{
  "uid": "cogitave.learn.native-mcp-interface.the-mcp-surface",
  "kind": "moduleUnit",
  "href": "/modules/native-mcp-interface/the-mcp-surface/",
  "title": "Why MCP is the native surface",
  "summary": "",
  "type": null,
  "products": [],
  "roles": [],
  "levels": [],
  "subjects": [],
  "headings": [
    "Why native, not adapted",
    "The protocol baseline",
    "What this buys, and what it costs"
  ],
  "source": "## Why native, not adapted\n\n[ADR-0003](../../../../core/docs/decisions/0003-mcp-native.md) frames the choice\nas three options: (1) **MCP-native** - tools and resources are the canonical\nsurface, REST/GraphQL/`llms.txt` are generated; (2) REST/GraphQL-native with an\nMCP adapter bolted on; (3) a proprietary agent RPC. Cogitave is an agent\ncompany, and agents are the primary consumers of company knowledge, so option 2\nwould make them second-class - \"the opposite of the company thesis,\" in the\nADR's own words - and option 3 forfeits ecosystem and standardization for no\nreal gain. The stated decision drivers were: an agent-first AI maturity target\n(Level 4 - agent-first with human oversight), one model and one query so\nhumans and agents cannot drift onto different data, standardized tool/resource\nsemantics with subscriptions and change notifications, and a spec Cogitave can\nauthor against with a clear upgrade path. The chosen outcome is option 1.\n\n## The protocol baseline\n\n[mcp-interface.md §1](../../../../core/docs/mcp-interface.md#1-protocol-baseline)\npins the concrete contract the server commits to:\n\n- **Spec revision 2025-11-25** - the `2026-07-28` release candidate is tracked\n  for a future upgrade, not adopted yet.\n- **Two transports**: stdio for local agents (namzu kernel, CI) and Streamable\n  HTTP for edge/remote callers - no legacy HTTP+SSE. An invalid `Origin` gets\n  HTTP 403; GET-stream polling and resumption use event IDs.\n- **JSON-RPC 2.0** over a stateful session, with capability negotiation\n  happening once, at `initialize`.\n- **JSON Schema 2020-12** for every tool's input and output - the same dialect\n  the property graph schema itself uses, so a tool's structured content and the\n  model validate identically.\n- **Capabilities advertised**: `tools` (with `listChanged`), `resources`\n  (`subscribe` + `listChanged`), `logging`, `completions`, plus tool/resource\n  icons exposed as metadata.\n- **Errors as data, not protocol failures**: a tool input-validation failure\n  comes back as a **tool execution error** (`isError: true`) rather than a\n  JSON-RPC protocol error - SEP-1303 - so the calling model can read the\n  failure and self-correct instead of the call simply breaking.\n\n## What this buys, and what it costs\n\nPer the ADR's own consequences: subscriptions give live invalidation instead of\npolling, agents and humans literally cannot drift onto different data, and the\ndesign aligns with the\n[ai-agent-engineering standard](../../../../standards/docs/standards/ai-agent-engineering.md)'s\nrequirement that every capability go over MCP with a repo-committed\n`.mcp.json`. The ADR is equally honest about the risks: MCP itself is\nfast-moving - hence pinning a revision instead of floating on it - and a tool\nsurface is an attack surface, which is why the graph-query tool covered in the\nnext unit is deliberately read-only and bounded rather than a general query\nescape hatch.\n\n> [!TIP]\n> When you evaluate any MCP surface, ask ADR-0003's own question back: is this\n> tool/resource set the canonical thing itself, or an adapter in front of\n> something else? Cogitave's answer for Core is the former.\n",
  "partOf": "cogitave.learn.native-mcp-interface",
  "durationInMinutes": 7,
  "quiz": null
}