Connect an MCP Client

Cesteral works with any client that speaks MCP over streamable HTTP — Claude Code, Claude Desktop, ChatGPT, Cursor, or your own custom agent. Connect with an API key (simplest) or OAuth, and every tool call your client makes runs through the same governance pipeline as the in-app assistant: guardrails, approvals, and the audit trail all apply.

An in-app version of this guide lives at Settings → MCP Clients.

1. Create an API Key

Go to Settings → API Keys → Create API Key and pick the scopes the client should have:

The full key (sk_user_…) is shown once at creation — copy it before closing the dialog.

Restricting connector access. When a key carries platform:execute, the create dialog lists your active connections — tick specific ones to limit the key to those connectors only (leave all unticked for unrestricted). A restricted key never sees other connections' tools, and calls to an excluded connection are rejected. Useful for handing one client a key scoped to a single platform.

Organization keys. Organization-owned keys (sk_org_…) work too. The API Keys page follows your current workspace: on an organization subdomain it manages org keys (admins only); on your personal workspace it manages personal keys. MCP calls on an org key are attributed to the user who minted it, and that user's org membership and role are re-checked on every call — the key stops working if they leave the organization.

2. Add the Server to Your Client

The endpoint is https://app.cesteral.com/api/mcp. The key goes in the Authorization: Bearer header (x-api-key also works).

Claude Code

claude mcp add --transport http cesteral https://app.cesteral.com/api/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

Claude Desktop / Cursor (mcp.json)

{
  "mcpServers": {
    "cesteral": {
      "type": "http",
      "url": "https://app.cesteral.com/api/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

Verify the connection

curl -X POST https://app.cesteral.com/api/mcp \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

OAuth Alternative (No API Key)

The API-key flow above is the simplest path. Clients that prefer OAuth 2.1 can instead discover and self-register automatically — point them at the MCP endpoint and they'll do the rest:

1. The client reads protected-resource metadata at https://app.cesteral.com/api/mcp/.well-known/oauth-protected-resource (also surfaced in the WWW-Authenticate header of a 401 from the endpoint).
2. It follows the advertised authorization-server issuer to …/.well-known/oauth-authorization-server.
3. If it has no client_id, it self-registers via Dynamic Client Registration (RFC 7591) at the advertised registration endpoint, sending its redirect URIs and getting back a client_id. Only public PKCE clients are issued (no secret); https redirect URIs and http loopback URIs are accepted.
4. It runs the PKCE authorization-code flow: you sign in and approve the requested scopes at the consent screen. Access tokens last 1 hour; refresh tokens last 30 days and rotate on use.

3. What You'll See

• Workspace tools — census, audiences, automations, campaign analytics, governance management, and more, filtered to the key's scopes.
• Connector tools — with platform:execute, every active external connection's tools appear as connection__tool (e.g. meta__update_budget) with full input schemas and governance annotations. Write tools that haven't passed admission review are hidden.

The tool list is point-in-time: after adding a connection or changing key scopes, have the client re-fetch its tool list.

4. Governance Over MCP

Your policies travel with the key — there is no ungoverned path:

• Approvals — a write that requires human approval returns a structured approval_required result with an approvalId instead of executing. Approve it in the Cesteral app, then run the tool again.
• Blocks — guardrail, pause, and admission blocks return an MCP tool error explaining the policy decision.
• Rate limits — the key's per-minute limit applies; 429 responses carry a Retry-After header.

Troubleshooting