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

# MCP setup

> Connect Claude Code, Cursor, Cline, Windsurf, Codex, or any MCP-compatible agent to your Pulse board.

# MCP setup

Pulse exposes 216 tools via the Model Context Protocol on `:8101`. Any MCP-compatible coding agent can connect to it. The agent then has full access to your board: creating ideations, writing specs, moving cards, querying the knowledge graph, and closing tasks with evidence.

***

## How it works

`okto-pulse init --agents` writes `.mcp.json` in your project directory. Most MCP-compatible agents auto-detect this file when launched from the same directory.

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

The `api_key` scopes the agent to your board and authenticates its tool calls. Treat it as a secret — do not commit `.mcp.json` to a public repository.

***

## Per-agent setup

<AccordionGroup>
  <Accordion title="Claude Code">
    Claude Code auto-detects `.mcp.json` in the working directory.

    1. Run `okto-pulse init --agents` in your project root.
    2. Start Claude Code from the same directory.
    3. Confirm Pulse appears in the MCP server list: `/mcp`

    That is the full setup. Claude Code re-reads `.mcp.json` on each session start.
  </Accordion>

  <Accordion title="Cursor">
    1. Run `okto-pulse init --agents` to generate `.mcp.json`.
    2. Open Cursor → **Preferences** → **MCP**.
    3. Paste the MCP URL from `.mcp.json`:
       ```text theme={null}
       http://localhost:8101/mcp?api_key=dash_...
       ```
    4. Save and restart Cursor.

    Cursor also auto-detects `.mcp.json` in project roots in newer versions — check your Cursor release notes.
  </Accordion>

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

    1. Run `okto-pulse init --agents`.
    2. Open the project in VS Code with the Cline extension active.
    3. Cline picks up the MCP server automatically.
  </Accordion>

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

    1. Run `okto-pulse init --agents`.
    2. Open your project in Windsurf.
    3. The `okto-pulse` server appears in the Cascade tool list.
  </Accordion>

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

    Add the following block:

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

    Replace the URL with the one from your generated `.mcp.json`. Restart any running Codex session to pick up the new server.
  </Accordion>

  <Accordion title="Claude Desktop">
    1. Open Claude Desktop → Settings → Developer → MCP Servers.
    2. Add a new server entry:

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

    3. Restart Claude Desktop.
  </Accordion>
</AccordionGroup>

***

## Verify the connection

Ask your agent to list available Pulse tools or inspect your board:

```text theme={null}
Use the Okto Pulse MCP tools. List the available boards and summarize
the current active work.
```

A correctly connected agent will enumerate boards and return a summary of ideations, specs, and open cards.

***

## Regenerate `.mcp.json`

If you changed the MCP port, rotate the API key, or moved to a new project directory:

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

To regenerate config for a specific agent only:

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

***

## Security

* `.mcp.json` contains your agent API key. Add it to `.gitignore`.
* The MCP URL with `?api_key=` is equivalent to a password — do not paste it into issues, Slack, or docs.
* The key scopes the agent to your local board only. It does not grant access to any remote service.

***

## What the agent can do

Once connected, your agent has access to the full Pulse pipeline via MCP tools:

| Category        | Examples                                                             |
| --------------- | -------------------------------------------------------------------- |
| Ideations       | Create, advance, answer Q\&A, evaluate scope                         |
| Refinements     | Investigate, cite evidence, add knowledge entries                    |
| Specs           | Write acceptance criteria, business rules, test scenarios, decisions |
| Sprints         | Suggest scope, create, evaluate                                      |
| Cards           | Create, move, attach evidence, close with conclusions                |
| Validations     | Submit spec and task validation with structured evidence             |
| Knowledge Graph | Query decisions, detect contradictions, trace supersedence chains    |

The agent is expected to query the knowledge graph at the start of each ideation and refinement — prior decisions and constraints live there, not in the chat context.

***

## Next steps

<Card title="First workflow" href="/quickstart">
  Run your first ideation-to-cards session with a connected agent.
</Card>