Connecting a client

The Pulse MCP server gives your agent document tools (parse, schema, split, tables, and more) that it calls like any other MCP tool. You can run it two ways, and they install and authenticate differently:

Hosted: your client connects to https://mcp.runpulse.com/mcp over Streamable HTTP. Nothing to install for most clients.
Local: your client launches the pulse-mcp package on your machine over stdio. A one-time uv install is required, and agents can read documents straight from disk.

Both expose the same tools and authenticate with the same Pulse API key. Pick a path below; each tab under Set up your client is self-contained, with its own prerequisites and a config for every client.

Quick start

For the fastest copy-paste into a coding agent, start here. Replace YOUR_PULSE_API_KEY with a key from the Pulse Platform.

claude mcp add --transport http pulse https://mcp.runpulse.com/mcp \
  --header "x-api-key: YOUR_PULSE_API_KEY"

claude mcp add pulse --env PULSE_API_KEY=YOUR_PULSE_API_KEY -- uvx pulse-mcp@latest

[mcp_servers.pulse]
url = "https://mcp.runpulse.com/mcp"
http_headers = { "x-api-key" = "YOUR_PULSE_API_KEY" }

{
  "mcpServers": {
    "pulse": {
      "type": "http",
      "url": "https://mcp.runpulse.com/mcp",
      "headers": { "x-api-key": "YOUR_PULSE_API_KEY" }
    }
  }
}

For every other client, the local server, and how to verify the connection, read on.

Hosted or local?

Hosted

Point your client at https://mcp.runpulse.com/mcp over Streamable HTTP. Nothing to install; the API key travels as a request header. The right default for most setups.

Local

Run the pulse-mcp package on your machine over stdio; the API key comes from the server’s environment. Pick this when agents should read documents straight from your disk: locally, extract also accepts a file_path (see document inputs).

	Hosted	Local
Transport	Streamable HTTP	stdio
Connect via	`https://mcp.runpulse.com/mcp`	`uvx pulse-mcp@latest`
Install	Nothing (Claude Desktop needs Node.js)	uv, which provides `uvx`
API key	`x-api-key` or `Authorization: Bearer` header	`PULSE_API_KEY` env var or `~/.pulse/config.toml`
Local files	No: URL inputs only	Yes: `extract` takes a `file_path`

Create your API key

Both setups authenticate with a Pulse API key.

Generate a key

In the Pulse Platform, open API Keys and create a key. Copy it immediately; it’s shown only once.

Keep it handy

You’ll paste it into your client config in the setup section below. The same key works for both the hosted and local servers.

Treat your API key like a password. Prefer environment variables or your client’s secret inputs over committing keys into a config file that lands in version control.

Set up your client

Pick a path with the tabs below. Each one is self-contained: a step-by-step prerequisite, how the API key is passed, and a numbered setup for every client. Throughout, replace YOUR_PULSE_API_KEY with the key you created above. This is a Pulse key from your Pulse dashboard — not a Claude or OpenAI key.

Hosted (no install)
Local (uvx)

The hosted server runs on Pulse’s infrastructure. Your client connects directly to https://mcp.runpulse.com/mcp over Streamable HTTP and sends your API key as a request header. Your existing credits and limits apply to every call.

The hosted server runs in Pulse’s cloud, so it cannot read files from your local disk. Pass documents as public or pre-signed URLs, or use the Local tab, where extract also accepts a file_path.

Prerequisites (hosted)

Most clients speak HTTP natively and need nothing installed — Codex, Claude Code, VS Code, and the MCP Inspector all connect directly, so you can jump straight to your client below.The one exception is Claude Desktop (and any stdio-only client), which reaches the hosted endpoint through the mcp-remote bridge. That bridge needs Node.js — its check-first install is Step 1 of the Claude Desktop section below, so there’s nothing to set up in advance.

Send the API key

Every hosted request carries your key as one of these headers. The client snippets below set it for you, so this is just for reference:

x-api-key: YOUR_PULSE_API_KEY

Authorization: Bearer YOUR_PULSE_API_KEY

Codex (hosted)

Open your Codex config

Edit ~/.codex/config.toml (or a project-scoped .codex/config.toml).

Add the Pulse server

Paste this block, replacing YOUR_PULSE_API_KEY:

~/.codex/config.toml

[mcp_servers.pulse]
url = "https://mcp.runpulse.com/mcp"
http_headers = { "x-api-key" = "YOUR_PULSE_API_KEY" }

Restart Codex

Reopen Codex to load the server. The pulse tools are now available to the agent.

Claude Code (hosted)

Add the server

From your terminal, run:

claude mcp add --transport http pulse https://mcp.runpulse.com/mcp \
  --header "x-api-key: YOUR_PULSE_API_KEY"

Prefer a file you can commit? Add it to a project’s .mcp.json instead:

.mcp.json

{
  "mcpServers": {
    "pulse": {
      "type": "http",
      "url": "https://mcp.runpulse.com/mcp",
      "headers": {
        "x-api-key": "YOUR_PULSE_API_KEY"
      }
    }
  }
}

Verify the connection

Run /mcp inside Claude Code and confirm pulse is listed.

Claude Desktop (hosted)

Claude Desktop speaks stdio natively, so it reaches the hosted endpoint through the mcp-remote bridge, which runs on Node.js.

Check for Node.js (provides npx)

The bridge is launched with npx, which ships with Node.js. Check whether you already have it:

npx --version

If that prints a version number, skip Step 2.

Install Node.js (only if Step 1 failed)

Download and run the LTS installer from nodejs.org. Then close and reopen your terminal so PATH updates, and run npx --version again to confirm.

Open your config file

In Claude Desktop: Settings → Developer → Edit Config. That opens claude_desktop_config.json (and creates it if missing). To open it manually instead:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the Pulse entry

If the file is empty, paste this whole block. If it already has an mcpServers block, paste just the "pulse": { ... } part inside it. Replace YOUR_PULSE_API_KEY:

claude_desktop_config.json

{
  "mcpServers": {
    "pulse": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote", "https://mcp.runpulse.com/mcp",
        "--header", "x-api-key:${PULSE_API_KEY}"
      ],
      "env": {
        "PULSE_API_KEY": "YOUR_PULSE_API_KEY"
      }
    }
  }
}

The ${PULSE_API_KEY} reference (no space after the colon) keeps the key in the env block so the header is passed cleanly by mcp-remote.

Restart Claude Desktop

Fully quit Claude Desktop and reopen it, then look for the Pulse tools under the connectors (plug) icon.

On Claude (web and desktop) you can skip this manual setup entirely and add Pulse from the connector directory with one click — no API key and no Node.js. See Claude Connector.

VS Code (hosted)

Open your workspace MCP config

Edit .vscode/mcp.json in your workspace (create it if it doesn’t exist). Note VS Code uses the servers key, not mcpServers.

Add the Pulse server

Paste this block. The inputs section prompts for your key once and keeps it out of the committed file:

.vscode/mcp.json

{
  "servers": {
    "pulse": {
      "type": "http",
      "url": "https://mcp.runpulse.com/mcp",
      "headers": {
        "x-api-key": "${input:pulse-api-key}"
      }
    }
  },
  "inputs": [
    {
      "id": "pulse-api-key",
      "type": "promptString",
      "description": "Pulse API key",
      "password": true
    }
  ]
}

Start using the tools

Open the Chat view in Agent mode. VS Code prompts for your API key the first time, then the Pulse tools are available.

Any client (hosted)

Any client that speaks Streamable HTTP can connect. Configure it with:

Setting	Value
Transport	Streamable HTTP
URL	`https://mcp.runpulse.com/mcp`
Header	`x-api-key: YOUR_PULSE_API_KEY` (or `Authorization: Bearer YOUR_PULSE_API_KEY`)

The local server runs the pulse-mcp package on your own machine and talks to your client over stdio. It exposes the same tools as the hosted server, plus the agent can read documents straight from disk (extract accepts a file_path).

Prerequisites (local): install uv

pulse-mcp is launched with uvx, which comes with uv, a fast Python tool manager from Astral. This is the only thing you install — and only once, no matter how many clients you connect.

You do not need Python or pip first. uv is a single self-contained binary, and uvx automatically downloads a managed Python and the pulse-mcp package the first time a client launches it — so there’s no separate “install pulse-mcp” step.

Check if uv is installed

uvx --version

If that prints a version number, skip Step 2. (uvx installs automatically with uv.)

Install uv (only if Step 1 failed)

Run the standalone installer — it needs no Python or pip:

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

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Then close and reopen your terminal (the installer updates your PATH) and run uvx --version again to confirm.

pulse-mcp@latest re-resolves the newest release on every launch. To upgrade on your own schedule, pin a version instead: "args": ["pulse-mcp==0.1.2"].

Provide the API key

The local server reads your key from the PULSE_API_KEY environment variable, set in the env block of each client config below.Alternatively, create ~/.pulse/config.toml, handy when several MCP clients share one machine. The environment variable wins when both are set:

~/.pulse/config.toml

api_key = "YOUR_PULSE_API_KEY"

Codex (local)

Open your Codex config

Edit ~/.codex/config.toml (or a project-scoped .codex/config.toml).

Add the Pulse server

Paste this block, replacing YOUR_PULSE_API_KEY:

~/.codex/config.toml

[mcp_servers.pulse]
command = "uvx"
args = ["pulse-mcp@latest"]
env = { "PULSE_API_KEY" = "YOUR_PULSE_API_KEY" }

Restart Codex

Reopen Codex to load the server. The pulse tools are now available to the agent.

Claude Code (local)

Add the server

From your terminal, run:

claude mcp add pulse --env PULSE_API_KEY=YOUR_PULSE_API_KEY -- uvx pulse-mcp@latest

Prefer a file you can commit? Add it to a project’s .mcp.json instead:

.mcp.json

{
  "mcpServers": {
    "pulse": {
      "command": "uvx",
      "args": ["pulse-mcp@latest"],
      "env": {
        "PULSE_API_KEY": "YOUR_PULSE_API_KEY"
      }
    }
  }
}

Verify the connection

Run /mcp inside Claude Code and confirm pulse is listed.

Claude Desktop (local)

Claude Desktop speaks stdio natively, so the local server is the most direct connection — no bridge needed.

Open your config file

In Claude Desktop: Settings → Developer → Edit Config. That opens claude_desktop_config.json (and creates it if missing). To open it manually instead:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the Pulse entry

If the file is empty, paste this whole block. If it already has an mcpServers block, paste just the "pulse": { ... } part inside it. Replace YOUR_PULSE_API_KEY:

claude_desktop_config.json

{
  "mcpServers": {
    "pulse": {
      "command": "uvx",
      "args": ["pulse-mcp@latest"],
      "env": {
        "PULSE_API_KEY": "YOUR_PULSE_API_KEY"
      }
    }
  }
}

Restart Claude Desktop

Fully quit Claude Desktop and reopen it, then look for the Pulse tools under the connectors (plug) icon.

VS Code (local)

Open your workspace MCP config

Edit .vscode/mcp.json in your workspace (create it if it doesn’t exist). Note VS Code uses the servers key, not mcpServers.

Add the Pulse server

Paste this block. The inputs section prompts for your key once and keeps it out of the committed file:

.vscode/mcp.json

{
  "servers": {
    "pulse": {
      "type": "stdio",
      "command": "uvx",
      "args": ["pulse-mcp@latest"],
      "env": {
        "PULSE_API_KEY": "${input:pulse-api-key}"
      }
    }
  },
  "inputs": [
    {
      "id": "pulse-api-key",
      "type": "promptString",
      "description": "Pulse API key",
      "password": true
    }
  ]
}

Start using the tools

Open the Chat view in Agent mode. VS Code prompts for your API key the first time, then the Pulse tools are available.

Any client (local)

Any client that can launch a stdio server can connect. Configure it with:

Setting	Value
Transport	stdio
Command	`uvx`, args `["pulse-mcp@latest"]`
Environment	`PULSE_API_KEY=YOUR_PULSE_API_KEY`

Verify the connection

Use the official MCP Inspector to test the server directly, independent of any client. (The Inspector is launched with npx, so it needs Node.js; install it as shown in the Hosted tab under Claude Desktop if you don’t have it.) Hosted:

npx @modelcontextprotocol/inspector

In the Inspector UI:

Transport: Streamable HTTP
URL: https://mcp.runpulse.com/mcp
Header: x-api-key = YOUR_PULSE_API_KEY

Local (the Inspector launches the server itself):

PULSE_API_KEY=YOUR_PULSE_API_KEY npx @modelcontextprotocol/inspector uvx pulse-mcp@latest

Connect, then open the Tools tab, where you should see extract, apply_schema, and the rest of the Pulse tools.

Troubleshooting

Authentication failed: missing or invalid API key

The request reached Pulse without a valid key. Confirm the x-api-key header (hosted) or the PULSE_API_KEY environment variable (local) is set in your client config, that the value matches a live key in the Platform, and that you restarted the client after editing the config.

Tools don't appear in my client

Most clients only load MCP servers at startup, so fully restart the client after editing its config. If they still don’t show, validate the JSON (a trailing comma or wrong key name like mcpServers vs. servers is the usual culprit) and test the endpoint with the MCP Inspector.

'uvx: command not found' or 'npx: command not found'

The required tool isn’t installed or isn’t on your PATH. Install uv (Local tab) for uvx, or Node.js (Hosted tab, under Claude Desktop) for npx. After installing, reopen your terminal (and restart the MCP client) so the updated PATH takes effect, then re-run the verification command.

The local server exits immediately

pulse-mcp exits at launch when it can’t find an API key and prints setup instructions to stderr, which your client surfaces in its MCP logs. Set PULSE_API_KEY in the config’s env block, or create ~/.pulse/config.toml as shown in the Local tab, then restart the client.

The agent can't read a local file

The hosted server processes documents by URL, not from your local disk. Either run the local server (Local tab), where extract accepts a file_path, or upload the file somewhere the server can reach it and pass a public or pre-signed file_url. See document inputs.

The agent says the result is too large to show

Large results are saved to a download link instead of being returned inline. The agent can’t open that link itself. Paste the URL back into the chat (or open it in your browser) and the agent will read it. See large results.

Payment required / out of credits

Your Pulse plan limit was reached. Check usage and upgrade in the Platform, or contact support.

Start Here

Agent Tools

Core Concepts

Security & Compliance

Help

Connecting a client

Quick start

Hosted or local?

Hosted

Local

Create your API key

Set up your client

Prerequisites (hosted)

Send the API key

Codex (hosted)

Claude Code (hosted)

Claude Desktop (hosted)

VS Code (hosted)

Any client (hosted)

Prerequisites (local): install uv

Provide the API key

Codex (local)

Claude Code (local)

Claude Desktop (local)

VS Code (local)

Any client (local)

Verify the connection

Troubleshooting

Next steps

Tools & workflows

MCP overview

​Quick start

​Hosted or local?

Hosted

Local

​Create your API key

​Set up your client

​Prerequisites (hosted)

​Send the API key

​Codex (hosted)

​Claude Code (hosted)

​Claude Desktop (hosted)

​VS Code (hosted)

​Any client (hosted)

​Prerequisites (local): install uv

​Provide the API key

​Codex (local)

​Claude Code (local)

​Claude Desktop (local)

​VS Code (local)

​Any client (local)

​Verify the connection

​Troubleshooting

​Next steps

Tools & workflows

MCP overview

Quick start

Hosted or local?

Create your API key

Set up your client

Prerequisites (hosted)

Send the API key

Codex (hosted)

Claude Code (hosted)

Claude Desktop (hosted)

VS Code (hosted)

Any client (hosted)

Prerequisites (local): install uv

Provide the API key

Codex (local)

Claude Code (local)

Claude Desktop (local)

VS Code (local)

Any client (local)

Verify the connection

Troubleshooting

Next steps