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

# MCP server

> Choose hosted or local Pulse MCP, then set up your client.

Pulse MCP lets your agent parse documents, extract fields, split by topic and read tables
and charts. Tools use API V2 names and configs from the `pulse-ai` SDK.

## Choose how to connect

| | [Hosted MCP](#hosted-mcp) | [Local MCP](#local-mcp) |
| - | - | - |
| Where the MCP server runs | Managed by Pulse | On your computer |
| Documents it can access | Public or presigned URLs | URLs and files on your computer |
| Setup | Connect from your client | Install uv, sign in, then configure your client |

Both send documents to Pulse's API for processing and use your organization's credits.

## Hosted MCP

**Choose your client below.** The MCP server runs on Pulse, with no local installation.
Existing Pulse OAuth connections use browser sign-in. The API-key examples are for
manual connections when a Pulse OAuth connection is unavailable.

> [tab] Claude (web and desktop)
>
> 1. Open Claude's connector directory and select **Pulse → Connect**.
> 2. Sign in to Pulse and approve access.
> 3. Give Claude a public or presigned document URL.
>
> Claude handles authentication automatically.

> [tab] Claude Code
>
> Use your configured Pulse OAuth connection and sign in when prompted.
> For a manual connection, [create an API key](https://platform.runpulse.com) and run:
>
> ```bash theme={null}
> claude mcp add --transport http pulse https://mcp.runpulse.com/mcp \
>   --header "x-api-key: YOUR_PULSE_API_KEY"
> ```
>
> Run `/mcp` to check that Pulse is connected.

> [tab] Codex
>
> Browser sign-in with `pulse-mcp --login` is available through
> [local MCP setup](#local-mcp), which saves credentials for the server on your computer.
>
> For a manual connection to the **hosted server**, [create an API key](https://platform.runpulse.com)
> and add this to `~/.codex/config.toml`, then restart the MCP connection:
>
> ```toml theme={null}
> [mcp_servers.pulse]
> url = "https://mcp.runpulse.com/mcp"
> http_headers = { "x-api-key" = "YOUR_PULSE_API_KEY" }
> ```
>
> An existing Pulse OAuth connection handles sign-in instead of using these headers.

> [tab] VS Code
>
> For a manual connection, [create an API key](https://platform.runpulse.com) and add
> this to `.vscode/mcp.json`, then enable Pulse in the client's MCP controls:
>
> ```json theme={null}
> {
>   "servers": {
>     "pulse": {
>       "type": "http",
>       "url": "https://mcp.runpulse.com/mcp",
>       "headers": { "x-api-key": "YOUR_PULSE_API_KEY" }
>     }
>   }
> }
> ```
>
> See the [VS Code MCP configuration reference](https://code.visualstudio.com/docs/agents/reference/mcp-configuration).

> [tab] Cursor
>
> For a manual connection, [create an API key](https://platform.runpulse.com) and add
> this to `~/.cursor/mcp.json` or the project's `.cursor/mcp.json`:
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "pulse": {
>       "url": "https://mcp.runpulse.com/mcp",
>       "headers": { "x-api-key": "YOUR_PULSE_API_KEY" }
>     }
>   }
> }
> ```
>
> Enable Pulse in Cursor's MCP controls. See the [Cursor MCP guide](https://cursor.com/docs/mcp).

Keep API keys out of prompts and committed config. For OAuth client credentials or
other clients, see [custom hosted connections](#advanced-details).

## Local MCP

Your client launches the MCP server on your computer and can give it local file paths.
Local Parse uploads files directly to Pulse, up to 100 MB.

**1. Install uv**

On macOS or Linux:

```bash theme={null}
curl -LsSf https://astral.sh/uv/install.sh | sh
```

See the [uv installation guide](https://docs.astral.sh/uv/getting-started/installation/)
for Windows and other installation methods.

**2. Authenticate**

Run:

```bash theme={null}
uvx pulse-mcp==0.2.0 --login
```

This opens your browser to sign in to Pulse and approve access. It creates a device
API key, saves it to `~/.pulse/mcp.toml` with owner-only permissions (`0600`), and exits.

**3. Add to your MCP client**

Choose your client below. These configs use your saved login automatically;
leave `--login` out of the launch command.

> [tab] Claude Code
>
> Run:
>
> ```bash theme={null}
> claude mcp add pulse -- uvx pulse-mcp==0.2.0
> ```
>
> Run `/mcp` to check that Pulse is connected.

> [tab] Claude Desktop
>
> Open **Settings → Developer → Edit Config**, add this entry and restart Claude Desktop:
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "pulse": {
>       "command": "uvx",
>       "args": ["pulse-mcp==0.2.0"]
>     }
>   }
> }
> ```

> [tab] Codex
>
> Add this to `~/.codex/config.toml` and restart the MCP connection:
>
> ```toml theme={null}
> [mcp_servers.pulse]
> command = "uvx"
> args = ["pulse-mcp==0.2.0"]
> ```
>
> The server uses your saved login; no API key is needed in the Codex config.

> [tab] VS Code
>
> Add this to `.vscode/mcp.json`, then enable Pulse in the client's MCP controls:
>
> ```json theme={null}
> {
>   "servers": {
>     "pulse": {
>       "type": "stdio",
>       "command": "uvx",
>       "args": ["pulse-mcp==0.2.0"]
>     }
>   }
> }
> ```

> [tab] Cursor
>
> Add this to `~/.cursor/mcp.json` or the project's `.cursor/mcp.json`, then enable Pulse:
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "pulse": {
>       "command": "uvx",
>       "args": ["pulse-mcp==0.2.0"]
>     }
>   }
> }
> ```

The client must run on your computer and support launching a stdio server.
`PULSE_API_KEY` overrides saved login. See [credentials and troubleshooting](#advanced-details).

## Run a workflow

Give your agent a document and describe the output you want. For example:

> "Use Pulse to read this bank statement:
> [https://platform.runpulse.com/api/examples/637e5678-30b1-45fa-acc4-877f2d636419/pdf](https://platform.runpulse.com/api/examples/637e5678-30b1-45fa-acc4-877f2d636419/pdf).
> Return the account holder, statement period, ending balance and transactions as JSON.
> Include page references so I can check the values."

The agent chooses the Pulse tools and handles their inputs and job polling.
With local MCP, you can provide an absolute file path in place of the URL.

| What you want | Capability guide |
| - | - |
| Read document text and layout | [Parse](https://docs.runpulse.com/v2/parse.md) |
| Extract specific fields | [Extract](https://docs.runpulse.com/v2/extract.md) |
| Find sections by topic | [Split](https://docs.runpulse.com/v2/split.md) |
| Read tables | [Tables](https://docs.runpulse.com/v2/tables.md) |
| Read chart data | [Charts](https://docs.runpulse.com/v2/charts.md) |

For large documents or organizations that delete results on first read, see
[result limits and retention](#advanced-details).

## Advanced details

> [accordion] Authentication and troubleshooting
>
> `PULSE_API_KEY` overrides the login saved in `~/.pulse/mcp.toml`. If the device key
> expires, run `--login` again and restart the connection. Each login creates a new key;
> remove unused keys from **API Keys** in Pulse.
>
> **Custom hosted connections**
>
> When adding a custom server in your client, choose **Streamable HTTP** and enter
> this in its **Server URL** field:
>
> ```text theme={null}
> https://mcp.runpulse.com/mcp
> ```
>
> If your client asks for OAuth credentials, use the values provided by Pulse, then
> sign in and approve access. Manual connections accept `x-api-key: <key>` or
> `Authorization: Bearer <key>`.
>
> **Local API-key setup**
>
> To use an API key in place of browser login, set it in your client's environment:
>
> ```toml Codex: local API key theme={null}
> [mcp_servers.pulse]
> command = "uvx"
> args = ["pulse-mcp==0.2.0"]
> env = { "PULSE_API_KEY" = "YOUR_PULSE_API_KEY" }
> ```
>
> Keep keys out of prompts and committed config. A local package pin does not
> select the hosted server's version.
>
> **Check the connection**
>
> Ask your agent:
>
> > "Use only Pulse. List its available tools without processing documents."
>
> | Problem | Action |
> | - | - |
> | Hosted sign-in fails | Reconnect Pulse and approve access; check the OAuth client credentials if your setup requires them. |
> | API-key authentication fails | Check the key and restart the connection. A stale `PULSE_API_KEY` overrides local browser login. |
> | Local server exits | Run `--login` or set `PULSE_API_KEY`, then read the client's MCP log. |
> | `uvx` is missing | Install uv and restart your client so it picks up the updated `PATH`. |
> | V1/V2 SDK collision | Run `uvx pulse-mcp==0.2.0` in its isolated environment. |

> [accordion] Tool inputs and job handling
>
> | Tool | Inputs and purpose |
> | - | - |
> | `parse` | `file_url`, or local-only `file_path`: return Markdown, layout elements and a `parse_id`. |
> | `extract` | `parse_id` and `config.input_schema`: extract structured fields. |
> | `split` | `parse_id` and `config.topics`: find topic page ranges. |
> | `tables` | `parse_id`: extract merged tables as HTML, Markdown or JSON. |
> | `charts` | `parse_id`: read chart data and base64-encoded exports. |
> | `parse_batch` | `file_urls` or `folder_url`, optional `max_depth`: parse many documents. |
> | `pipeline` | `file_url` and a pipeline config: run Parse plus downstream steps. |
> | `get_job` | `job_id`: read status and completed results, or a batch/pipeline manifest. |
>
> Supply exactly one of `config` or `config_id` to job-starting tools. Config fields
> follow the V2 SDK; unknown fields are forwarded for engine validation, so typos
> return errors. For example, Tables accepts `config={"format":["json"],"effort":"high"}`.
>
> Hosted Parse requires a URL. Local Parse uploads files directly, up to 100 MB;
> chat attachments are not local file paths.
>
> **Parse, then extract**
>
> ```json Parse tool arguments theme={null}
> {
>   "file_url": "https://example.com/invoice.pdf",
>   "config": {"model": "ultra-2"},
>   "include_result": false
> }
> ```
>
> Wait for completion using `get_job` with `include_result=false`, then reuse the `parse_id`:
>
> ```json Extract tool arguments theme={null}
> {
>   "parse_id": "parse-…",
>   "config": {
>     "input_schema": {
>       "type": "object",
>       "properties": {"total": {"type": "number"}}
>     }
>   }
> }
> ```
>
> For topic-specific extraction, use `split` to find pages, then pass them as
> `extract.config.page_range` with the original `parse_id`.
>
> See [Parse](https://docs.runpulse.com/v2/parse.md), [Extract](https://docs.runpulse.com/v2/extract.md), [Split](https://docs.runpulse.com/v2/split.md),
> [Tables](https://docs.runpulse.com/v2/tables.md), [Charts](https://docs.runpulse.com/v2/charts.md), [Batch](https://docs.runpulse.com/v2/batch.md) and
> [Pipelines](https://docs.runpulse.com/v2/pipelines.md) for full config and result shapes.
>
> **Asynchronous jobs**
>
> Tools submit asynchronously and poll for up to 15 seconds by default. Set
> `async_=true` to return immediately; `parse_batch` always does. Continue with
> `get_job(job_id=...)`. Completed output is under `result`.
> The polling budget does not cap submission or individual HTTP request time.
>
> Pipeline manifests expose step IDs while processing. Read each completed step's
> output with `get_job` using its own ID.
>
> Polling and result-read errors retain the job ID and any last known status, with
> `isError=true` on the MCP call. When `poll_with` is `get_job`, retry that ID.
> Permanent errors, such as expired results, omit the retry hint.

> [accordion] Result limits and retention
>
> Full V2 results, including Markdown and elements, are returned inline. They can
> exceed a client's size limit; there is no automatic download-link fallback.
> Use a smaller `config.page_range`, or retrieve and save large results through the SDK/API.
>
> > [!WARNING]
> >
> > First-read deletion consumes a result even if the MCP client rejects the response.
> > Before chaining downstream steps, use `include_result=false` on `parse` and its
> > `get_job` polls. Read the parse result after those steps finish. For large results,
> > save the first read through the SDK/API instead of relying on MCP delivery.

> [accordion] Upgrading from pulse-mcp 0.1
>
> Reconnect to refresh tools, and update workflows:
>
> | 0.1 | 0.2 |
> | - | - |
> | `extract` | `parse` |
> | `apply_schema` | `extract` |
> | `split_document` | `split` |
> | `extract_tables` | `tables` |
> | `extract_charts` | `charts` |
> | `batch_extract` | `parse_batch` |
> | `run_pipeline` | `pipeline` |
>
> Use V2 `parse_id` values and `config`/`config_id`. V1 job IDs and saved pipelines
> are incompatible; old parameter aliases and `generate_schema` are removed.
> Pin `pulse-mcp==0.1.4` locally to retain V1 tools.


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