SITEMAP / DOCS / AGENTS

MCP Setup

Waypath ships an MCP (Model Context Protocol) server at https://mcp.waypath.app. Once registered, any MCP-aware agent (Claude Desktop, Cursor, custom Anthropic SDK loops) gets four tools: get_customer_context, get_account_brief, write_memory, ingest_event. Same surface as the REST API, but the agent calls them by name instead of by URL.

01Claude Code / Cursor

claude mcp add --transport http waypath https://mcp.waypath.app -s user

That writes the registration to your user-scope MCP config. New Claude sessions pick it up automatically. You will be prompted for your wp_live_... key on first use.

02Claude Desktop

Coming soon — @waypath/mcp is not yet on the npm registry. The config shape below is final; the npx form will work the moment the package ships. Until then, use the HTTP transport above (https://mcp.waypath.app) for Claude Desktop too — Claude supports --transport http on macOS and Windows.

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

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

Restart Claude Desktop. Test it by asking "what do you know about jane@acme.com" - the model should call get_customer_context unprompted.

03ChatGPT / OpenAI / generic agent loops

OpenAI's hosted apps do not yet speak MCP over HTTP. Use the REST API directly. Every MCP tool maps 1:1 to a REST endpoint:

MCP toolREST endpoint
get_customer_contextGET /v1/context/{id} or GET /v1/context?email=
get_account_briefGET /v1/account/{id}
write_memoryPOST /v1/memory
ingest_eventPOST /v1/events

See Customer Context, Account Brief, Memory Writes, Events for full contracts.

04Tool reference

get_customer_context

{
  id?: string         // Customer ID
  email?: string      // OR resolve by email
  budget?: number     // Token budget. Default 2048.
}

Returns the CustomerContext shape.

get_account_brief

{
  id: string          // Account ID
}

Returns the AccountBrief shape.

write_memory

{
  customer: string
  type: 'decision' | 'action' | 'observation'
  agent: string
  payload: object
  idempotency_key?: string
}

Returns { id, customer, type, ts, idempotency_key? }.

ingest_event

{
  event: string
  customer?: string
  email?: string
  phone?: string
  externalId?: string
  properties?: object
  timestamp?: string  // ISO-8601
}

Returns { eventId, customerId, resolved }.

05Auth

The MCP server reads WAYPATH_API_KEY from env. With Claude Code's claude mcp add flow, the CLI prompts on first use and persists the key to its user-scope config. With Claude Desktop's JSON config, you set env.WAYPATH_API_KEY directly.

The same key scopes apply. A key with only context:read will fail write_memory calls with forbidden_scope.

06Troubleshooting

SymptomCause
"MCP server failed to start"WAYPATH_API_KEY not set, or npx @waypath/mcp cannot reach the registry.
Tools missing from ClaudeRestart Claude Desktop after editing the config. Cursor picks up changes per-session.
401 on every callKey was revoked or rotated. Issue a new one and update the env.
403 on write_memoryKey lacks memory:write scope. Re-issue with the right scope.

07See also