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

# Connecting a client

> Set up the Pulse MCP server, hosted or local, in Codex, Claude Desktop, Claude Code, VS Code, or any MCP-compatible 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`](https://pypi.org/project/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](/mcp/tools) and authenticate with the same Pulse API key. Pick
a path below; each tab under [Set up your client](#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](https://platform.runpulse.com).

<CodeGroup>
  ```bash Claude Code (hosted) theme={null}
  claude mcp add --transport http pulse https://mcp.runpulse.com/mcp \
    --header "x-api-key: YOUR_PULSE_API_KEY"
  ```

  ```bash Claude Code (local) theme={null}
  claude mcp add pulse --env PULSE_API_KEY=YOUR_PULSE_API_KEY -- uvx pulse-mcp@latest
  ```

  ```toml Codex (hosted) theme={null}
  [mcp_servers.pulse]
  url = "https://mcp.runpulse.com/mcp"
  http_headers = { "x-api-key" = "YOUR_PULSE_API_KEY" }
  ```

  ```json Any HTTP client (hosted) theme={null}
  {
    "mcpServers": {
      "pulse": {
        "type": "http",
        "url": "https://mcp.runpulse.com/mcp",
        "headers": { "x-api-key": "YOUR_PULSE_API_KEY" }
      }
    }
  }
  ```
</CodeGroup>

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

## Hosted or local?

<CardGroup cols={2}>
  <Card title="Hosted" icon="cloud" href="#set-up-your-client">
    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.
  </Card>

  <Card title="Local" icon="laptop-code" href="#set-up-your-client">
    Run the [`pulse-mcp`](https://pypi.org/project/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](/mcp/tools#document-inputs)).
  </Card>
</CardGroup>

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

<Steps>
  <Step title="Generate a key">
    In the [Pulse Platform](https://platform.runpulse.com), open **API Keys** and create a
    key. Copy it immediately; it's shown only once.
  </Step>

  <Step title="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.
  </Step>
</Steps>

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

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

<Tabs>
  <Tab title="Hosted (no install)">
    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.

    <Warning>
      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`.
    </Warning>

    ### 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`](https://www.npmjs.com/package/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)

    <Steps>
      <Step title="Open your Codex config">
        Edit `~/.codex/config.toml` (or a project-scoped `.codex/config.toml`).
      </Step>

      <Step title="Add the Pulse server">
        Paste this block, replacing `YOUR_PULSE_API_KEY`:

        ```toml ~/.codex/config.toml theme={null}
        [mcp_servers.pulse]
        url = "https://mcp.runpulse.com/mcp"
        http_headers = { "x-api-key" = "YOUR_PULSE_API_KEY" }
        ```
      </Step>

      <Step title="Restart Codex">
        Reopen Codex to load the server. The `pulse` tools are now available to the agent.
      </Step>
    </Steps>

    ### Claude Code (hosted)

    <Steps>
      <Step title="Add the server">
        From your terminal, run:

        ```bash theme={null}
        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:

        ```json .mcp.json theme={null}
        {
          "mcpServers": {
            "pulse": {
              "type": "http",
              "url": "https://mcp.runpulse.com/mcp",
              "headers": {
                "x-api-key": "YOUR_PULSE_API_KEY"
              }
            }
          }
        }
        ```
      </Step>

      <Step title="Verify the connection">
        Run `/mcp` inside Claude Code and confirm `pulse` is listed.
      </Step>
    </Steps>

    ### Claude Desktop (hosted)

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

    <Steps>
      <Step title="Check for Node.js (provides npx)">
        The bridge is launched with `npx`, which ships with Node.js. Check whether you already
        have it:

        ```bash theme={null}
        npx --version
        ```

        If that prints a version number, skip Step 2.
      </Step>

      <Step title="Install Node.js (only if Step 1 failed)">
        Download and run the **LTS** installer from [nodejs.org](https://nodejs.org). Then close
        and reopen your terminal so `PATH` updates, and run `npx --version` again to confirm.
      </Step>

      <Step title="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`
      </Step>

      <Step title="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`:

        ```json claude_desktop_config.json theme={null}
        {
          "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"
              }
            }
          }
        }
        ```

        <Note>
          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`.
        </Note>
      </Step>

      <Step title="Restart Claude Desktop">
        Fully quit Claude Desktop and reopen it, then look for the Pulse tools under the
        connectors (plug) icon.
      </Step>
    </Steps>

    <Tip>
      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](/mcp/claude-connector).
    </Tip>

    ### VS Code (hosted)

    <Steps>
      <Step title="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`.
      </Step>

      <Step title="Add the Pulse server">
        Paste this block. The `inputs` section prompts for your key once and keeps it out of the
        committed file:

        ```json .vscode/mcp.json theme={null}
        {
          "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
            }
          ]
        }
        ```
      </Step>

      <Step title="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.
      </Step>
    </Steps>

    ### 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`) |
  </Tab>

  <Tab title="Local (uvx)">
    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](https://docs.astral.sh/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.

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

    <Steps>
      <Step title="Check if uv is installed">
        ```bash theme={null}
        uvx --version
        ```

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

      <Step title="Install uv (only if Step 1 failed)">
        Run the standalone installer — it needs no Python or `pip`:

        <CodeGroup>
          ```bash macOS / Linux theme={null}
          curl -LsSf https://astral.sh/uv/install.sh | sh
          ```

          ```powershell Windows theme={null}
          powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
          ```
        </CodeGroup>

        Then close and reopen your terminal (the installer updates your `PATH`) and run
        `uvx --version` again to confirm.
      </Step>
    </Steps>

    <Note>
      `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"]`.
    </Note>

    ### 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:

    ```toml ~/.pulse/config.toml theme={null}
    api_key = "YOUR_PULSE_API_KEY"
    ```

    ### Codex (local)

    <Steps>
      <Step title="Open your Codex config">
        Edit `~/.codex/config.toml` (or a project-scoped `.codex/config.toml`).
      </Step>

      <Step title="Add the Pulse server">
        Paste this block, replacing `YOUR_PULSE_API_KEY`:

        ```toml ~/.codex/config.toml theme={null}
        [mcp_servers.pulse]
        command = "uvx"
        args = ["pulse-mcp@latest"]
        env = { "PULSE_API_KEY" = "YOUR_PULSE_API_KEY" }
        ```
      </Step>

      <Step title="Restart Codex">
        Reopen Codex to load the server. The `pulse` tools are now available to the agent.
      </Step>
    </Steps>

    ### Claude Code (local)

    <Steps>
      <Step title="Add the server">
        From your terminal, run:

        ```bash theme={null}
        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:

        ```json .mcp.json theme={null}
        {
          "mcpServers": {
            "pulse": {
              "command": "uvx",
              "args": ["pulse-mcp@latest"],
              "env": {
                "PULSE_API_KEY": "YOUR_PULSE_API_KEY"
              }
            }
          }
        }
        ```
      </Step>

      <Step title="Verify the connection">
        Run `/mcp` inside Claude Code and confirm `pulse` is listed.
      </Step>
    </Steps>

    ### Claude Desktop (local)

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

    <Steps>
      <Step title="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`
      </Step>

      <Step title="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`:

        ```json claude_desktop_config.json theme={null}
        {
          "mcpServers": {
            "pulse": {
              "command": "uvx",
              "args": ["pulse-mcp@latest"],
              "env": {
                "PULSE_API_KEY": "YOUR_PULSE_API_KEY"
              }
            }
          }
        }
        ```
      </Step>

      <Step title="Restart Claude Desktop">
        Fully quit Claude Desktop and reopen it, then look for the Pulse tools under the
        connectors (plug) icon.
      </Step>
    </Steps>

    ### VS Code (local)

    <Steps>
      <Step title="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`.
      </Step>

      <Step title="Add the Pulse server">
        Paste this block. The `inputs` section prompts for your key once and keeps it out of the
        committed file:

        ```json .vscode/mcp.json theme={null}
        {
          "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
            }
          ]
        }
        ```
      </Step>

      <Step title="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.
      </Step>
    </Steps>

    ### 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` |
  </Tab>
</Tabs>

## Verify the connection

Use the official [MCP Inspector](https://github.com/modelcontextprotocol/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**:

```bash theme={null}
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):

```bash theme={null}
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](/mcp/tools).

## Troubleshooting

<AccordionGroup>
  <Accordion title="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](https://platform.runpulse.com), and
    that you restarted the client after editing the config.
  </Accordion>

  <Accordion title="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](#verify-the-connection).
  </Accordion>

  <Accordion title="'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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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](/mcp/tools#document-inputs).
  </Accordion>

  <Accordion title="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](/mcp/tools#large-results).
  </Accordion>

  <Accordion title="Payment required / out of credits">
    Your Pulse plan limit was reached. Check usage and upgrade in the
    [Platform](https://platform.runpulse.com), or
    [contact support](mailto:support@trypulse.ai).
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Tools & workflows" icon="wrench" href="/mcp/tools">
    Full tool reference and end-to-end agent examples.
  </Card>

  <Card title="MCP overview" icon="circle-info" href="/mcp/overview">
    How the Pulse MCP server works and when to use it.
  </Card>
</CardGroup>