Model Context Protocol (MCP) integration

YieldFabric exposes an MCP surface so AI agents (Claude, Cursor, other MCP-compatible clients) can read wallet state and execute operations 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.

Where the MCP surface lives

The MCP integration is served under the payments REST surface at /api/mcp/*.

Every endpoint is JWT-gated with the same Authorization: Bearer <jwt> header the rest of the API uses. Tool calls run under that caller's permissions — the same auth surface as a direct GraphQL call.

Tools (19)

The current tool catalog covers wallet, payment, connection, pipeline composition, and agreement operations:

The first 12 are wallet-scoped — what an agent invokes when acting on behalf of a single user. The pipeline + agreement tools operate on shared platform state. Group / workflow / KG tools aren't exposed via MCP today (they go through the regular GraphQL / REST surfaces).

Discovery and schemas

The MCP surface includes both action endpoints (tools/call, prompts/get, resources/wallet/{uri}) and discovery endpoints:

• GET /api/mcp/tools/list — enumerate the 19 tools with input schemas
• GET /api/mcp/prompts/list — enumerate the 2 prompts with arguments
• GET /api/mcp/resources/list — enumerate resource templates
• POST /api/mcp/initialize — MCP protocol handshake

Clients should read tools/list at startup and use the returned input schemas as the source of truth for tool arguments.

HTTP-only

MCP clients connect over two transports:

• stdio (subprocess) — Claude Code's default; Cursor uses this too.
• HTTP/SSE (remote) — Claude Code (recent versions) and Claude.ai custom-integrations support this.

YieldFabric's MCP surface is HTTP-only. Use an HTTP-capable MCP client or place a small stdio-to-HTTP proxy in front of it for clients that only support subprocess transport.

Calling it manually (curl)

Here's how to drive the MCP endpoints with curl. Replace $TOKEN with a YF JWT (see cross-service-walkthrough.md step 1 for how to obtain one).

Fetch wallet AI view (YAML resource)

WALLET_ID="WLT-0x..."
curl -s -X GET "https://pay.yieldfabric.com/api/mcp/resources/wallet/wallet://${WALLET_ID}" \
  -H "Authorization: Bearer $TOKEN" \
  | jq -r '.text'

Returns YAML describing balances, recent transactions, contacts, and pending actions for the wallet. Useful as a context block fed into an LLM prompt.

Call a tool

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

Tool-specific arguments are defined per domain on the platform. Until full JSON Schemas ship per tool, call tools/list to discover the available tools and their input shapes — the discovery endpoint is the contract.

Get a context prompt

curl -s -X POST https://pay.yieldfabric.com/api/mcp/prompts/get \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "wallet_context_prompt",
    "arguments": { "wallet_id": "'$WALLET_ID'" }
  }' \
  | jq .

Two prompts exist today:

• wallet_context_prompt — wallet-specific orientation for an LLM acting on that wallet.
• connections_context_prompt — relationships + recent interaction context.

Wiring Claude Code (current state)

Claude Code's ~/.config/claude-code/config.json (or equivalent) supports both stdio + remote MCP. For the HTTP surface here, a remote MCP entry looks like:

{
  "mcpServers": {
    "yieldfabric": {
      "transport": {
        "type": "http",
        "url": "https://pay.yieldfabric.com/api/mcp"
      },
      "headers": {
        "Authorization": "Bearer <YF_JWT>"
      }
    }
  }
}

With discovery endpoints in place, the client auto-loads the 19 tools and 2 prompts on connect — no need to pre-declare them in config. The catalog table above is for human readers; clients should read the live spec at /api/mcp/tools/list.

Wiring Cursor

.cursor/mcp.json (or workspace mcp.json):

{
  "mcpServers": {
    "yieldfabric": {
      "url": "https://pay.yieldfabric.com/api/mcp"
    }
  }
}

Cursor auto-discovers tools via the same tools/list endpoint.

Use MCP for agent tooling, not app data flow

MCP is useful when a model-facing tool client needs a compact wallet view, typed actions, 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 MCP tools usually sit beside.
• Authentication & signing — JWT lifecycle and permissions for tool calls.
• API reference — REST and GraphQL operations the MCP tools wrap.