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.
| Tool | Description |
|---|---|
atisbo_orient | Workspace orientation: snapshot, what changed, strategy, or connections |
atisbo_lookup | Read claims, solutions, maps, nodes, context, or living docs |
atisbo_capture | Ingest a signal, save knowledge, or attach evidence |
atisbo_decide | Triage, create/update Solutions, set priority boosts, record outcomes, or log decisions |
atisbo_map | Read or edit the product taxonomy map |
atisbo_connect | Find and create data sources — see Connect with your agent |
atisbo_analyze | Run broader product analysis over claims, solutions, or activity |
atisbo_support | Diagnose 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 answers405— there is no SSE channel to open; all traffic is POST) - Protocol version: negotiated at
initialize— the server echoes any revision from2024-10-07through2025-11-25and 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 requirenotifications/initialized, and answersDELETEwith405— 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 freshMcp-Session-Idplusmcp-session-stale: 1, so a client can adopt the new id and refreshtools/listwithout losing its place. - HTTP status conventions (read this before mapping errors): a
200response can carry a JSON-RPC error object — protocol-level refusals ride on 200, including untrustedOrigin(-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:400unparseable JSON (-32700) or an unsupportedMCP-Protocol-Versionheader;401missing/invalid key with aWWW-Authenticatechallenge;404an invalidMcp-Session-Id(-32005 — a forged id answersSESSION_ID_INVALIDwith no hash echo; a session minted by an earlier deploy is SERVED, and only a call it cannot validate answersSCHEMA_SNAPSHOT_STALEcarrying both hashes);405any non-POST method withAllow: POST;415aContent-Typeother thanapplication/json(charset parameters allowed);429rate limit withRetry-After. Notifications answer202with no body. Rule of thumb: got a 200? The JSON-RPC envelope holds the real verdict. - Idempotency: Write operations accept
X-Idempotency-Keyheader. Every write records a receipt before it executes and echoes the receipt key asidempotency_keyin the response — the key you sent, ajsonrpc:<id>derived from your session, or anauto:<uuid>minted when you sent neither. After a lost response (gateway502, crash, network stall) probe the durable verdict withatisbo_lookup mode=receipts:appliedmeans the write landed (do not resend),failedcarries the certified error,in_flight/unknownmean 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
modefirst in the argument object (key order survives until the cutoff), and pass large structured params (spec,coverage_updates,json_paths, mapcontext_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:
| Tool | Description |
|---|---|
search_docs | Search the documentation by keyword or natural-language question |
get_doc | Read one full page as markdown by its URL (e.g. /docs/api/webhooks) |
list_docs | List 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.