Connect a custom agent

If you are building your own agent (for example with an Agent SDK) or using an MCP client that is not Claude or ChatGPT, you connect to the same two B2Trader endpoints and the same OAuth flow. This page covers the OAuth details a custom client needs. Pick the surface you need first — see Overview:

Read-only: https://<your-broker-domain>/mcp-read-only
Full access: https://<your-broker-domain>/mcp-full-access

OAuth discovery

Your client needs no B2Trader-specific configuration beyond the MCP URL. B2Trader is an OAuth 2.1 protected resource and advertises everything a compliant client needs:

Your client calls the MCP endpoint without a token and receives 401 Unauthorized with a WWW-Authenticate: Bearer resource_metadata="…" header.
That header points at https://<your-broker-domain>/.well-known/oauth-protected-resource (RFC 9728) for the surface you called. Fetching it returns the resource identifier, the authorization server (your broker's Keycloak realm), and scopes_supported — one scope only, matching the surface: [mcp:read] for /mcp-read-only, [mcp:trade] for /mcp-full-access.
Your client runs the standard OAuth 2.1 authorization-code flow with PKCE against that authorization server, requesting the scope for the surface you want.
B2Trader validates the token's audience (bbp-mcp) and the required scope (mcp:read for read-only, mcp:trade for full access) before serving any tool.

Use a compliant MCP client library — it performs discovery, PKCE, and token refresh for you. You only supply the MCP URL.

Pre-registered OAuth clients

B2Trader ships two pre-registered public OAuth clients. Use the one matching your surface:

Surface	`client_id`	Scope	Consent
Read-only	`mcp-read-only`	`mcp:read`	None
Full access	`mcp-full-access`	`mcp:trade`	Explicit trade-scope consent

Both are public clients (no client secret) and require PKCE (S256). A custom client authenticates as one of these client_ids and completes the browser sign-in as any other agent does. Depending on how your broker set up your platform, the page that opens is either the B2Trader sign-in form or the sign-in page of the portal you normally use to access your account — your client behaves the same either way.

Command-line agents (Codex CLI, Claude Code)

Command-line MCP clients default to Dynamic Client Registration (DCR) — on first connect they try to register a brand-new OAuth client with the authorization server instead of using a fixed client_id. The B2Trader Keycloak realm does not permit anonymous DCR, so these tools must be told to use one of the pre-registered client_ids above:

Codex CLI:

codex mcp add <name> --url <mcp-url> --oauth-client-id mcp-full-access
codex mcp login <name>

Use mcp-read-only in place of mcp-full-access for the read-only surface.

Claude Code:

claude mcp add --transport http --client-id mcp-full-access --callback-port 8080 <name> <mcp-url>

Without an explicit client_id, both tools fall back to anonymous DCR, which the authorization server rejects — the connection fails before you reach the sign-in page.

Redirect URIs

The pre-registered clients accept these redirect URIs:

Redirect URI	Use
`https://claude.ai/api/mcp/auth_callback`	Claude (claude.ai)
`https://chatgpt.com/connector_platform_oauth_redirect`	ChatGPT
`http://localhost:8080/*`	Claude Code — fixed callback port
`http://127.0.0.1/*`	Codex CLI and other loopback clients — ephemeral port

If your custom agent runs locally, use one of the loopback redirects above. Most Agent SDKs and MCP client libraries (including Codex CLI) default to an ephemeral-port loopback callback on 127.0.0.1, matching http://127.0.0.1/*, so no configuration change is needed. Claude Code is the exception: it needs a fixed callback port to match a registered redirect, so pass --callback-port 8080 (matching http://localhost:8080/*) as shown above.

Adding a custom redirect URI (broker step)

If your agent runs on a hosted callback URL that is not one of the above (for example a server-side agent with its own public redirect), your broker must add that redirect URI to the pre-registered client in Keycloak before sign-in will succeed.

A redirect URI that is not registered on the client fails at the sign-in step with an "Invalid redirect URI" error from Keycloak. Send your broker the exact callback URL your agent uses and which surface it needs (read-only or full access).

Adding a redirect URI is a broker-side change to the MCP client registration. It requires no product change and is the documented path for onboarding custom, non-marketplace agents.

Full access

If your custom agent uses the full-access surface, the same full-access safety rules apply: no per-action confirmation, irreversible actions, and the prompt-injection risk of an autonomous agent. Read that page before granting mcp:trade.