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

# Connect an agent

> Connect Claude Code, Cursor, Cline, Windsurf, Goose, or Codex to your Pulse board via MCP — one command to generate the config, then start your agent.

# Connect an agent

Pulse exposes 216 tools via the [Model Context Protocol](https://modelcontextprotocol.io) on port `8101`.
Any MCP-compatible coding agent can connect to it and gain full access to your board: creating ideations, writing specs, moving cards, querying the knowledge graph, and closing tasks with evidence.

***

## Prerequisites

<Steps>
  <Step title="Pulse is running">
    ```bash theme={null}
    okto-pulse serve --accept-terms
    ```

    Pulse binds the API + UI to port `8100` and the MCP server to port `8101`. Both must be reachable from wherever your agent runs.

    <Warning>
      Set `MCP_HOST=0.0.0.0` in your container environment so the MCP server binds to all interfaces. If left as `127.0.0.1` (the default), agents outside the container cannot reach it.
    </Warning>
  </Step>

  <Step title="You have an API key">
    `okto-pulse init --agents` generates a scoped API key for each agent. Run it from your project root — the key is embedded in the `.mcp.json` it writes.

    If you already ran `init`, your key is in the `.mcp.json` in your project directory. Do not commit that file to a public repository.
  </Step>
</Steps>

***

## Generate `.mcp.json`

Run this once from your project root:

```bash theme={null}
okto-pulse init --agents
```

This writes `.mcp.json` in the current working directory:

```json theme={null}
{
  "mcpServers": {
    "okto-pulse": {
      "url": "http://127.0.0.1:8101/mcp?api_key=dash_..."
    }
  }
}
```

The `api_key` scopes the agent to your board and authenticates every tool call. Most MCP-compatible agents auto-detect this file when launched from the same directory.

To generate config for a specific agent only:

```bash theme={null}
okto-pulse init --agents claude
okto-pulse init --agents cursor
```

To use a non-default MCP port:

```bash theme={null}
okto-pulse serve --mcp-port 8200 --accept-terms
```

Then update the generated `.mcp.json` URL to use the same port.

***

## Per-agent setup

<Tabs>
  <Tab title="Claude Code">
    Claude Code auto-detects `.mcp.json` in the working directory. No manual config needed.

    <Steps>
      <Step title="Generate the config">
        ```bash theme={null}
        okto-pulse init --agents
        ```

        Run from the same directory where you launch Claude Code.
      </Step>

      <Step title="Start Claude Code">
        ```bash theme={null}
        claude
        ```

        Claude Code reads `.mcp.json` on each session start.
      </Step>

      <Step title="Confirm Pulse appears in the MCP list">
        Inside a Claude Code session, type:

        ```text theme={null}
        /mcp
        ```

        `okto-pulse` should appear in the server list with a green status indicator.
      </Step>
    </Steps>

    <Tip>
      Claude Code re-reads `.mcp.json` each time a new session starts. If you rotate your API key, just re-run `okto-pulse init --agents` and restart the session — no other config changes needed.
    </Tip>
  </Tab>

  <Tab title="Cursor">
    Cursor auto-detects `.mcp.json` in project roots in recent versions. You can also add the server manually via the Cursor settings UI.

    <Steps>
      <Step title="Generate the config">
        ```bash theme={null}
        okto-pulse init --agents
        ```
      </Step>

      <Step title="Open your project in Cursor">
        Launch Cursor from the same directory. Cursor will detect `.mcp.json` automatically in recent builds.
      </Step>

      <Step title="Manual setup (if auto-detect is not available)">
        Open **Cursor → Preferences → MCP** and paste the MCP URL from `.mcp.json`:

        ```text theme={null}
        http://127.0.0.1:8101/mcp?api_key=dash_...
        ```

        Save and restart Cursor.
      </Step>
    </Steps>

    <Note>
      Auto-detection of `.mcp.json` was added in Cursor 0.46+. If you're on an older build, use the manual setup step above.
    </Note>
  </Tab>

  <Tab title="Cline">
    Cline auto-detects `.mcp.json` in the project directory when the VS Code extension is active.

    <Steps>
      <Step title="Generate the config">
        ```bash theme={null}
        okto-pulse init --agents
        ```
      </Step>

      <Step title="Open the project in VS Code">
        Open VS Code with the Cline extension active. The project root must contain the `.mcp.json` file.
      </Step>

      <Step title="Confirm Cline picks up the server">
        In the Cline sidebar, open **MCP Servers**. `okto-pulse` should appear as a connected server. If it doesn't appear, try reloading the VS Code window (`Cmd+Shift+P → Developer: Reload Window`).
      </Step>
    </Steps>
  </Tab>

  <Tab title="Windsurf">
    Windsurf auto-detects `.mcp.json` in the project directory.

    <Steps>
      <Step title="Generate the config">
        ```bash theme={null}
        okto-pulse init --agents
        ```
      </Step>

      <Step title="Open your project in Windsurf">
        Launch Windsurf from the project root. The `okto-pulse` server appears in the Cascade tool list automatically.
      </Step>

      <Step title="Verify in the Cascade panel">
        Open the Cascade panel and look for `okto-pulse` in the tools list. If the server doesn't appear, check that `.mcp.json` is in the root of the folder Windsurf has open (not a subdirectory).
      </Step>
    </Steps>
  </Tab>

  <Tab title="Goose">
    Goose (by Block) supports MCP servers via `~/.config/goose/config.yaml`.

    <Steps>
      <Step title="Generate the config to get your API key">
        ```bash theme={null}
        okto-pulse init --agents
        ```

        Open `.mcp.json` and copy the full URL value (including `?api_key=dash_...`).
      </Step>

      <Step title="Add Pulse to Goose's config">
        Edit `~/.config/goose/config.yaml` and add an extension entry:

        ```yaml theme={null}
        extensions:
          okto-pulse:
            type: remote_extension
            name: okto-pulse
            uri: http://127.0.0.1:8101/mcp?api_key=dash_...
            enabled: true
        ```

        Replace the URI with the full URL from your `.mcp.json`.
      </Step>

      <Step title="Restart Goose">
        Goose reads `config.yaml` at startup. Start a new Goose session for the change to take effect.
      </Step>
    </Steps>

    <Note>
      Config shown is for Goose 1.x. If you're on an earlier release, see the [Goose documentation](https://block.github.io/goose/) for the legacy extension format.
    </Note>
  </Tab>

  <Tab title="Codex">
    Codex (OpenAI CLI) supports user-wide MCP configuration via `~/.codex/config.toml`.

    <Steps>
      <Step title="Generate the config to get your API key">
        ```bash theme={null}
        okto-pulse init --agents
        ```

        Open `.mcp.json` and copy the full URL value.
      </Step>

      <Step title="Add Pulse to Codex's config">
        Edit `~/.codex/config.toml` and add:

        ```toml theme={null}
        [[mcp_servers]]
        name = "okto-pulse"
        url  = "http://127.0.0.1:8101/mcp?api_key=dash_..."
        ```

        Replace the URL with the one from your `.mcp.json`.
      </Step>

      <Step title="Restart any running Codex session">
        Codex reads `config.toml` at startup. Kill any running Codex session and start a new one.
      </Step>
    </Steps>

    <Tip>
      If you want Codex to connect on a per-project basis rather than globally, you can also place `.mcp.json` in your project directory — Codex will detect it automatically in recent CLI versions.
    </Tip>
  </Tab>
</Tabs>

***

## Verify the connection

Once your agent is connected, ask it to inspect your board:

```text theme={null}
Use the Okto Pulse MCP tools. List all boards I have access to and summarize
the current active work.
```

A correctly connected agent will call `okto_pulse_list_my_boards`, enumerate your boards, and return a summary of open ideations, specs, and cards. If the agent responds that it has no such tools available, the MCP server is not connected — see Troubleshooting below.

***

## Permissions on first connect

Pulse generates a scoped key for each agent with a default permission preset. The preset determines which categories of tools the agent can call.

| Preset           | What it can do                                                             |
| ---------------- | -------------------------------------------------------------------------- |
| **Full Control** | All 216 tools — read, write, move, validate, delete                        |
| **Spec Writer**  | Create and update specs, add Q\&A, write business rules and test scenarios |
| **Executor**     | Read board, create and move cards, attach evidence, close tasks            |
| **QA**           | Read board, submit validations, run test scenarios                         |
| **Validator**    | Read board, submit task validations only                                   |

The default preset for newly generated keys is **Full Control**. You can change a key's permissions in the Pulse settings UI (**Board → Agents → Edit**).

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Agent says it has no Pulse tools">
    The MCP server is not reachable or the agent didn't pick up `.mcp.json`.

    1. Confirm Pulse is running: `okto-pulse status`
    2. Confirm port 8101 is listening: `curl http://127.0.0.1:8101/mcp`
    3. Confirm `.mcp.json` is in the project root the agent is using — not a subdirectory
    4. Restart the agent after generating `.mcp.json`
  </Accordion>

  <Accordion title="Connection refused on port 8101">
    `okto-pulse serve` is not running, or it started on a different port.

    ```bash theme={null}
    okto-pulse status
    ```

    If the MCP port shows **stopped**, start Pulse with `okto-pulse serve --accept-terms`. If you started on a custom port, pass `--mcp-port` to match: `okto-pulse serve --mcp-port 8200`.
  </Accordion>

  <Accordion title="Agent can connect locally but not from Docker">
    The MCP server binds to `127.0.0.1` by default, which is not reachable from inside Docker containers or remote machines.

    Set the environment variable before starting Pulse:

    ```bash theme={null}
    MCP_HOST=0.0.0.0 okto-pulse serve --accept-terms
    ```

    Then update `.mcp.json` to use the container's host IP instead of `127.0.0.1`.
  </Accordion>

  <Accordion title="API key is rejected (401 Unauthorized)">
    The key in `.mcp.json` may be stale or was rotated.

    Regenerate the config:

    ```bash theme={null}
    okto-pulse init --agents
    ```

    Then restart your agent. The new key is written to `.mcp.json` in the current directory.
  </Accordion>

  <Accordion title="Cursor / Cline doesn't detect .mcp.json automatically">
    Some older builds require manual configuration. Open the MCP settings in your agent and paste the URL from `.mcp.json` directly. The URL has the form:

    ```text theme={null}
    http://127.0.0.1:8101/mcp?api_key=dash_...
    ```
  </Accordion>
</AccordionGroup>

***

## Next steps

<CardGroup cols={2}>
  <Card title="First workflow" href="/quickstart">
    Run your first ideation-to-cards session with your connected agent.
  </Card>

  <Card title="MCP reference" href="/reference/mcp">
    Full index of all 216 MCP tools, grouped by domain.
  </Card>
</CardGroup>