--- title: "AI Connector — MCP Spec" slug: ai-connector-mcp-spec section: In-App Help status: stable description: "Contract document · what the MCP coordination server must implement to act as the AI-tool connector for the Globus ecosystem" last-updated: 2026-10-07 --- # AI Connector — MCP Spec Contract document · what the MCP coordination server must implement to act as the AI-tool connector for the Globus ecosystem > **Status: built in this repo; the rest of the page is the original handoff spec** > > The MCP surface is implemented in this Nexus repo itself (`server/mcp-connector.ts`), mounted at `/ai/v1/mcp` and `/mcp`, not in a separate MCP repository. As built: stateless POST only (GET and DELETE return 405, no SSE stream); 12 tools (`searchDocs`, `getDoc`, `listDocs`, `getDocsBatch`, `graphNeighbors`, `graphQuery`, `listGoals`, `getGoalStatus`, `listProjects`, `getProjectStatus`, `getTeamCapacity`, `listAuditEvents`); toolset version `1.1.0` (also reported by `GET /ai/v1/healthz`); no legacy `search` / `fetch` aliases; MCP calls carry `via: mcp` in the audit payload. Where the text below says otherwise, this note wins. > > **Original handoff specification** > > This page is a handoff specification. It defines the contract the MCP coordination server (a separate repository) must implement so any MCP-aware AI client — Claude Desktop, Cursor, Windsurf, ChatGPT desktop, Manus — can connect to it as an “ecosystem connector.” No code in this docs-site repo needs to change to satisfy the spec; the MCP team owns the build. ## What This Spec Is We already operate an MCP (Messaging and Coordination Protocol) coordination server for internal ecosystem sync — the heartbeat, sync-status, and ecosystem-context surface described on the Coordination Loop page. Native AI tooling speaks MCP as a first-class protocol for tool use, so the same coordination server is the natural home for an AI-facing connector. This spec is the companion to the AI Connector (OpenAPI 3.1) surface. Together they cover essentially every relevant AI tool: - OpenAPI surface → ChatGPT Custom GPT Actions, Manus, Cursor (OpenAPI mode), generic HTTP tool runners. - MCP surface → Claude Desktop, Cursor (MCP mode), Windsurf, Zed, any MCP-native client; also growing first-party MCP support in ChatGPT desktop and Manus. The two surfaces are intentionally 1:1 in behavior. Every MCP tool below proxies to the equivalent /api/ai/v1/* endpoint on the docs site so there is no behavioral drift between connectors and a single set of integration tests covers both. ## Handoff Boundary OWNED BY THIS REPO (DONE) - The /api/ai/v1/* HTTP surface and OpenAPI document. - AI Consumer API Key issuance, rate limits, and audit-log emission. - This spec page, the AI Connector help page, and the Coordination Loop cross-link. OWNED BY MCP REPO (TO BUILD) - Streamable HTTP MCP transport at a stable public URL. - tools/list / tools/call implementing the 8 tools below. - resources/list / resources/read implementing the docs:// URI scheme. - AI-Consumer-Key bearer auth, per-key rate limits, audit-log proxying. ## Transport Remote MCP over Streamable HTTP (the modern MCP HTTP transport that subsumes the older HTTP+SSE transport). The MCP server MUST expose a single stable URL: https://mcp.allianceabroad.com/ai/v1/mcp - POST is the primary verb (JSON-RPC 2.0 over HTTP); GET on the same URL upgrades to a server-initiated SSE stream for long-lived sessions per the Streamable HTTP transport spec. - A stdio fallback MUST be shipped as a small launcher binary / npx package (e.g. npx @aag/mcp-ai-connector) so local-dev users on clients that do not yet speak remote MCP can still connect. The stdio launcher accepts the same AI Consumer key via the AI_CONSUMER_KEY env var and forwards every JSON-RPC frame to the remote URL above. - Health check: GET https://mcp.allianceabroad.com/ai/v1/healthz returns status / ok / mcpProtocolVersion / 2025-06-18 / toolsetVersion / 1.0.0. Unauthenticated so external uptime probes can use it. ## Authentication The MCP connector reuses the same AI Consumer API Key issued for the OpenAPI surface. A single key works across both connectors so the operator only manages one credential per tool. # Required on every HTTP request to the MCP endpoint Authorization: Bearer aik_ # Equivalent (for clients with a dedicated header slot) x-ai-key: aik_ The MCP server does not need to resolve the key label itself — the docs site's own AI auth middleware (makeAiAuth in server/ai-connector.ts) resolves the bearer against storage.resolveAiConsumerKey on every request, and the downstream audit middleware writes ai-consumer: as the actor automatically. The MCP server's only responsibility is to forward the bearer header unchanged on each upstream call. There is no public “whoami” endpoint on the AI surface today. If the MCP server wants to show the operator the resolved key label in its own UI, that is a prerequisite addition to the docs site (tracked as a follow-up — see Implementation Follow-up). > **Fail closed on missing key** > > A request that arrives without a bearer key or with an unknown key MUST be rejected at the MCP transport layer with HTTP 401 before any JSON-RPC frame is parsed. Do not fall back to an unauthenticated read mode. ## Tools Surface > **listAuditEvents Parameter Subset** > > Note that while the upstream OpenAPI /api/ai/v1/audit endpoint supports 9 filter parameters (entityType, entityId, userId, action, actionPrefix, from, to, limit, offset), the MCP listAuditEvents tool currently exposes a simplified subset: only action, actionPrefix, limit and offset are available via MCP. tools/list MUST return the eight tools below. Each tool is a thin proxy — the MCP server takes the validated input, constructs the upstream HTTP call, forwards the AI Consumer key, and returns the JSON response as the tool result. | Tool | Description (AI-readable) | Input schema | Proxies to | | --- | --- | --- | --- | | name | desc | input | proxies | _(row above is a template, repeated for each data row)_ Tool descriptions are part of the contract — they are read by the host LLM to decide which tool to call. Keep them imperative and example-oriented; do not embed implementation detail. Response content type is always application/json wrapped in the standard MCP content: [text] envelope. ## Legacy / Compatibility Aliases In addition to the standard tools above, the MCP exposes two legacy aliases designed for compatibility with older OpenAI Custom Connector consumers. These tools use a different response schema: - search: Alias for searchDocs. Returns the OpenAI Custom Connector schema: . - fetch: Alias for getDoc. Returns the OpenAI Custom Connector schema: . ## Resources Surface resources/list MUST return one resource per doc page in the manifest, plus one aggregate. URI scheme: docs:// # one per page in content/manifest.json docs://llms-full # aggregate — concatenated llms-full.txt - Listing driver: the MCP server pulls the manifest from GET /api/ai/v1/docs (same source that feeds llms.txt) and emits one resource entry per page with uri, name (page title), description (section label), and mimeType: "text/markdown". - Read: resources/read for docs:// proxies to GET /api/ai/v1/docs/ and returns the body as the resource text. When bodyFormat is structured-only, the resource text is a short note pointing to the permalink — never silently return empty. - Aggregate: docs://llms-full proxies to GET /llms-full.txt on the docs site and returns it verbatim with mimeType: "text/plain". - Caching: the MCP server MAY cache the manifest for 60 seconds and individual doc bodies for 5 minutes. It MUST NOT cache audit results, goal status, project status, or team capacity — those are call-through. ## Prompts Surface Optional but recommended. prompts/list MUST advertise one starter prompt that pre-loads ecosystem context so a new Claude / Cursor session does not have to re-discover the surface: Prompt: globus_architecture_qa “Answer architecture questions about the Globus ecosystem.” — renders a system message listing the available tools, the canonical doc entry points (Overview, Capability Layers, Integration Contract, Coordination Loop), and the rule that the docs site is source of truth. Arguments: — when supplied, the prompt also pre-calls getGoalStatus(goalId) and embeds the result. ## Audit & Rate Limits - Audit (automatic): every tools/call MUST result in an audit_logs row written via the shared recordAudit() helper on the docs site. The MCP server does not write directly to the docs DB — it simply forwards the bearer key to the upstream /api/ai/v1/* call and the docs-site middleware emits the row automatically (action prefix ai., e.g. ai.goals.get, actor ai-consumer: ). - Channel marker (deferred dependency — not GA-blocking): distinguishing MCP-originated traffic from direct OpenAPI traffic in the audit log requires a small addition to the docs site (an opt-in ?via=mcp query param threaded into the audit after payload). That work is not yet shipped on the docs site. The MCP server SHOULD send ?via=mcp on every upstream call from day one (it is a no-op against today's docs site, which simply ignores unknown query params), and the marker becomes meaningful automatically once the docs-site change lands. The MCP server MUST NOT block its own launch on this marker. See Implementation Follow-up. - Resources reads: resources/read calls produce ai.docs.get or ai.docs.list audit rows the same way. - Rate limit: the upstream per-key bucket is 30 req/min. The MCP server SHOULD NOT add a second layer — it propagates 429 from upstream and includes the Retry-After seconds in the MCP error data object. - Session limits: a single MCP session counts as one tool consumer for rate-limit purposes, regardless of how many tools/call frames it sends. The bucket is keyed on the AI Consumer key, not the session id. ## Error Model Upstream HTTP errors map to MCP responses as follows. The general rule: transport / protocol errors (401, 400) use JSON-RPC error objects; recoverable business errors (404, 429, 5xx) return as a successful tools/call result with isError: true so the host LLM can read the failure and recover. | Upstream HTTP | MCP shape | Notes | | --- | --- | --- | | http | mcp | note | _(row above is a template, repeated for each data row)_ ## Versioning - The MCP server advertises its toolset version via the healthz endpoint and via a server instructions string on initialize (e.g. "Globus AI Connector — toolset v1.0.0 — proxies /api/ai/v1/*"). - The MCP toolset version tracks the upstream OpenAPI surface version 1:1. When the OpenAPI surface bumps to /api/ai/v2/*, a parallel MCP endpoint MUST be stood up at /ai/v2/mcp. The v1 endpoint keeps running until the change registry marks it Sunset. - Additive changes (new tool, new optional field, new resource) do not bump the namespace — they are announced in the API change registry under the scope ai_connector. (same scope as the OpenAPI surface). - The MCP protocol version itself is negotiated per the MCP spec; the server SHOULD support the two most recent protocol revisions at any time. ## How to Connect (End Users) Once the MCP team ships the contract above, end users will connect from their MCP-native client of choice. The snippets below are the expected copy-paste configs. Claude Desktop Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows): mcpServers The @aag/mcp-ai-connector launcher is the stdio fallback; once Claude Desktop ships first-class remote MCP support, the same key can be configured against the https://mcp.allianceabroad.com/ai/v1/mcp URL directly. Cursor Settings → MCP → Add new MCP server. Cursor supports remote MCP natively: mcpServers Generic MCP client Any client that speaks Streamable HTTP MCP can connect with: Endpoint: https://mcp.allianceabroad.com/ai/v1/mcp Transport: Streamable HTTP (POST for requests, GET for SSE upgrade) Auth: Authorization: Bearer aik_ Health: GET https://mcp.allianceabroad.com/ai/v1/healthz ## Implementation Follow-up Implementation of this contract lives in the MCP coordination server repo, not in this docs-site repo. The MCP team owns: - Standing up the Streamable HTTP endpoint at /ai/v1/mcp with bearer-key auth. - Implementing tools/list / tools/call / resources/list / resources/read / prompts/list as proxies to /api/ai/v1/*. - Publishing the @aag/mcp-ai-connector stdio launcher for clients that do not yet speak remote MCP. - Publishing the /healthz probe and wiring it into existing uptime monitoring. - End-to-end smoke test from Claude Desktop and Cursor against a staging MCP endpoint before flipping production DNS. Two pieces of this contract require small prerequisite additions to the docs site (this repo) before the MCP server can rely on them. They are intentionally not assumed to exist in any tool description above: - via=mcp audit channel marker: add an opt-in ?via= query param to /api/ai/v1/* and thread it into the audit after payload so MCP-vs-OpenAPI traffic can be told apart in the Audit Console. - Optional whoami endpoint: if the MCP server wants to display the resolved key label in its own UI, add a minimal GET /api/ai/v1/whoami returning . Not required for audit correctness. > **Related** > > See the AI Connector page for the OpenAPI surface this MCP server proxies, and the Coordination Loop page for how the existing internal-MCP surface relates to this new AI-facing surface.