Connecting a client

There are two ways to run the Pulse MCP server. Both expose the same tools and authenticate with the same Pulse API key, but their setup differs, so pick one before you configure a client. Every client section below shows a config for each.

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	uv (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`

The local configs below launch the server with uvx, which downloads pulse-mcp from PyPI on first run; there is no separate install step. 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.1"].

Authentication

Create an API key

Generate a key in the Pulse Platform under API Keys. Copy it immediately; it’s shown only once.

Add it to your client config

Drop the key into the client’s MCP configuration as shown below.

Restart the client

Most clients pick up MCP servers on restart. The Pulse tools then appear in the tool list.

How the key reaches Pulse depends on the connection. Hosted: every request carries the key as either header:

x-api-key: YOUR_PULSE_API_KEY

Authorization: Bearer YOUR_PULSE_API_KEY

Local: the server reads the key from the PULSE_API_KEY environment variable, normally set in the env block of the client config. Alternatively, create ~/.pulse/config.toml, which is 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"

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.

Codex

Add Pulse to ~/.codex/config.toml (or a project-scoped .codex/config.toml):

Hosted
Local

~/.codex/config.toml

[mcp_servers.pulse]
url = "https://mcp.runpulse.com/mcp"
http_headers = { "x-api-key" = "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 to load the server; the pulse tools will then be available to the agent.

Claude Code

Add the server from the terminal:

Hosted
Local

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

Or add it to a project’s .mcp.json:

.mcp.json

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

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

Or add it to a project’s .mcp.json:

.mcp.json

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

Run /mcp inside Claude Code to verify the connection.

Claude Desktop

Edit your claude_desktop_config.json:

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

Claude Desktop speaks stdio natively, so the local server is the most direct connection. Reaching the hosted endpoint instead goes through the mcp-remote bridge, which requires Node.js.

Local
Hosted (mcp-remote)

claude_desktop_config.json

{
  "mcpServers": {
    "pulse": {
      "command": "uvx",
      "args": ["pulse-mcp@latest"],
      "env": {
        "PULSE_API_KEY": "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, then look for the Pulse tools under the connectors (plug) icon.

VS Code (GitHub Copilot)

Add Pulse to .vscode/mcp.json in your workspace. Note VS Code uses the servers key:

Hosted
Local

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

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

The inputs block prompts for the key once and keeps it out of the committed file. Open the Chat view in Agent mode to use the Pulse tools.

Any MCP client

Hosted: any client that speaks Streamable HTTP. 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`)

Local: any client that can launch a stdio server. 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. 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.

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 under Authentication, 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, 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.

Connecting a client

Hosted or local?

Hosted

Local

Authentication

Codex

Claude Code

Claude Desktop

VS Code (GitHub Copilot)

Any MCP client

Verify the connection

Troubleshooting

Next steps

Tools & workflows

MCP overview

​Hosted or local?

Hosted

Local

​Authentication

​Codex

​Claude Code

​Claude Desktop

​VS Code (GitHub Copilot)

​Any MCP client

​Verify the connection

​Troubleshooting

​Next steps

Tools & workflows

MCP overview

Hosted or local?

Authentication

Codex

Claude Code

Claude Desktop

VS Code (GitHub Copilot)

Any MCP client

Verify the connection

Troubleshooting

Next steps