AtisboAtisbo Docs
API Reference

MCP Server

Use Atisbo as an AI tool via the Model Context Protocol (MCP)

MCP Server

Atisbo exposes a Model Context Protocol (MCP) server that lets agents work with the same Signals, Opportunities, Backlog, Groups, Decisions, Living Documents, and Outcomes shown in the app.

What is MCP?

The Model Context Protocol is an open standard that lets AI assistants call external tools. When Claude or another AI has your Atisbo MCP configured, it can:

  • Review Signals and evidence provenance
  • Search Opportunities about a specific topic
  • Read your Strategy Stack and roadmap
  • Prepare portfolio-level Product Reviews
  • Create or update Solutions after a human Decision
  • Brief a designer or engineer on one Backlog item and its Living Document
  • Connect a design or PR handoff to In Review
  • Record the observed Outcome of a Done Solution

Agent Skills add interaction guidance on top of these tools. They do not add a separate Atisbo planning or implementation pipeline.

Setup

The short way

Go to Settings → Account → Connect agents, pick your agent, and click Generate setup command. You get one block to paste into your terminal — it connects this workspace and installs the Atisbo skills in the same step. Most people should stop here.

The manual way

If you are wiring a client yourself, generate the connection from the same screen and use the key it gives you. The key is shown once.

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "atisbo": {
      "type": "http",
      "url": "https://app.atisbo.dev/api/mcp",
      "headers": {
        "Authorization": "Bearer <your-api-key>"
      }
    }
  }
}

Custom Agent (JSON-RPC 2.0)

Start with the compact tools returned by tools/list. A normal workflow should begin with atisbo_orient, then call a more specific tool only when the answer needs it.

curl -X POST https://app.atisbo.dev/api/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-api-key>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "atisbo_orient",
      "arguments": { "mode": "snapshot" }
    }
  }'

Available Tools

tools/list returns eight intent-level tools by default. Each one takes a mode, so the surface stays small while the capability does not.

ToolDescription
atisbo_orientWorkspace orientation: snapshot, what changed, strategy, or connections
atisbo_lookupRead claims, solutions, maps, nodes, context, or living docs
atisbo_captureIngest a signal, save knowledge, or attach evidence
atisbo_decideTriage, create/update Solutions, set priority boosts, record outcomes, or log decisions
atisbo_mapRead or edit the product taxonomy map
atisbo_connectFind and create data sources — see Connect with your agent
atisbo_analyzeRun broader product analysis over claims, solutions, or activity
atisbo_supportDiagnose why the workspace is not behaving as expected

atisbo_support is deliberately top-level rather than a mode on another tool. It is needed at exactly the moment the calling agent is confused about Atisbo, which is the worst moment to require it to already know which tool hides support.

A larger surface of single-purpose primitives also exists, requested with ?surface=full. It changes discovery only — every primitive is callable through tools/call at any time, whether or not tools/list advertised it. Most clients should not ask for it: eight tools cost an agent far less context than eighty.

Tool Reference

atisbo_orient

Returns a compact workspace overview.

Input:

{
  "mode": "snapshot"
}

Output:

{
  "data": {
    "top_claims": [],
    "solutions": [],
    "recommended_next_tools": []
  },
  "meta": {
    "timestamp": "2026-03-07T14:30:00Z"
  }
}

atisbo_lookup

Reads a specific object or searches by name/reference. Use this after atisbo_orient when you need detail.

Input:

{
  "mode": "get",
  "claim_id": "claim-uuid",
  "depth": "summary"
}

atisbo_decide

Applies product decisions. Resolve names to UUIDs before mutating.

Input:

{
  "mode": "update_solution",
  "solution_id": "solution-uuid",
  "priority_boost": 1.5,
  "comment": "Prioritized for the current strategic commitment."
}

The current Board order uses manual rank first, then evidence-weighted priority multiplied by the PM's explicit boost. RICE fields are retained only for legacy audit/effort workflows and do not rank Solutions.

Authentication

Every MCP tool call requires a Bearer token in the Authorization header. The protocol handshake does not: initialize, ping, notifications/* and tools/list answer without a key, so you can point a client at the endpoint and inspect its tool surface before creating a credential. Keys are:

  • Scoped to one tenant and one workspace
  • Created and revoked in Settings → Account → Connect agents — revocation takes effect within about 30 seconds
  • Hashed before storage (SHA-256) — Atisbo never stores the plaintext key, so a lost key is replaced rather than recovered

An unauthenticated tools/call answers 401 with a JSON-RPC error plus a standard WWW-Authenticate: Bearer resource_metadata=… challenge pointing at /.well-known/oauth-protected-resource, which names the scopes a key can carry.

Usage Protection

Atisbo tracks MCP usage as work units so the platform can detect runaway agent loops without treating every request as equal. Simple reads are cheap; write tools, external tools, long-running tools, and batches count for more.

Normal clients should use the compact surface and avoid repeated tools/list calls. Hard rate limiting is reserved for incident-response protection, not as the default user experience.

Protocol

Atisbo's MCP server implements JSON-RPC 2.0 over HTTPS:

  • Endpoint: POST https://app.atisbo.dev/api/mcp (GET answers 405 — there is no SSE channel to open; all traffic is POST)
  • Protocol version: negotiated at initialize — the server echoes any revision from 2024-10-07 through 2025-11-25 and answers an unknown or absent one with its latest supported (2025-11-25)
  • Sessions are transport-only, stateless by design: every request re-authenticates and re-reads state, so any request is processed equivalently to one under the latest supported protocol version. The server does NOT gate calls on an earlier initialize (no session store), does not require notifications/initialized, and answers DELETE with 405 — there is nothing to terminate. The spec's initialization gate matters for stateful servers; here the invariant is per-request equivalence instead. A session id embeds the tool-contract revision of the deploy that minted it; when a later deploy serves the call, the request still runs (validated against the live contract) and the response carries a fresh Mcp-Session-Id plus mcp-session-stale: 1, so a client can adopt the new id and refresh tools/list without losing its place.
  • HTTP status conventions (read this before mapping errors): a 200 response can carry a JSON-RPC error object — protocol-level refusals ride on 200, including untrusted Origin (-32600), envelope-shape violations (-32600), validation failures (-32602), and unknown tools/methods/resources (-32601/-32602). HTTP error statuses are reserved for transport gates, where the request never reached tool dispatch: 400 unparseable JSON (-32700) or an unsupported MCP-Protocol-Version header; 401 missing/invalid key with a WWW-Authenticate challenge; 404 an invalid Mcp-Session-Id (-32005 — a forged id answers SESSION_ID_INVALID with no hash echo; a session minted by an earlier deploy is SERVED, and only a call it cannot validate answers SCHEMA_SNAPSHOT_STALE carrying both hashes); 405 any non-POST method with Allow: POST; 415 a Content-Type other than application/json (charset parameters allowed); 429 rate limit with Retry-After. Notifications answer 202 with no body. Rule of thumb: got a 200? The JSON-RPC envelope holds the real verdict.
  • Idempotency: Write operations accept X-Idempotency-Key header. Every write records a receipt before it executes and echoes the receipt key as idempotency_key in the response — the key you sent, a jsonrpc:<id> derived from your session, or an auto:<uuid> minted when you sent neither. After a lost response (gateway 502, crash, network stall) probe the durable verdict with atisbo_lookup mode=receipts: applied means the write landed (do not resend), failed carries the certified error, in_flight/unknown mean the process died mid-write (wait or contact support — never resend a mutation blindly), and no receipt at all means the write never started — safe to resend.
  • Retries: Query tools have automatic retry with circuit breaker
  • Client payload budget: tool-call arguments are serialized JSON on the wire, and some agent transports truncate long serialized arguments — later keys of the object vanish before the request reaches the server, and the call dies client-side with a misleading schema error (an enum complaint about a key the server would have accepted). Keep arguments compact (~1.5 kB serialized is a safe ceiling), put mode first in the argument object (key order survives until the cutoff), and pass large structured params (spec, coverage_updates, json_paths, map context_answers) as a JSON string — every such field accepts the stringified form and parses it server-side on arrival.

See the MCP specification for full protocol details.

Documentation MCP Server

The server above acts on your workspace and needs a key. A second MCP server serves the public documentation itself — no key, no workspace, nothing to configure:

  • Endpoint: POST https://app.atisbo.dev/api/mcp-docs
  • Transport: JSON-RPC 2.0 over HTTP (Streamable HTTP conventions, same envelope as above)
  • Auth: none — it can only return text already published under /docs

Three read-only tools:

ToolDescription
search_docsSearch the documentation by keyword or natural-language question
get_docRead one full page as markdown by its URL (e.g. /docs/api/webhooks)
list_docsList documentation pages with title and description; optional integer limit (1–50) caps the response, omit it for the whole corpus

The same pages are also exposed as MCP resources — resources/list returns the corpus index and resources/read reads one page as markdown by its resource URI (for example https://app.atisbo.dev/docs/api/webhooks). Both are advertised in the server's initialize capabilities.

Rate limited to 30 requests per minute per IP, fail-closed. Retrieval is keyword matching over a corpus frozen at build time; no language model runs in this path.

Ask Endpoint (NLWeb)

The same corpus also answers Microsoft's NLWeb protocol:

curl -X POST https://app.atisbo.dev/api/ask \
  -H "Content-Type: application/json" \
  -d '{"query": "how do I forward support email into Atisbo"}'

The response carries _meta (response_type, version, limitations) and an array of matching doc pages with url, name, site and score. Send "streaming": true to get the NLWeb v0.55 SSE event sequence (start, one result per hit, complete) instead of one JSON object. GET /api/ask?query=... works too.

Like the docs server this is retrieval only — it ranks real documentation pages and never generates prose, which _meta.limitations states on every response.

On this page