MCP API Reference

Reference verified against the live runtime griffai-memory 1.2.0.dev40 on 2026-08-10. Tool counts and names are live observations — re-verify with tools/list rather than freezing them.

The Brain is programmable over the Model Context Protocol (MCP), JSON-RPC 2.0 over HTTP with SSE responses.

Endpoints

Surface	Endpoint	Auth	Audience
Local (on-platform)	http://127.0.0.1:8788/mcp	Loopback-local, token-free	Local agents on the platform machine. The only local Brain surface (single-port model since 2026-07-16; /health served same-process).
Hosted (customer SaaS)	your workspace's MCP connector URL (provisioned at signup, served from connect.griff.run)	OAuth sign-in, or a per-user API bearer managed in the workspace	Remote clients (Claude, ChatGPT, other MCP-compatible apps) connecting to a tenant workspace. Tenant-scoped: tenant identity derives from the authenticated credential, never from the request body.

Handshake

curl -s http://127.0.0.1:8788/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"my-client","version":"1.0"}}}'

Returns a serverInfo block (griffai-memory, current version). Then call tools/list for the live tool inventory, and tools/call to invoke.

The front door: retrieval_arbitrate_tool

Recall goes through one governed router/arbiter, not raw search:

{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{
  "name":"retrieval_arbitrate_tool",
  "arguments":{"query":"what changed in the identity rollout","compact":true}
}}

• Always pass compact: true.
• Do not pass limit / candidate_limit — the router enforces its own bounds server-side and reports them back in routing.bounds.
• Results carry per-item grounding tokens and content_sha256, plus map_evidence when file location is part of the answer.
• Raw recall tools are not public; compatibility recall names delegate to this same governed path.

Tool families

The live server exposes 60+ bounded tools (63 observed on 1.2.0.dev40). Families:

Family	Representative tools	Purpose
Governed recall	retrieval_arbitrate_tool, brain_command	Router/arbiter recall; natural-language routing to the right governed surface.
Knowledge & docs	docstore_manifest_tool, docstore_search_tool, docstore_get_*	Governed document store: current-state, claims matrix, proof packs, known limitations.
Graph	graphrag_status_tool, brain_institutional_graph_tool	GraphRAG status and institutional graph queries.
Status & health	brain_status_query_tool, brain_startup_context_tool, brain_operational_bootstrap_tool, recall_stats	Board/status synthesis, session startup packets, runtime posture.
Verification	brain_verify_claims_tool, recall_staleness_check_tool, receipt_reconcile_tool, ledger_integrity_scan_tool	Claim verification, staleness checks, receipt/ledger reconciliation.
Continuity	capture_operator_intent_tool, record_operator_correction_tool, record_outcome_valence_tool, due_followups_tool, generate_daily_brain_brief_tool	Operator intents, corrections, outcomes, follow-ups, daily briefs.
Work tracking	record_task_attempt_tool, update_task_attempt_status_tool, list_task_attempts_tool	The governed work ledger.
Artifact identity	issue_artifact_id_tool, issue_artifact_id_bundle_tool, reconcile_artifact_id_tool, list_artifact_ids_tool	Brain-issued durable IDs for boards, receipts, handoffs, workorders.
Ingest & lifecycle	ingest_paths_tool, tombstone_paths_tool, tombstone_reconcile_sweep_tool	Governed ingest and supersession.
Agent state	agent_state_write_tool, agent_state_read_admit_tool, agent_state_policy_simulate_tool, agent_state_lineage_tool	Agent State Integrity write/read gates, simulation, lineage.
Runtime & benchmarks	brain_runtime_check, brain_benchmark_*	Skilled runtime checks and recall benchmarks.

Behavior contracts

• Concurrency-safe front door: synchronous tool implementations run in worker threads; requests exceeding 120 s receive a bounded JSON-RPC timeout while the event loop stays available.
• Governed calls are audited: every governed call receives a policy decision and an audit entry; with identity enforcement live, each carries the caller's resolved per-turn identity (see Per-Agent Identity).
• Bounded results: the server enforces result bounds; clients must not attempt to widen them.

Hosted connector notes

• Workspace provisioning starts at signup; each workspace gets its own connector URL and credentials.
• The hosted tool surface mirrors the recall/docstore/status families with tenant scoping; per-tenant rate limits are enforced per credential, not by network address.
• Treat any tool inventory published here as indicative — tools/list on your connector is authoritative for your plan and tenant.