Model Context Protocol (MCP) integration

YieldFabric exposes MCP surfaces so AI clients (Claude, Cursor, other MCP-compatible hosts) can use YF as a knowledge base and act on wallet state through stable tools.

This is an optional AI-tooling surface. Regular web apps and backend services should keep using auth REST, the GraphQL gateway for reads and mutations, and message-status polling for settlement.

Two surfaces — pick by client

If you're wiring Claude: you want the agents /mcp surface.

The knowledge-base surface (POST /mcp)

Standard MCP over stateless Streamable HTTP: initialize, ping, tools/list, tools/call; notifications get 202; GET /mcp is 405 (no server-push stream). Seven read-only tools — the connector reads and reasons over the knowledge graphs YieldFabric already built (file → KG); it never re-processes. Scoped to what the caller can access:

Every result names its source. Hits, entities, and citations carry a source: {kg, room} object — which knowledge graph, and which room / workspace / private notebook it came from — so the model can always tell you where a fact originated, and search spans every room you can access in one call. Deal/intent write tools are deliberately not exposed on this surface, and retrieval is scoped to what the caller can access (rationale: ).

Auth: two ways in

1. API key header (backend/dev — Claude Code, Claude Desktop). Generate a yf_api_… key once (see docs/building-with-yf.md §API keys), then pass it as the bearer — the agents middleware exchanges it per request, so it never expires mid-session. Do not put a raw JWT in config: access JWTs die in 15 minutes.

claude mcp add --transport http yieldfabric https://agents.yieldfabric.com/mcp \
  --header "Authorization: Bearer yf_api_..."

or in .mcp.json:

{
  "mcpServers": {
    "yieldfabric": {
      "type": "http",
      "url": "https://agents.yieldfabric.com/mcp",
      "headers": { "Authorization": "Bearer yf_api_..." }
    }
  }
}

2. OAuth login (claude.ai custom connectors — the "Connect" button). Add the connector in claude.ai → Settings → Connectors → Add custom connector → paste https://agents.yieldfabric.com/mcp. The browser opens YieldFabric's login (any sign-in method — email/password, MetaMask, passkey, Dynamic), shows a consent card, and the connector is live; token renewal is silent thereafter. Claude Code/Desktop can use the same flow — omit the --header and run /mcp to authenticate.

Under the hood (all standard, nothing to configure client-side): anonymous POST /mcp → 401 + WWW-Authenticate → /.well-known/oauth-protected-resource (agents) → RFC 8414 metadata + RFC 7591 dynamic registration + PKCE code flow (auth service /oauth/*) → consent page (app.../oauth/authorize) → 1-hour MCP access tokens with 30-day silent refresh. Authorization-server reference: .

Calling it manually (curl)

# Handshake
curl -s -X POST https://agents.yieldfabric.com/mcp \
  -H "Authorization: Bearer $YF_API_KEY" -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","clientInfo":{"name":"curl","version":"0"}}}'

# Discover tools
curl -s -X POST https://agents.yieldfabric.com/mcp \
  -H "Authorization: Bearer $YF_API_KEY" -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

# Ask the knowledge base (grounded answer + citations)
curl -s -X POST https://agents.yieldfabric.com/mcp \
  -H "Authorization: Bearer $YF_API_KEY" -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"ask","arguments":{"question":"What are the key terms of the Acme facility?"}}}'

Async pattern: ingest returns {run_id, ...} immediately — poll ingest_status with that id every few seconds until the status is terminal. Don't wait synchronously; MCP clients abort tools idle for ~5 minutes.

The wallet/payments surface (/api/mcp/*, bespoke REST)

Served by the payments service. This is not the standard MCP protocol — there is no JSON-RPC envelope, so Claude and other standard MCP clients cannot connect to it directly; it exists for YF-internal agent runtimes and custom integrations.

Every endpoint is JWT-gated (Authorization: Bearer <jwt>) and runs under the caller's permissions. The 15-minute JWT TTL means this surface suits programmatic callers that mint tokens per session — not static client config.

Tool catalog (19): yieldfabric/list_assets, get_asset, send_instant_payment, accept_payment, swap_credit_for_cash, complete_swap, list_contacts, get_contact, list_connection_requests, create_connection_request, accept_connection, send_invitation, pipeline/list_tasks, pipeline/describe_task, pipeline/propose, pipeline/find_predecessors, agreement/get, agreement/get_graph, agreement/next_scheduled_payment. Read tools/list for the authoritative input schemas.

curl -s -X POST https://pay.test.yieldfabric.com/api/mcp/tools/call \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"name": "yieldfabric/list_contacts", "arguments": {}}'

The agents service also keeps a bespoke POST /api/mcp/tools/call route (knowledge + deal/intent tools, yieldfabric/* names) for the same internal callers — the /mcp surface above is the external-client story.

Use MCP for agent tooling, not app data flow

MCP is useful when a model-facing tool client needs a compact wallet view, typed knowledge access, and prompts. For product flows controlled by your own app, prefer the direct public APIs:

• Auth REST for sign-in, token refresh, profile lookup, and API keys.
• The GraphQL gateway for public reads and mutations across auth, payments, and agents.
• Message-status polling for settlement confirmation.

See also

• Agents, knowledge & workspaces — the collaboration surface the knowledge tools sit beside.
• — design rationale, auth posture, don't-break rules.
• Authentication & signing — JWT lifecycle and permissions for tool calls.
• API reference — REST and GraphQL operations the MCP tools wrap.