MCP Setup

Waypath ships an MCP (Model Context Protocol) adapter for external coding agents. It does not maintain a separate tool catalog. MCP tools are generated from:

GET /api/v1/capabilities

and each tool call invokes:

POST /api/v1/capabilities/:id/invoke

That keeps MCP behavior identical to API and CLI behavior for grants, allowed modes, quota, idempotency, AOS approval, receipts, and audit history.

01Hosted HTTP

Use the hosted endpoint when your MCP client supports HTTP transport:

claude mcp add --transport http waypath https://mcp.waypath.app \
  --header "Authorization: Bearer wp_live_..." \
  -s user

Every HTTP MCP request must include either:

Authorization: Bearer wp_live_...

or:

X-API-Key: wp_live_...

Each HTTP MCP session is bound to the key used at initialize time. Requests that reuse the same MCP session id with a different key are rejected.

02Local stdio

Use local stdio for Claude Desktop, Cursor, Codex, or any client that launches an MCP process. Stdio mode reads the key from WAYPATH_API_KEY.

{
  "mcpServers": {
    "waypath": {
      "command": "npx",
      "args": ["-y", "@waypath/mcp"],
      "env": {
        "WAYPATH_API_KEY": "wp_live_...",
        "WAYPATH_API_BASE": "https://api.waypath.app"
      }
    }
  }
}

For local development against this repo:

npm run build -w @waypath/mcp

{
  "mcpServers": {
    "waypath-local": {
      "command": "node",
      "args": ["D:/Waypath/Waypath V2/App/packages/mcp/dist/index.js"],
      "env": {
        "WAYPATH_API_KEY": "wp_live_...",
        "WAYPATH_API_BASE": "http://localhost:4747"
      }
    }
  }
}

03Tool discovery

The tool list is filtered by the active key's grants and modes. A key with only capability:context.get sees only the context tool. A key with capability:queue.outreach and queue mode sees the outreach queue tool, but not direct execute-only behavior.

Tool descriptions include:

• capability id
• human title and description
• input schema
• examples
• action-credit cost
• allowed modes
• side-effect class
• approval behavior
• receipt and pending-action behavior

Current examples include:

04Calling tools

Each MCP tool schema includes the capability input fields plus an optional _mode field:

{
  "_mode": "dry_run"
}

Allowed values are:

• dry_run
• queue
• execute

If _mode is omitted, the MCP adapter follows the gateway defaults. Read-only and low-risk writeback capabilities execute. queue.* capabilities queue. Side-effecting execute capabilities queue when approval is required.

05Responses

MCP returns structured JSON text with the same envelope as the REST gateway:

{
  "status": "queued",
  "result": {},
  "pending_action_id": "pa_123",
  "action_credit_cost": 2,
  "request_id": "req_123",
  "quota": {
    "plan": "growth",
    "limit": 3000,
    "used": 221,
    "remaining": 2779
  },
  "receipt_url": "/api/v1/capabilities/actions/req_123",
  "pending_receipt_url": "/api/v1/capabilities/pending/pa_123"
}

Agents should store request_id for receipts and pending_action_id when an operator approval is required.

06Self-hosted HTTP

npx -y @waypath/mcp --http --port 3737
npx -y @waypath/mcp --http --public --port 3737

GET /healthz is public. All MCP traffic on / requires a wp_live_... key. By default, --http binds to 127.0.0.1. Use --public only behind TLS and reverse-proxy controls.

07Troubleshooting

08See also

• Quickstart
• Capabilities
• API Keys
• CLI