MCP reference

Pulse exposes 216 tools via the Model Context Protocol. They cover every stage of the ADLC pipeline — from creating an ideation to submitting task validation evidence — plus full access to the Knowledge Graph. The server runs locally at http://127.0.0.1:8101/mcp (default). Any MCP-compatible agent (Claude Code, Cursor, Cline, Windsurf, Goose, Codex) can connect to it and call these tools directly.

What you can do with MCP tools

MCP tools give your AI agent direct access to the full SDLC workflow — no web UI needed.

Audience	What MCP unlocks
Individual developers	Run ideation → spec → cards entirely from your coding agent. Never leave the editor.
AI agent builders	Wire Pulse as a structured memory and task layer for autonomous agents. The KG persists decisions across sessions and agent restarts.
Teams	Multiple agents share one board. Decisions, constraints, and test scenarios are written once and referenced by every agent that joins.

A connected agent can: create and advance ideations, write specs with business rules and test scenarios, record design decisions, suggest and create sprints, move cards through the implementation pipeline, submit validation evidence, and query the Knowledge Graph for prior context — all as native tool calls.

Authentication

Every tool call requires authentication. Pulse supports two methods:

API key (recommended)

Pass the key as a query parameter. okto-pulse init --agents generates a scoped key and writes it into .mcp.json automatically:

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

The key has the prefix dash_ followed by a hex string. Most agents pick this up from .mcp.json automatically — no manual config required.

Bearer token

Pass the token in the Authorization header. The value is the same dash_<hex> key:

curl http://127.0.0.1:8101/mcp \
  -H "Authorization: Bearer dash_..."

import httpx

client = httpx.Client(
    base_url="http://127.0.0.1:8101",
    headers={"Authorization": "Bearer dash_..."},
)

const client = new MCPClient({
  url: "http://127.0.0.1:8101/mcp",
  headers: { Authorization: "Bearer dash_..." },
});

Environment variable

Set PULSE_API_TOKEN in the environment where your agent or automation script runs. Pulse reads this as the fallback when no api_key query param or Authorization header is present:

export PULSE_API_TOKEN=dash_...

Your API key is equivalent to a password for your board. Do not commit .mcp.json to a public repository. Do not paste the ?api_key= URL into GitHub issues, Slack, or chat tools.

Transport

Pulse uses HTTP Streamable MCP (the MCP standard transport over HTTP with SSE streaming).

Property	Value
Default URL	`http://127.0.0.1:8101/mcp`
Transport	HTTP Streamable MCP (SSE)
Response format	All tools return `str` — a JSON-encoded response or error object
Rate limiting	None on local; Docker deployments may add upstream limits

Docker note: If Pulse is running inside Docker, the MCP server binds to 127.0.0.1 by default — unreachable from outside the container. Set MCP_HOST=0.0.0.0 before starting okto-pulse serve to expose it on all interfaces.

Tool domains

216 tools across 8 domains. Full per-tool reference pages are coming in Wave 2 — click a domain card to learn more or jump to the Knowledge Graph page now.

Board management

17 tools across profile, board discovery, members, activity & mentions, and guidelines. The session-start surface — list_my_boards, get_board_guidelines, get_unseen_summary.

Ideations

20 tools. Create, advance, and evaluate ideations. Structured Q&A, ambiguity-killer protocol, knowledge entries, version snapshots, ideation-to-spec derivation.Coming Wave 2 — full reference page with all parameters.

Refinements

14 tools. Deep investigation phase. Create and advance refinements, structured Q&A, evidence and constraint capture, refinement-to-spec derivation.Coming Wave 2 — full reference page with all parameters.

Specs

~40 tools. Write acceptance criteria, business rules, test scenarios, API contracts, architecture designs, screen mockups, decisions, and structured Q&A. Evaluation gate and validation gate.Coming Wave 2 — full reference page with all parameters.

Sprint

14 tools. Create and advance sprints, assign cards, suggest sprint scope, submit sprint evaluations, sprint Q&A. Status flow: draft → active → review → closed.Coming Wave 2 — full reference page with all parameters.

Cards & Validation

~16 tools. Create, move, and close cards; dependencies, comments, attachments, card knowledge. Includes the two validation gates: submit_spec_validation (approved → validated) and submit_task_validation (validation → done).Coming Wave 2 — full reference page with all parameters.

Knowledge Graph

21 tools (across kg_tools.py, kg_query_tools.py, kg_power_tools.py, and KG admin tools in server.py). Consolidation session lifecycle, natural-language and Cypher queries, decision history, contradiction detection, supersedence chains.Reference: Knowledge Graph concepts

Analytics & Traceability

3 tools. get_analytics (velocity, quality, coverage, per-agent metrics), get_traceability_report (spec → BRs → scenarios → cards → validations lineage), list_blockers (cards currently on-hold or missing dependencies).Coming Wave 2 — full reference page with all parameters.

Top 20 tools

These are the tools agents reach for most in daily ADLC workflows, ordered by where they appear in the pipeline.

Tool	Domain	What it does
`okto_pulse_list_my_boards`	Board	List all boards this agent has access to — first call at session start
`okto_pulse_get_unseen_summary`	Board	Count and summarize unseen mentions and activity since last session
`okto_pulse_create_ideation`	Ideations	Start a new feature idea with title, description, and initial context
`okto_pulse_get_ideation_context`	Ideations	Rich context bundle: ideation + linked refinements + KG prior decisions
`okto_pulse_evaluate_ideation`	Ideations	Submit scope evaluation (per-axis scores) before advancing to spec
`okto_pulse_derive_spec_from_ideation`	Ideations	Create a new spec from a completed ideation — one-step derivation
`okto_pulse_get_spec_context`	Specs	Rich context: spec + sprint + cards + KG decisions + BRs + contracts
`okto_pulse_add_business_rule`	Specs	Add a business rule constraint to a spec
`okto_pulse_add_test_scenario`	Specs	Add a test scenario with acceptance criteria linkage
`okto_pulse_add_decision`	Specs	Record a design decision with rationale and alternatives considered
`okto_pulse_submit_spec_evaluation`	Specs	Qualitative evaluation gate — required before `approved → validated` transition
`okto_pulse_suggest_sprints`	Sprint	AI-assisted sprint suggestion: slice a spec into reviewable deliveries
`okto_pulse_create_card`	Cards & Validation	Create an implementation card (type: normal, test, bug)
`okto_pulse_get_task_context`	Cards & Validation	Rich bundle: card + spec + BRs + scenarios + decisions + KG context — read before implementing
`okto_pulse_move_card`	Cards & Validation	Move a card to the next status (enforces transition gate)
`okto_pulse_submit_task_validation`	Cards & Validation	Independent reviewer evidence gate — required before `validation → done`
`okto_pulse_get_traceability_report`	Analytics	Full lineage: spec → BRs → TRs → scenarios → cards → validations
`okto_pulse_kg_query_natural`	Knowledge Graph	Natural-language search over the KG — no Cypher, no schema knowledge required
`okto_pulse_kg_find_similar_decisions`	Knowledge Graph	Find past decisions ranked by semantic similarity, graph centrality, and recency
`okto_pulse_kg_begin_consolidation`	Knowledge Graph	Open a transactional session to commit new nodes and edges to the graph

Tool count breakdown

Source file	Tool count
`server.py`	177
`kg_tools.py`	7
`kg_query_tools.py`	9
`kg_power_tools.py`	5
Total	216

All tools return str — a JSON-encoded response object or a structured error. Error objects always include an error key and a human-readable message.

Quickstart: list your boards

Once Pulse is running and your agent is connected, this is the first call to make:

Use the Okto Pulse MCP tools. Call okto_pulse_list_my_boards and summarize
what boards I have access to and what's currently in progress.

A correctly connected agent will call okto_pulse_list_my_boards, then follow up with okto_pulse_get_unseen_summary to surface any activity since the last session. From there, you’re ready to start or continue any pipeline stage. For step-by-step connection setup, see Connect an agent.

Error handling

All 216 tools return str — a JSON-encoded payload. On success the shape varies by tool, but every error follows the same structure:

{
  "error": "NOT_FOUND",
  "message": "Board brd_abc123 not found or agent does not have access.",
  "detail": {}
}

Common error codes:

Code	Meaning
`UNAUTHORIZED`	Missing or invalid API key. Check `.mcp.json` and regenerate with `okto-pulse init --agents`.
`FORBIDDEN`	Key is valid but the agent’s permission preset does not allow this tool. Change the preset in Board → Agents → Edit.
`NOT_FOUND`	Entity ID is incorrect or belongs to a different board.
`VALIDATION_ERROR`	Required field missing or value out of range. The `detail` object lists the failing fields.
`CONFLICT`	Status transition is not allowed (e.g., trying to move a card to `done` without passing the validation gate).
`RATE_LIMITED`	KG Cypher queries are rate-limited to 30 req/min per board. Back off and retry.

When you get an unexpected error, pass the full JSON error object to your agent — it contains enough context to self-correct in most cases.

Versioning policy

Pulse follows semantic versioning. MCP tool stability by version:

Change type	How it’s communicated
Breaking (tool removed or parameter renamed)	Major version bump + `CHANGELOG.md` `BREAKING:` entry + minimum 1 sprint deprecation notice
New tool added	Minor version bump + `CHANGELOG.md` entry
Bug fix or description change	Patch version + `CHANGELOG.md` entry
Behavior-only change (same signature, stricter validation)	Patch version + `CHANGELOG.md` `Note:` entry

Safe pattern for agents: call okto_pulse_kg_schema_info at session start to get the current schema version. If the version has changed since your last session, check CHANGELOG.md for any breaking changes before proceeding. Tool names follow the okto_pulse_<noun>_<verb> convention. Names are stable within a major version.

Connecting your agent

Connect an agent

Step-by-step setup for Claude Code, Cursor, Cline, Windsurf, Goose, and Codex — including .mcp.json generation, per-agent config, and troubleshooting.

Next steps

Knowledge Graph

How the KG persists decisions, constraints, and learnings across sessions and agent changes.

ADLC Pipeline

The six stages — Ideation → Refinement → Spec → Sprint → Cards → Validation — and how MCP tools map to each one.

Get started

Concepts

Configuration

Reference

Permissions & Agents

Guides

KG Operations

Operations

Help

MCP reference

MCP reference

What you can do with MCP tools

Authentication

API key (recommended)

Bearer token

Environment variable

Transport

Tool domains

Board management

Ideations

Refinements

Specs

Sprint

Cards & Validation

Knowledge Graph

Analytics & Traceability

Top 20 tools

Tool count breakdown

Quickstart: list your boards

Error handling

Versioning policy

Connecting your agent

Connect an agent

Next steps

Knowledge Graph

ADLC Pipeline

​MCP reference

​What you can do with MCP tools

​Authentication

​API key (recommended)

​Bearer token

​Environment variable

​Transport

​Tool domains

Board management

Ideations

Refinements

Specs

Sprint

Cards & Validation

Knowledge Graph

Analytics & Traceability

​Top 20 tools

​Tool count breakdown

​Quickstart: list your boards

​Error handling

​Versioning policy

​Connecting your agent

Connect an agent

​Next steps

Knowledge Graph

ADLC Pipeline

MCP reference

What you can do with MCP tools

Authentication

API key (recommended)

Bearer token

Environment variable

Transport

Tool domains

Top 20 tools

Tool count breakdown

Quickstart: list your boards

Error handling

Versioning policy

Connecting your agent

Next steps