Connect an AI agent
BayesBoard runs a hosted MCP server. Point your agent at it with an API key and it can build, evaluate and export decision boards in your workspace, and interview you for the numbers instead of making them up. No extension or plugin is needed: every client below connects with a few lines of configuration.
Endpoint
- URL:
https://app.bayesboard.com/mcp(the olderhttps://app.bayesboard.com/api/mcpserves the same server). - Transport: Streamable HTTP, stateless. Each request is one POST; replies are JSON. There is no session and no standalone event stream, so GET answers 405.
- Protocol versions:
2026-07-28(per-request metadata,server/discover) and the handshake versions2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05(initialize). Your client picks; you do not need to set anything. - Auth:
Authorization: Bearer bb_live_...on every request. Keys are part of the Agent plan; create one under Dashboard, API keys. It is shown once. Anyone holding it can act in your workspace until you revoke it. - The same key works on the REST API under
/api/boards, which is what every MCP tool calls.
Keys and access
Choose a key's access when you create it. New keys get read and write unless you choose otherwise.
| Scope | What it allows | Tools |
|---|---|---|
Read boards:read | Every key has it. Lists, exports, evaluates and runs sensitivity and next_question. | list_examples, get_example, evaluate_example, list_boards, next_question, evaluate_board, run_sensitivity, export_board |
Propose boards:propose | Reserved for proposing changes that a person reviews before they apply. Not available yet, so a read and propose key can only read for now. | None yet |
Write boards:write | Creates boards and changes them: nodes, edges, imports, docs, comments and share links. | create_board, add_node, add_edge, update_node, update_edge, import_board |
Use a read-only key when an agent should only look, for example to summarise or check boards in CI. A key acts as the member who created it, inside one workspace, with the same row-level security as the editor.
Client setup
Replace bb_live_YOUR_KEY with your key, or keep the key in an environment variable where the client supports it. Each client says whether we have run it end to end.
Claude Code
Verified 2026-11-15 with Claude Code 2.1.316Run once in a terminal. Add --scope project to share it with a repository through .mcp.json (keep the key out of git: use "Bearer ${BAYESBOARD_API_KEY}" there).
claude mcp add --transport http bayesboard https://app.bayesboard.com/mcp \
--header "Authorization: Bearer bb_live_YOUR_KEY"Or leave out --header: Claude Code then signs you in with OAuth (run /mcp, then Authenticate). The OAuth path is not yet verified with Claude Code.
Checked: connects over MCP 2026-07-28 (server/discover, tools/list, prompts/list) and, against the previous server, falls back to the 2025-11-25 handshake; tool calls were run with the MCP TypeScript SDK below.
VS Code (agent mode)
Unverified.vscode/mcp.json in your workspace. VS Code asks for the key once and stores it as a secret.
{
"inputs": [
{
"type": "promptString",
"id": "bayesboard-key",
"description": "BayesBoard API key (bb_live_...)",
"password": true
}
],
"servers": {
"bayesboard": {
"type": "http",
"url": "https://app.bayesboard.com/mcp",
"headers": { "Authorization": "Bearer ${input:bayesboard-key}" }
}
}
}Cursor
Unverified.cursor/mcp.json in a project, or ~/.cursor/mcp.json for every project. Set BAYESBOARD_API_KEY in your environment.
{
"mcpServers": {
"bayesboard": {
"url": "https://app.bayesboard.com/mcp",
"headers": { "Authorization": "Bearer ${env:BAYESBOARD_API_KEY}" }
}
}
}Claude Desktop
Unverifiedclaude_desktop_config.json (Settings, Developer, Edit Config). It runs the mcp-remote bridge, which forwards the key as a header. Needs Node.js.
{
"mcpServers": {
"bayesboard": {
"command": "npx",
"args": [
"-y", "mcp-remote", "https://app.bayesboard.com/mcp",
"--header", "Authorization:${AUTH_HEADER}"
],
"env": { "AUTH_HEADER": "Bearer bb_live_YOUR_KEY" }
}
}
}Or skip the bridge: add BayesBoard as a custom connector (below) and sign in with OAuth.
ChatGPT
UnverifiedSettings, Apps and Connectors, Advanced: turn on Developer mode. Then Create, paste this URL and choose OAuth. ChatGPT registers itself and sends you to BayesBoard to allow access. Without signing in it can still open the example boards.
https://app.bayesboard.com/mcp/guestClaude (custom connector)
Unverifiedclaude.ai or Claude Desktop: Settings, Connectors, Add custom connector. Paste this URL; Claude sends you to BayesBoard to sign in and allow access.
https://app.bayesboard.com/mcpMCP TypeScript SDK with OAuth sign-in
Verified 2026-11-16 with @modelcontextprotocol/sdk 1.32.2For your own agent that acts for a person: pass an OAuthClientProvider and the SDK discovers BayesBoard, registers, opens the consent screen (PKCE) and refreshes tokens.
import { Client } from '@modelcontextprotocol/sdk/client/index.js'
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js'
// authProvider implements OAuthClientProvider (redirectUrl, clientMetadata,
// token and verifier storage, redirectToAuthorization).
const transport = new StreamableHTTPClientTransport(new URL('https://app.bayesboard.com/mcp'), { authProvider })
const client = new Client({ name: 'my-agent', version: '1.0.0' })
await client.connect(transport) // first run: UnauthorizedError, then transport.finishAuth(code)Checked: discovery from the 401, dynamic registration, consent in a browser, PKCE token exchange, tools/list, list_boards and evaluate_example against a build of this release wired to the staging database.
MCP TypeScript SDK (your own agent)
Verified 2026-11-16 with @modelcontextprotocol/sdk 1.32.2npm install @modelcontextprotocol/sdk, then connect with the Streamable HTTP transport.
import { Client } from '@modelcontextprotocol/sdk/client/index.js'
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js'
const transport = new StreamableHTTPClientTransport(new URL('https://app.bayesboard.com/mcp'), {
requestInit: { headers: { Authorization: `Bearer ${process.env.BAYESBOARD_API_KEY}` } },
})
const client = new Client({ name: 'my-agent', version: '1.0.0' })
await client.connect(transport)
const { tools } = await client.listTools()
const boards = await client.callTool({ name: 'list_boards', arguments: {} })Checked: connect, tools/list, prompts/list, create_board, add_node, add_edge, evaluate_board and next_question on staging.
Any HTTP client (curl)
Verified 2026-11-15 with curl 8.7.1One JSON-RPC 2.0 message per POST; the reply is JSON. Clients on MCP 2026-07-28 also send _meta and the MCP-Protocol-Version, Mcp-Method and Mcp-Name headers.
curl -s https://app.bayesboard.com/mcp \
-H "Authorization: Bearer bb_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
"params":{"name":"list_boards","arguments":{}}}'Checked: tools/call list_boards and create_board on staging.
60-second demo
Once your client is connected, paste this into the chat. The agent builds the board as you answer, then evaluates it. Open the board in the editor afterwards to see every number and where it came from.
Use the BayesBoard tools to help me decide: "Should we expand to the EU next quarter?"
1. Create a board for it and suggest two competing hypotheses. Ask me for a prior for each; do not invent numbers.
2. Get the elicit_board prompt and follow it: ask me for three pieces of evidence, one at a time, and how strongly each one points.
3. Add them to the board, then evaluate it.
4. Tell me where each hypothesis ended up, which input moved it most, and call next_question to say what you would ask me next.Errors you may see
Tool errors come back as a tool result the agent can read; the text always says what to do next.
- 401 API_KEY_REQUIRED, INVALID_API_KEY
- No key, a mistyped key, or one that was revoked or expired. Send "Authorization: Bearer bb_live_..." with a current key.
- 401 TOKEN_EXPIRED, TOKEN_REVOKED, INVALID_TOKEN
- An OAuth sign-in that expired, was disconnected, or was made for another server. Your client refreshes or signs in again on its own; if not, reconnect it.
- 403 PLAN_REQUIRED
- The workspace behind the key has no active Agent plan. Check the plan on the pricing page.
- 403 INSUFFICIENT_SCOPE
- The key lacks the scope this tool or route needs (the reply names it). Create a key with that access under Dashboard, API keys.
- 409 VERSION_CONFLICT
- The board changed since the agent last read it, for example in the editor. Read it again (export_board or evaluate_board) and retry with the new version.
- 428 PRECONDITION_REQUIRED
- A change was sent without expectedVersion. Send the version from your last response for that board.
- 429
- More than 120 requests a minute from one key. Wait for the Retry-After seconds, then retry.
- 400 with -32022
- The client asked for a protocol version this server does not speak. Pick one from error.data.supported.
- 400 with -32020
- A 2026-07-28 request whose MCP-Protocol-Version, Mcp-Method or Mcp-Name header does not match its body. Send the headers your MCP library builds; do not edit them by hand.
OAuth
Clients that cannot send an API key header, such as ChatGPT and Claude custom connectors, sign in with OAuth instead. Give them https://app.bayesboard.com/mcp (or https://app.bayesboard.com/mcp/guest for ChatGPT, see below). The client finds BayesBoard's sign-in on its own, registers, and sends you to a BayesBoard page that names the app, shows where you will return to, and asks which workspace it may use and whether it may only read or also change boards. Nothing happens until you choose Allow.
Who may connect: every account, on every plan, can connect an app that reads boards (list, open, evaluate, sensitivity and next question). Letting an app change boards (boards:write, or propose changes) needs the Agent plan: on another plan the consent screen offers read only and the app is told why when it tries to write. The plan is checked on every request, so after a downgrade a connected app can still read but no longer write; after an upgrade, reconnect the app to allow writing.
A connected app gets the same scopes as an API key (boards:read, boards:write) in one workspace only, and can never publish a board, manage keys or change your account. Its access token lasts an hour and is renewed with a refresh token that changes on every use. See and disconnect connected apps under Dashboard, API keys, Connected apps.
https://app.bayesboard.com/mcp/guest also works without an account: it lists every tool, but only the example tools (list_examples, get_example, evaluate_example) run until you sign in. They read the demo boards and starter templates only, store nothing and are rate-limited.
For developers: protected resource metadata at /.well-known/oauth-protected-resource/mcp, authorization server metadata at /.well-known/oauth-authorization-server, dynamic client registration (public clients, https or loopback redirect URIs), authorization code with PKCE S256 only, the resource parameter (RFC 8707) and iss in the redirect (RFC 9207), revocation (RFC 7009) at /oauth/revoke. MCP authorization spec 2026-07-28.