Connect your account to an IDE (MCP)

What this is

CustomAgents runs a hosted MCP server so your AI coding tools can read and act on your account — list agents, search contacts, read conversations, send messages — using the same scoped API key you already use for REST.

The server is Streamable HTTP and stateless: every request re-validates your bearer key, there is no server-issued session to hijack, and no local process to install.

Account MCP endpoint:  https://api.customagents.io/v1/mcp

Authenticate with an account key (ca_acct_…). For an MCP bound to a single agent, see Per-Agent API & MCP.

IDE configuration

All clients authenticate the same way: Authorization: Bearer ca_acct_…. Generate the key in Settings → API Keys (details).

Claude Code (CLI)

claude mcp add --transport http custom-agents \
  https://api.customagents.io/v1/mcp \
  --header "Authorization: Bearer ca_acct_YOUR_KEY"

Cursor

Add to ~/.cursor/mcp.json (or the project's .cursor/mcp.json):

{
  "mcpServers": {
    "custom-agents": {
      "url": "https://api.customagents.io/v1/mcp",
      "headers": {
        "Authorization": "Bearer ca_acct_YOUR_KEY"
      }
    }
  }
}

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "custom-agents": {
      "url": "https://api.customagents.io/v1/mcp",
      "headers": {
        "Authorization": "Bearer ca_acct_YOUR_KEY"
      }
    }
  }
}

VS Code

Add to .vscode/mcp.json (note the servers key and "type": "http"):

{
  "servers": {
    "custom-agents": {
      "type": "http",
      "url": "https://api.customagents.io/v1/mcp",
      "headers": {
        "Authorization": "Bearer ca_acct_YOUR_KEY"
      }
    }
  }
}

Account tool catalog

Each tool requires a scope. If your key lacks the scope, the tool is not registered and the IDE never sees it. Tools marked destructive mutate data or spend money and trigger an explicit confirmation prompt in the IDE before they run.

Security model

• No token passthrough. Your key is validated against our database and the tool handler calls our own controllers in-process. The token never reaches a third-party authorization server, so the confused-deputy class doesn't apply.
• Identity is bound to the key, not the input. Every tool handler is closed over the organizationId and scopes resolved from your validated key. A tool can't be tricked into acting on another account by its arguments.
• Stateless. Each request re-validates the bearer key. There's no session id to steal.
• Origin checked. The server validates the Origin header to defend against DNS-rebinding from a local browser.
• Rate limited & spend-capped. MCP requests are subject to per-key rate limits, and money-spending tools respect your key's spend cap.

OAuth sign-in (no key to copy)

You can connect without pasting a key: add the MCP server URL and sign in. This works in clients that support remote MCP with OAuth (Claude Desktop / claude.ai connectors, Claude Code, Cursor, VS Code, ChatGPT custom connectors).

1. In your client, add the MCP server https://api.customagents.io/v1/mcp (for a single agent, https://api.customagents.io/v1/agents/AGENT_ID/mcp).
2. The client discovers the OAuth endpoints automatically (RFC 9728 protected-resource metadata) and opens a browser to sign in.
3. On the consent screen you pick the organization (and, for a per-agent connection, the agent), choose exactly which permissions to grant, and optionally set a spend cap. Permissions that can spend credits are flagged.
4. Approve, and the client is connected — no key handling. Manage or revoke connections any time under Settings → Connected Apps.

How it maps to scopes: an OAuth connection grants the same scopes as an API key (the consent screen is the scope picker), and authorization is identical — messages:send is email-only, SMS needs messages:send:sms, and so on. Static ca_acct_ / ca_agt_ bearer keys keep working unchanged as the fallback for clients that don't do OAuth.

Security: the access token never carries your org — the org/agent binding is decided by you at consent and re-verified against your live membership on every request, so a connection can't reach an org you've left or were removed from. Revoking a connection cuts off its tokens immediately.

See also

• API Keys & Scopes
• Per-Agent API & MCP
• API Reference