FAI Orchard MCP Server — Reference
13-section protocol reference for the MCP server. Covers tools, prompts, resources, error envelopes, rate-limiting, audit log, and the 27-contract cross-runtime conformance suite.
ℹ️ For getting-started see /docs/orchard/getting-started. For per-client install snippets see /docs/mcp/install-clients.
§1 — Protocol version + capabilities
| Capability | Status |
|---|---|
| MCP protocol version | `2025-06-18` (locked at GA) |
| `tools` | ✅ 5 tools |
| `prompts` | ✅ 6 prompts |
| `resources` | ✅ 1 scheme (`frootai://orchard/…`) |
| `logging` | ✅ structured JSON via stderr |
| `completions` | (planned post-A11) |
§2 — Tools (5)
| Name | Purpose | Required entitlement |
|---|---|---|
| `orchard.search` | Full-text + faceted search over the 413-entry catalog | none |
| `orchard.show` | Render a single accelerator/play as Markdown | none |
| `orchard.list_skills` | Paginated list of agent skills (top 100 on Free) | none / `skills:full` (Pro+) |
| `orchard.show_skill` | Full manifest of a skill (deps, capabilities, attestation) | none |
| `orchard.bushel.sync` | Push/pull cloud-synced curated list | `bushel-sync` (Pro+) |
§3 — Prompts (6)
| Name | Purpose |
|---|---|
| `orchard.find_for_use_case` | "Find me an accelerator for {use_case}" |
| `orchard.compare` | Compare 2-3 accelerators side-by-side |
| `orchard.scaffold` | Generate scaffolding code for the chosen accelerator |
| `orchard.eval_report` | Render the eval-proven badge details |
| `orchard.deploy_checklist` | Pre-deploy checklist for the chosen variety |
| `orchard.security_review` | Pre-built CISO review pack for an accelerator |
§4 — Resources (1)
URI scheme: `frootai://orchard/<variety>/<id>`
Returns the accelerator's full manifest as JSON. Supports the standard MCP `resources/read` + `resources/subscribe` (cache-invalidation pushes when the daily cron refreshes the catalog).
§5 — Error envelope (RFC-7807 + MCP-style)
Every error response has the shape:
```json { "ok": false, "error": { "code": "rate_limited", "message": "Public-facing message", "request_id": "abc123def456" }, "ts": "2026-05-28T12:34:56.789Z" } ```
Standard error codes:
- `invalid_input` — schema-validation failure
- `unauthorized` — missing or invalid auth
- `forbidden` — auth ok, scope/entitlement insufficient
- `not_found`
- `rate_limited` — sets `Retry-After` header
- `internal` — server-side; check `request_id` in logs
- `payload_too_large` — body exceeds 1 MiB cap
§6 — Rate limiting
Default budgets per tier are documented in /docs/enterprise/pricing.
| Header | Meaning |
|---|---|
| `Retry-After` | seconds until the bucket refills (on `429`) |
| `X-Request-Id` | correlates with audit-log entries |
| `X-Served-By` | server build identifier (e.g., `frootai-backend/1.0.0`) |
Multi-instance deployments share rate-limit state via the optional Redis backend — see Self-host guide §5.
§7 — Audit log
Every `tools/call`, `prompts/get`, and `resources/read` is logged to the audit segment with:
- `request_id` (matches the response header)
- `ts` (ISO 8601 UTC)
- `duration_ms`
- SHA-256 fingerprint of the Bearer token (NEVER the raw token)
- SHA-256 fingerprint of the request IP (NEVER the raw IP)
- SHA-256 fingerprint of the user-agent
- HTTP status + error code (if applicable)
Audit segments compact atomically. Business + Enterprise tier exports to YOUR S3/Azure Blob/local FS bucket — see Enterprise edition §3.
§8 — Authentication
| Flow | Endpoint | Purpose |
|---|---|---|
| Bearer token | `Authorization: Bearer <jwt>` | Standard |
| CLI device-code (RFC 8628) | `POST /api/cli-auth/start` → `poll` → `complete` | CLI auth without browser redirect |
| SAML 2.0 SSO (Team+) | `/api/auth/saml/login` | IdP-initiated or SP-initiated |
| OIDC 1.0 SSO (Team+) | `/api/auth/oidc/login` | Generic OIDC + provider-specific shortcuts |
PKCE (RFC 7636) required for the device-code flow. Tokens use HMAC-SHA256 signing with key rotation supported (see token-service module).
§9 — Cross-runtime byte-equal conformance
27 contract assertions run against:
- `@frootai/mcp-orchard` (npm)
- `frootai-mcp-orchard` (PyPI)
- VSCode-embedded MCP server (same `createServer` code path)
Cross-runtime conformance certificate (SHA-256-fingerprinted) uploaded as a workflow artifact on every release. Schema: /schema/conformance-certificate-v1.json.
§10 — Multi-region behavior
Server pinned to one region at startup via `FROOTAI_REGION` env var. Cross-region READ requires entitlement; cross-region WRITE always denied as test invariant. See Enterprise edition §1.
§11 — Graceful shutdown
On `SIGTERM`:
- Server enters `draining: true` state
- `/health` returns `503` with `Retry-After: 30` so load balancers route away
- In-flight requests complete (configurable drain window via `closeGraceful({drainMs})` or `FROOTAI_DRAIN_MS` env var; default 30s)
- Process exits when in-flight count = 0 OR drain window expires
This means rolling deploys land without dropped requests.
§12 — Skill marketplace integration
The `orchard.list_skills` + `orchard.show_skill` tools expose the skill marketplace. Skills are:
- Schema-validated against `@frootai/skill-manifest-v1`
- Sigstore-attested (publisher → manifest hash)
- Dependency-allowlisted (only `@frootai/*` deps on Free; expanded on Team+ with admin review)
Read-only access on all tiers. Publishing requires Pro+ tier + signed publisher agreement.
§13 — Telemetry
Opt-in, default disabled. Set `FROOTAI_TELEMETRY=on` to emit usage events (no PII; no Bearer tokens; no IPs). `DO_NOT_TRACK=1` is a hard override that suppresses every event.
Self-hosted Docker has zero `npm install` at runtime so the image is air-gap-friendly — no outbound calls unless you opt in to telemetry + explicitly point it at your collector.