MCP server

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	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.

Claude (web and desktop)
Claude Code
Codex
VS Code
Cursor

Open Claude’s connector directory and select Pulse → Connect.
Sign in to Pulse and approve access.
Give Claude a public or presigned document URL.

Claude handles authentication automatically.

Use your configured Pulse OAuth connection and sign in when prompted. For a manual connection, create an API key and run:

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.

Browser sign-in with pulse-mcp --login is available through local MCP setup, which saves credentials for the server on your computer.For a manual connection to the hosted server, create an API key and add this to ~/.codex/config.toml, then restart the MCP connection:

[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.

For a manual connection, create an API key and add this to .vscode/mcp.json, then enable Pulse in the client’s MCP controls:

{
  "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.

For a manual connection, create an API key and add this to ~/.cursor/mcp.json or the project’s .cursor/mcp.json:

{
  "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.

Keep API keys out of prompts and committed config. For OAuth client credentials or other clients, see custom hosted connections.

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.

Install uv

On macOS or Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

See the uv installation guide for Windows and other installation methods.

Authenticate

Run:

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.

Add to your MCP client

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

Claude Code
Claude Desktop
Codex
VS Code
Cursor

Run:

claude mcp add pulse -- uvx pulse-mcp==0.2.0

Run /mcp to check that Pulse is connected.

Open Settings → Developer → Edit Config, add this entry and restart Claude Desktop:

{
  "mcpServers": {
    "pulse": {
      "command": "uvx",
      "args": ["pulse-mcp==0.2.0"]
    }
  }
}

Add this to ~/.codex/config.toml and restart the MCP connection:

[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.

Add this to .vscode/mcp.json, then enable Pulse in the client’s MCP controls:

{
  "servers": {
    "pulse": {
      "type": "stdio",
      "command": "uvx",
      "args": ["pulse-mcp==0.2.0"]
    }
  }
}

Add this to ~/.cursor/mcp.json or the project’s .cursor/mcp.json, then enable Pulse:

{
  "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.

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. 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
Extract specific fields	Extract
Find sections by topic	Split
Read tables	Tables
Read chart data	Charts

For large documents or organizations that delete results on first read, see result limits and retention.

Advanced details

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 connectionsWhen adding a custom server in your client, choose Streamable HTTP and enter this in its Server URL field:

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 setupTo use an API key in place of browser login, set it in your client’s environment:

Codex: local API key

[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 connectionAsk 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.

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

Parse tool arguments

{
  "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:

Extract tool arguments

{
  "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, Extract, Split, Tables, Charts, Batch and Pipelines for full config and result shapes.Asynchronous jobsTools 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.

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.

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.

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.

Get started

Endpoints

Run at scale

Essentials

Agents

Account

Choose how to connect

Hosted MCP

Local MCP

Run a workflow

Advanced details