MCP Architecture

VaultCrux v1.2 introduces a dedicated MCP service at VaultCrux/apps/mcp.

Service boundary

• Process: @vaultcrux/mcp
• Port: 8091 (host bind 14334)
• Health contracts:
  • GET /healthz
  • GET /readyz
  • GET /metrics
• Tool contracts:
  • GET /capabilities
  • POST /rpc (JSON-RPC 2.0)
  • POST /stream (streamable HTTP, NDJSON JSON-RPC responses)
  • GET /sse (SSE capability + keepalive stream)
  • stdio bridge (pnpm --filter @vaultcrux/mcp stdio)

stdio transport

• Environment:
  • MCP_STDIO_API_KEY (required)
  • MCP_STDIO_TENANT_ID (optional, defaults to default)
• Input/output contract:
  • One JSON-RPC payload per line on stdin.
  • One JSON-RPC response per line on stdout.
  • Invalid JSON lines return JSON-RPC parse error (-32700).

Authentication and rate limiting

• x-tenant-id and x-api-key are required for /rpc and /capabilities.
• Mutating methods additionally require idempotency (x-idempotency-key or tool param).
• Approved mutation execution can include x-shield-approval-token.
• MCP reuses API-key validation and DB-backed minute windows for deterministic 429 + retry-after.

Shield decision pipeline

• MCP evaluates tool calls through Shield before API passthrough.
• Decision outcomes:
  • allow: normal tool execution
  • approval_required: JSON-RPC error with approvalRequestId + decisionId
  • deny: JSON-RPC error with structured denial type and decisionId
• Decisions are persisted to vaultcrux.shield_decisions and emitted as shield.decision outbox events.

Tool map

• query_vault → POST /v1/retrieve
• get_credit_balance → GET /v1/credits/:agentId
• get_credit_escrow → GET /v1/credits/:agentId/escrow
• get_economy_dashboard → GET /v1/economy/dashboard/:agentId
• convert_credits_to_discount → POST /v1/economy/convert
• get_subscription_discount_preview → POST /v1/economy/convert/preview
• tip_platform → POST /v1/economy/tip-platform
• browse_bundles → GET /v1/bundles
• purchase_bundle → POST /v1/bundles/purchase