Connect an agent

Pulse exposes 198 tools via the Model Context Protocol 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

Pulse is running

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.

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.

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.

Generate `.mcp.json`

Run this once from your project root:

okto-pulse init --agents

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

{
  "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:

okto-pulse init --agents claude
okto-pulse init --agents cursor

To use a non-default MCP port:

okto-pulse init --agents --mcp-port 8200

Per-agent setup

Claude Code auto-detects .mcp.json in the working directory. No manual config needed.

Generate the config

okto-pulse init --agents

Run from the same directory where you launch Claude Code.

Start Claude Code

claude

Claude Code reads .mcp.json on each session start.

Confirm Pulse appears in the MCP list

Inside a Claude Code session, type:

/mcp

okto-pulse should appear in the server list with a green status indicator.

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.

Cursor auto-detects .mcp.json in project roots in recent versions. You can also add the server manually via the Cursor settings UI.

Generate the config

okto-pulse init --agents

Open your project in Cursor

Launch Cursor from the same directory. Cursor will detect .mcp.json automatically in recent builds.

Manual setup (if auto-detect is not available)

Open Cursor → Preferences → MCP and paste the MCP URL from .mcp.json:

http://127.0.0.1:8101/mcp?api_key=dash_...

Save and restart Cursor.

Auto-detection of .mcp.json was added in Cursor 0.46+. If you’re on an older build, use the manual setup step above.

Cline auto-detects .mcp.json in the project directory when the VS Code extension is active.

Generate the config

okto-pulse init --agents

Open the project in VS Code

Open VS Code with the Cline extension active. The project root must contain the .mcp.json file.

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

Windsurf auto-detects .mcp.json in the project directory.

Generate the config

okto-pulse init --agents

Open your project in Windsurf

Launch Windsurf from the project root. The okto-pulse server appears in the Cascade tool list automatically.

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

Goose (by Block) supports MCP servers via ~/.config/goose/config.yaml.

Generate the config to get your API key

okto-pulse init --agents

Open .mcp.json and copy the full URL value (including ?api_key=dash_...).

Add Pulse to Goose's config

Edit ~/.config/goose/config.yaml and add an extension entry:

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.

Restart Goose

Goose reads config.yaml at startup. Start a new Goose session for the change to take effect.

Config shown is for Goose 1.x. If you’re on an earlier release, see the Goose documentation for the legacy extension format.

Codex (OpenAI CLI) supports user-wide MCP configuration via ~/.codex/config.toml.

Generate the config to get your API key

okto-pulse init --agents

Open .mcp.json and copy the full URL value.

Add Pulse to Codex's config

Edit ~/.codex/config.toml and add:

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

Restart any running Codex session

Codex reads config.toml at startup. Kill any running Codex session and start a new one.

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.

Verify the connection

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

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

Agent says it has no Pulse tools

The MCP server is not reachable or the agent didn’t pick up .mcp.json.

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

Connection refused on port 8101

okto-pulse serve is not running, or it started on a different port.

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.

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:

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.

API key is rejected (401 Unauthorized)

The key in .mcp.json may be stale or was rotated.Regenerate the config:

okto-pulse init --agents

Then restart your agent. The new key is written to .mcp.json in the current directory.

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:

http://127.0.0.1:8101/mcp?api_key=dash_...

Get started

Concepts

Configuration

Reference

Permissions & Agents

Guides

KG Operations

Operations

Help

Connect an agent

Connect an agent

Prerequisites

Generate `.mcp.json`

Per-agent setup

Verify the connection

Permissions on first connect

Troubleshooting

Next steps

First workflow

MCP reference

Get started

Concepts

Configuration

Reference

Permissions & Agents

Guides

KG Operations

Operations

Help

Documentation Index

​Connect an agent

​Prerequisites

​Generate .mcp.json

​Per-agent setup

​Verify the connection

​Permissions on first connect

​Troubleshooting

​Next steps

First workflow

MCP reference

Connect an agent

Prerequisites

Generate `.mcp.json`

Per-agent setup

Verify the connection

Permissions on first connect

Troubleshooting

Next steps