> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pre.dev/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Agents: start with https://docs.pre.dev/agents.md, which has complete recipes, plan access, polling rules, errors and limits.
> Authenticate with the workspace API key (pdk_…) from Integrations → Built-in, sent as Authorization: Bearer <key>.
> REST API: https://api.pre.dev (OpenAPI: https://docs.pre.dev/api-reference/openapi.json). AI Gateway: https://api.pre.dev/v1, OpenAI-compatible (OpenAPI: https://docs.pre.dev/api-reference/ai-gateway.openapi.json).
> pre.dev MCP server: https://api.pre.dev/mcp. Search these docs over MCP at https://docs.pre.dev/mcp.

# MCP tool reference

> The eight primary pre.dev tools, exact input names, result formats, and deprecated aliases.

The pre.dev MCP server is **`https://api.pre.dev/mcp`**, over Streamable HTTP. It runs pre.dev's specification and browser tools. Searching this documentation is a separate MCP server, `https://docs.pre.dev/mcp`, which needs no key.

Connect once to use specification generation, project plans and browser automation. [Setup instructions](/architect-agent/mcp-setup) cover authentication and client configuration.

Call **`tools/list`** after initialization for the live input schemas. `GET /mcp/info` is a human-readable service inventory; it is not the protocol's tool-discovery method.

## Tool inventory

| Tool | Purpose | Result |
| - | - | - |
| `fast_spec` | Generate a concise specification | Text with artifact links or a `get_spec` handoff |
| `deep_spec` | Generate a detailed specification | Text with artifact links or a `get_spec` handoff |
| `get_spec` | Retrieve a specification and its status | Text and, on success, `structuredContent` |
| `list_specs` | Paginated specification history | Text and, for a nonempty page, `structuredContent` |
| `get_plan` | A project's verified plan | Markdown text and `structuredContent` |
| `browser_agent` | Run browser tasks | Text summary or an async run ID |
| `browser_agent_get` | Retrieve browser task results | JSON text and `structuredContent` |
| `browser_agent_list` | Paginated browser history | Text and `structuredContent` |

Generation and browser execution consume credits. Retrieval and listing do not launch new work. The server marks browser execution as potentially destructive because a task can click, submit forms, or change data on external sites.

<Note>
  The `browser_agent` tools run tasks on pre.dev's cloud browsers. To let your coding agent drive the Chrome on your own computer, with your profiles and logins, use [Browser Agents Local](/browser-agents/local): a separate, open-source MCP server that runs on your machine and provides its own `chrome_*` tools.
</Note>

## fast\_spec and deep\_spec

Both tools accept the same parameters:

| Parameter | Required | Type | Meaning |
| - | - | - | - |
| `executiveSummary` | Yes | String, minimum 10 characters | What to specify |
| `existingContext` | No | String | Existing code, stack, constraints, and architecture as text |
| `docURLs` | No | Array of URL strings | Reference documentation |

```json theme={null}
{
  "executiveSummary": "Add CSV exports to the reporting dashboard.",
  "existingContext": "An existing TypeScript app with a reports API and organization-scoped access.",
  "docURLs": ["https://www.rfc-editor.org/rfc/rfc4180"]
}
```

These MCP tools do **not** take REST's `input`, `currentContext`, `file`, or `async` fields. They may return before generation finishes. If the result provides a specification ID, call `get_spec` until its status is `completed` or `failed`.

Generation results are text, not the REST `SpecResponse` JSON envelope. A progress notification reaching 100 does not replace a terminal status check.

## get\_spec

```json theme={null}
{ "specId": "507f1f77bcf86cd799439011" }
```

`specId` is required. Use the ID returned by generation or listing. A successful `structuredContent` contains `specId` and `status`; it may also include `endpoint`, `created`, `executionTimeMs`, `progress`, `specUrl`, `predevUrl`, `output`, `errorMessage`, and `creditsUsed`, the credits recorded for the spec's project so far.

`output` is specification Markdown, preferring the coding-agent variant. Status is `pending`, `processing`, `completed`, `failed`, or `unknown`. Optional values may be absent while generation is running.

A `completed` result also carries `plan` when its project has one: the project's verified plan (the same object `get_plan` returns), and the text ends with the plan as Markdown.

## list\_specs

| Parameter | Type | Default | Values |
| - | - | - | - |
| `limit` | Number | `20` | `1`–`100` |
| `skip` | Number | `0` | Zero or greater |
| `endpoint` | String | All | `fast_spec`, `deep_spec` |
| `status` | String | All | `pending`, `processing`, `completed`, `failed` |

For nonempty pages, `structuredContent` contains `specs`, `total`, `hasMore`, `skip`, and `limit`. Each entry uses **`specId`**, not REST's `_id`. Use `get_spec` for the full body. An empty page returns a text-only result.

There is no `find_specs` MCP tool; use [REST search](/architect-agent/api/find-specs).

## get\_plan

```json theme={null}
{ "specId": "507f1f77bcf86cd799439011" }
```

Pass exactly one of `specId` (from generation or listing) or `projectId`. The result is the project's verified plan: what the app is for, each feature's status from pre.dev's checks, progress, what is left, whether it is ready to launch with a plain fix for each open item, where screens, API routes and stored data live in the code (file and line), and what the last change did.

The text content is the plan as Markdown, written for a coding agent to read before working on the project. `structuredContent` contains `projectId`, `specId`, `plan` and `markdown`; `plan` has the same fields as the [REST plan](/architect-agent/api/get-plan) and is null while the project has nothing planned or built yet.

| Feature status | Meaning |
| - | - |
| `works` | A check of this feature passed at the current code |
| `built_not_checked` | The code is there; nothing has proven it yet |
| `changed_since_check` | Its files changed after its check passed |
| `needs_a_look` | Its check failed the last time it ran |
| `not_working` | Its check keeps failing |
| `in_progress`, `planned` | Not built yet |
| `out_of_scope` | Set outside the project's scope; listed, not counted |
| `removed` | Taken out because the owner asked; listed, not counted |

An organization key reads its organization's projects; any other key reads only its own. Another account's ID returns an error result (`isError: true`), the same as an ID that does not exist. Retrieval does not use credits.

## browser\_agent

| Parameter | Required | Type | Meaning |
| - | - | - | - |
| `tasks` | Yes | Nonempty array | One object per browser task |
| `concurrency` | No | Number, `1`–`20` | Parallel task allowance within this run; default `5` |
| `async` | No | Boolean | Return the run ID without waiting for results |

Each task supports:

| Field | Type | Meaning |
| - | - | - |
| `url` | String, required | Starting URL |
| `instruction` | String | Goal to accomplish |
| `input` | Object of string values | Form fields or other task inputs |
| `output` | JSON Schema | Expected output shape |
| `successCondition` | String | Natural-language completion condition |
| `mode` | `auto`, `extract`, `agent` | Automatic routing, schema extraction, or goal-driven navigation |
| `maxSteps` | Integer, `1`–`50` | Planning-iteration budget |
| `maxDurationSeconds` | Integer, `5`–`600` | Per-task execution budget in seconds |

Limits apply to each task. Set explicit budgets for long flows; defaults can vary by task and execution mode. Your account's [in-flight limit](/browser-agents/api/queue-status) also applies to the whole submission.

Synchronous execution returns a **text summary**, which truncates task data. Retrieve `browser_agent_get` for full structured results. Async execution returns the ID in text so you can poll it.

The MCP tool has no `stream` or `idempotencyKey` input and no cancellation operation; closing the client does not stop browser work. It emits live notifications during synchronous execution when the client supports them. The same credit, batch-size, and account in-flight gates apply as in REST.

### Extract structured data

```json theme={null}
{
  "tasks": [{
    "url": "https://example.com",
    "instruction": "Extract the main page heading.",
    "output": {
      "type": "object",
      "properties": { "heading": { "type": "string" } },
      "required": ["heading"]
    },
    "mode": "extract",
    "maxSteps": 10,
    "maxDurationSeconds": 120
  }]
}
```

The tool returns a text summary and run ID. Call `browser_agent_get` with that ID for the complete `structuredContent`, including `results[i].data`.

### Run a longer workflow

For a multi-step workflow, use `mode: "agent"`, give a concrete completion condition, and submit asynchronously:

```json theme={null}
{
  "tasks": [{
    "url": "https://news.ycombinator.com/newest",
    "instruction": "Open the next page using More, then collect the first five story titles and links.",
    "successCondition": "The next page has been opened and five stories from that page have been collected.",
    "output": {
      "type": "object",
      "properties": {
        "stories": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "title": { "type": "string" },
              "url": { "type": "string" }
            },
            "required": ["title", "url"]
          },
          "minItems": 5,
          "maxItems": 5
        }
      },
      "required": ["stories"]
    },
    "mode": "agent",
    "maxSteps": 20,
    "maxDurationSeconds": 180
  }],
  "async": true
}
```

Save the ID from the returned text, then call `browser_agent_get` every few seconds. Stop when batch `status` becomes `completed` or `failed`, and inspect each task's uppercase status. A completed batch does not mean every task succeeded.

## browser\_agent\_get

```json theme={null}
{ "id": "507f1f77bcf86cd799439011", "includeEvents": false }
```

`id` is required; `includeEvents` is optional and defaults to false. `structuredContent` contains the [browser run](/browser-agents/api/task-status), including individual task outcomes and extracted data. Set `includeEvents` to true to retrieve timelines and any available screenshots. During synchronous execution, clients with logging support also receive `notifications/message`; these are MCP notification envelopes, not REST SSE frames, and heavy event data may be shortened.

## browser\_agent\_list

| Parameter | Type | Default | Values |
| - | - | - | - |
| `limit` | Number | `20` | `1`–`100` |
| `skip` | Number | `0` | Use a nonnegative offset |
| `status` | String | All | `processing`, `completed` |

The structured result contains `total` and `batches`. Each batch has `id`, `status`, `total`, `completed`, and `totalCreditsUsed`. Unlike REST listing, this tool does **not** return `hasMore`; compare your offset and page length with `total`.

## Notifications and errors

The server sends `notifications/message` with `params: { level, logger, data }`. Browser messages contain a task index and event details; large screenshot and DOM values can be elided. Specification messages report phases such as `start`, `generating`, and `packaging`.

To receive `notifications/progress`, include a `progressToken` in the `tools/call` request's `_meta`:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "browser_agent",
    "arguments": {
      "tasks": [{ "url": "https://example.com", "instruction": "Read the page heading." }]
    },
    "_meta": { "progressToken": "heading-run" }
  }
}
```

Browser failures return `isError: true` when the tool call itself fails. Specification tools can return an error in text without `isError`; inspect the content and retrieve the specification status where an ID is available. Disconnecting or cancelling notification delivery does not cancel the underlying browser run.

## Deprecated aliases

| Older name | Current name |
| - | - |
| `browser_task` | `browser_agent` |
| `browser_task_get` | `browser_agent_get` |
| `browser_task_list` | `browser_agent_list` |

The aliases remain registered for compatibility. Use the current names in new integrations. Credits, queue status, and live browser URL retrieval are available through REST rather than dedicated MCP tools.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.