MCP clients and protocol

Last updated from API version 2026-10-06 at 2026-10-28 06:15 UTC (live spec, refreshed hourly). openapi.json

Owlbound is a remote MCP server at https://app.owlbound.ai/api/v1/mcp (Streamable HTTP, JSON responses). Clients that support MCP sign in (Claude, ChatGPT, Claude Code) connect with OAuth: see Connect Claude, ChatGPT or Claude Code. Any other client, script or CI job can send a v1 API key as a Bearer token instead; the tools are then limited to that key's scopes.

• Tools: one per action of the catalog (actions_<family>_<verb>, for example actions_linkedin_connect), plus reads of contacts, companies, tables, credits, events, approvals and action runs, and reads for sequences, senders and search.
• Dry run by default: an action tool only plans and returns a planId. It runs when called again with the same arguments plus apply: true and that planId (same MCP session, 15 minutes).
• Sends always wait for a person: MCP calls run as an agent, so every send and external write is created pending_approval whatever the key's approval mode, and the tool returns the approval link. No tool approves, rejects or changes settings.
• Rate limits, daily caps (agent caps are half the key's or the member's), idempotency and the request log apply to every call.
• Sign in (OAuth 2.1): discovery at /.well-known/oauth-protected-resource/api/v1/mcp, dynamic client registration, PKCE (S256). Access tokens last an hour and refresh tokens 30 days, rotated on every use. The app acts as the member who signed in, in one workspace, with the scopes ticked on the consent screen.

Claude Code with a key#

claude mcp add --transport http owlbound https://app.owlbound.ai/api/v1/mcp \
  --header "Authorization: Bearer $OWLBOUND_API_KEY"

Or in a project .mcp.json (the key stays in your environment):

{
  "mcpServers": {
    "owlbound": {
      "type": "http",
      "url": "https://app.owlbound.ai/api/v1/mcp",
      "headers": { "Authorization": "Bearer ${OWLBOUND_API_KEY}" }
    }
  }
}

Claude Desktop with a key#

The custom connector (sign in, no key) is the simplest way. To use a key instead, go through mcp-remote, in claude_desktop_config.json:

{
  "mcpServers": {
    "owlbound": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://app.owlbound.ai/api/v1/mcp",
        "--header",
        "Authorization:${OWLBOUND_AUTH}"
      ],
      "env": { "OWLBOUND_AUTH": "Bearer owl_sk_..." }
    }
  }
}

Protocol#

JSON-RPC 2.0 over Streamable HTTP. initialize returns an Mcp-Session-Id header that every later request sends. Only POST is served (GET and DELETE answer 405). See POST /mcp.