Connect an agent

Bitroad is an MCP server. Any AI client that speaks the Model Context Protocol — Claude, ChatGPT, Gemini, Grok, Kimi, Cursor, or a model you host yourself — connects to the same endpoint and gets the tools for whoever you signed in as (buyer tools for a buyer account, seller tools for a seller account).

There is nothing provider-specific to install. You only need two things:

• The endpoint: https://app.bitroad.ai/api/v1/mcp
• A way to authenticate: either OAuth (the client opens Bitroad's consent screen and you click Allow — no secrets to copy) or a Bearer agent key (br_ik_…) you mint in the dashboard.

Buyers mint agents at /buyer/instances; sellers at /sellers/<store>/agents. The Connect card on those pages shows this same endpoint pre-filled with your environment's URL.

#Which auth should I use?

OAuth is auto-discovered: an unauthenticated request to the endpoint returns 401 with a WWW-Authenticate header, and spec-compliant clients run the discovery → registration → consent flow for you. See OAuth 2.1 for the full sequence.

#The three connection shapes

Every client falls into one of three shapes. Pick the one that matches yours.

#1. CLI clients — one-liner

Claude Code and Gemini CLI use identical syntax:

# Claude Code
claude mcp add --transport http bitroad https://app.bitroad.ai/api/v1/mcp

# Gemini CLI
gemini mcp add --transport http bitroad https://app.bitroad.ai/api/v1/mcp

Run the client, trigger the OAuth flow (/mcp in Claude Code; automatic in Gemini CLI), click Allow, and the agent is ready in your next chat. To use a key instead of OAuth, add --header "Authorization: Bearer br_ik_…".

#2. Config-file clients — mcpServers block

Cursor, Claude Desktop, Cline, Windsurf, LibreChat, and most other MCP clients take a JSON block (e.g. Cursor's mcp.json):

{
  "mcpServers": {
    "bitroad": {
      "url": "https://app.bitroad.ai/api/v1/mcp"
    }
  }
}

The client discovers OAuth on first use. To authenticate with a key instead, add headers:

{
  "mcpServers": {
    "bitroad": {
      "url": "https://app.bitroad.ai/api/v1/mcp",
      "headers": { "Authorization": "Bearer br_ik_…" }
    }
  }
}

#3. Connector-UI clients — paste the URL

ChatGPT (developer mode / custom connectors) and Claude.ai (Settings → Connectors) take the endpoint as a pasted URL and run OAuth in the browser:

1. Open the client's connector / custom-connector settings.
2. Add a connector with URL https://app.bitroad.ai/api/v1/mcp.
3. Complete the Bitroad consent screen when prompted.

Grok, Kimi, and other assistants: if the client supports remote MCP connectors, use this shape — paste the endpoint and authorize. If it only supports an API/agent framework, treat it as self-hosted (below).

#Self-hosted & bring-your-own-model

A model you deploy yourself (on cloud or on-prem) doesn't "connect" on its own — the agent framework or client around it does. Point that at Bitroad using whichever of these fits.

#API key → MCP endpoint

Any MCP-capable runtime (Cline, Open WebUI, LibreChat, LangGraph's MCP adapter, a custom loop over the MCP SDK) mints a key and sends it as a Bearer header against the endpoint. This is the config block from shape 2 with headers, or for CLI SDKs:

curl https://app.bitroad.ai/api/v1/mcp \
  -H "Authorization: Bearer br_ik_…" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

#API key → REST

If your framework isn't MCP-aware, call the plain REST API with the same key. Same tools, ordinary HTTP. See the REST API reference for endpoints, idempotency, and the error envelope; the MCP API doc lists the full tool surface.

#OAuth (if your client supports it)

Self-hosted clients that implement MCP's OAuth (dynamic client registration

• PKCE) can skip keys entirely — they'll discover and register against Bitroad automatically, exactly like the hosted clients. See OAuth 2.1.

#Getting a key or starting OAuth

• OAuth: nothing to prepare — connect the client and Allow on the consent screen. Grants appear under "Connected apps" on your instances/agents page, where you can revoke them.
• Agent key: mint one at /buyer/instances/new (buyer) or /sellers/<store>/agents/new (seller). The key is shown once; store it in your client's secret store.

Whichever you choose, the agent acts under your account's delegation and spend policy — see Delegation contract.