Quickstart

1. Mint a token

In the dashboard, go to Settings → API keys and create a key. Choose the app scope and permissions; the default is the minimal read bundle. The full pkk_… token is shown once, at creation. Copy it then; it is never displayed again. If you lose it, revoke and mint a new one. See the token guide for scopes, rotation, and expiry.

2. Point your client at the endpoint

Each PorchOps MCP server has its own Streamable HTTP endpoint. Authentication is a bearer token in the Authorization header. The customer-graph server (live at launch) answers on:

https://mcp-customer-graph.porchops.com/mcp

Claude Desktop

Claude Desktop adds remote Streamable HTTP servers as custom connectors, no config file involved. In Settings → Connectors, choose Add custom connector, name it (for example porchops-customer-graph), paste the endpoint URL above, and set an Authorization header with the value Bearer pkk_yourworkspace_…. Save, and the customer-graph tools appear in the tools menu.

Claude Code

Register the server from the CLI:

claude mcp add --transport http porchops-customer-graph \
  https://mcp-customer-graph.porchops.com/mcp \
  --header "Authorization: Bearer pkk_yourworkspace_…"

Cursor

Add the server to your .cursor/mcp.json (or the global config under Cursor Settings → MCP), then reload.

{
  "mcpServers": {
    "porchops-customer-graph": {
      "url": "https://mcp-customer-graph.porchops.com/mcp",
      "headers": {
        "Authorization": "Bearer pkk_yourworkspace_…"
      }
    }
  }
}

Generic MCP client

Any client that speaks the Model Context Protocol over Streamable HTTP works. Most accept an mcpServers-shaped config block:

{
  "mcpServers": {
    "porchops-customer-graph": {
      "type": "http",
      "url": "https://mcp-customer-graph.porchops.com/mcp",
      "headers": {
        "Authorization": "Bearer pkk_yourworkspace_…"
      }
    }
  }
}

Under the hood it is JSON-RPC over HTTP POST with the bearer header; the server responds with JSON or an SSE stream. A raw tools/list call looks like:

POST https://mcp-customer-graph.porchops.com/mcp
Authorization: Bearer pkk_yourworkspace_…
Content-Type: application/json
Accept: application/json, text/event-stream

{ "jsonrpc": "2.0", "id": 1, "method": "tools/list" }

3. Call a tool

Once connected, your agent sees the customer-graph tools in its tool list. Ask it something that needs your customer data, for example:

• “Look up the customer with email founder@heronsoftware.com.”
• “Find paying customers from heronsoftware.com that have been quiet 30+ days.”
• “Show the timeline for that customer, then the runs that touched them.”

The full tool surface (names, permissions, input and output fields, and a worked example per tool) is in the customer-graph tool catalog.

Troubleshooting

• 401 Unauthorized: the token is missing, malformed, revoked, or expired. Check the Authorization: Bearer header and that the token starts with pkk_.
• 403 Forbidden: the workspace is on Free (BYOA is paid-only), or the token lacks the permission the tool needs. Grant the scope when you mint the token.
• 429 Too Many Requests: you hit the per-token rate limit or the workspace daily cap. Honor the Retry-After header. See limits.