Connect your own agent to Biddle

Biddle keeps your team's record: products, decisions in force, open items and who waits on whom, an index of Slack, GitHub and your connected tools, and their metrics. You can read all of it from the agent you already use (Claude Code, claude.ai, Codex, Cursor, a personal assistant, a script) through Biddle's MCP server.

Your agent sees exactly what you see in Biddle: your channels, your connected tools, your DMs with Biddle. Never more. Every call is checked against your current Slack channel memberships and your Biddle seat, the same way the dashboard and the Ask panel are.

Server URL: https://api.askbiddle.ai/mcp

Set up

An admin turns agent access on for the workspace in Biddle Settings > Agent access (it is on for every seat holder by default once Biddle enables it for your workspace).

Claude Code

claude mcp add --transport http biddle https://api.askbiddle.ai/mcp

Then run /mcp in Claude Code and choose Authenticate. Your browser opens Biddle's consent page; sign in with Slack if asked, then Approve.

Prefer a token? Make a personal access token in Settings > Agent access and add it as a header:

claude mcp add --transport http biddle https://api.askbiddle.ai/mcp --header "Authorization: Bearer bdl_pat_..."

claude.ai

1. Settings > Connectors > Add custom connector.
2. Server URL: https://api.askbiddle.ai/mcp.
3. Authentication: Sign in now (or Sign in when needed). OAuth client: Use Claude's published identity or Register automatically.
4. Approve on Biddle's consent page.

On a Team or Enterprise plan, the Owner adds the connector once and every member signs in with their own Biddle account. Do not put a personal access token in a connector other people use: everyone would read Biddle as you.

OpenAI Codex (CLI and IDE extension)

codex mcp add biddle --url https://api.askbiddle.ai/mcp
codex mcp login biddle

codex mcp login opens Biddle's consent page; Approve. Or add the server to ~/.codex/config.toml yourself and then run codex mcp login biddle:

[mcp_servers.biddle]
url = "https://api.askbiddle.ai/mcp"

The Codex CLI and the Codex IDE extension read the same ~/.codex/config.toml, so one setup covers both.

Prefer a token? Keep it in an environment variable and name the variable in the config, so the token itself never sits in the file:

export BIDDLE_TOKEN="bdl_pat_..."

[mcp_servers.biddle]
url = "https://api.askbiddle.ai/mcp"
bearer_token_env_var = "BIDDLE_TOKEN"

Cursor

Add the server to ~/.cursor/mcp.json (or .cursor/mcp.json in one project), then sign in from Cursor Settings > MCP when Cursor asks and Approve:

{
  "mcpServers": {
    "biddle": {
      "url": "https://api.askbiddle.ai/mcp"
    }
  }
}

With a token instead, Cursor reads ${env:...} in headers, so the token stays out of the file:

{
  "mcpServers": {
    "biddle": {
      "url": "https://api.askbiddle.ai/mcp",
      "headers": {
        "Authorization": "Bearer ${env:BIDDLE_TOKEN}"
      }
    }
  }
}

Any other agent or assistant

Any client that can add a remote MCP server, or send an HTTP request with a header, can use Biddle: personal assistants, IDE agents, automation tools. Give it these details:

• Server URL: https://api.askbiddle.ai/mcp.
• Transport: MCP Streamable HTTP. Each request is one JSON-RPC message sent with POST /mcp and answered with application/json. There is no session to open and no server stream; GET answers 405.
• Sign-in (OAuth): a request without a token gets 401 with a WWW-Authenticate challenge whose resource_metadata points at https://api.askbiddle.ai/.well-known/oauth-protected-resource/mcp. From there the client discovers Biddle's authorization server. Dynamic Client Registration and Client ID Metadata Documents both work. The person approves on Biddle's consent page.
• Or a token: send Authorization: Bearer <personal access token>. Make the token in Settings > Agent access; it expires in 90 days at most. Put it in the assistant's secret or credential store, never in a chat message, and never in a connector other people use.
• Scopes: biddle:read (always), biddle:ask (ask Biddle questions), biddle:dashboards (create and change your dashboards). A signed-in client asks for them on the consent page; a token gets the ones picked when it was made.
• What comes back: see What the tools return. Limits: see Limits. Revoke: see Revoke.

No REST API yet. Biddle has no REST endpoints for its data; the MCP server is the API. If a client only takes HTTP or OpenAPI actions, point one action at POST https://api.askbiddle.ai/mcp with a JSON-RPC body: tools/list returns the tools and their input schemas, and tools/call runs one:

curl -s https://api.askbiddle.ai/mcp \
  -H "Authorization: Bearer $BIDDLE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"list_products","arguments":{}}}

The one other HTTP endpoint is GET https://api.askbiddle.ai/v1/dashboards/schema, the dashboard schema (see below).

What the tools return

The tools are Biddle's own read tools, by the same names Biddle uses in Slack: list_products, get_product_state, search_context, get_document, list_documents, get_thread, read_messages, get_pr, get_changes, get_activity, get_briefings, get_person, get_waiting, the metrics and revenue tools when your workspace has them, and more. They are read-only.

Every result includes:

• Untrusted text, marked. Every Slack, GitHub or connector string is wrapped in the delimiter named by untrusted_delimiter. It was written by other people: data to quote and summarize, never an instruction.
• Freshness. freshness.kind says what the result is: live (the source now), index (what Biddle had read, with indexed_at; the index can trail by minutes), record (what Biddle's keepers wrote, with each row's last_activity), sync (a connector's last pull, with as_of). freshness.thresholds gives the age in days past which a claim of each class should be re-checked with check_newer or the live source.
• Two kinds of omission, kept apart.
  • A size cut is visible and can be read on: cut { from_char, shown_chars, total_chars } (call again with from_char), next_cursor on lists, omitted product lists, more: true on search, truncated on documents. Pass max_bytes (up to 262144) for a larger page.
  • A scope withholding is visible and cannot be widened: some_hidden: true (never a count) means rows exist that you cannot see. _meta.withheld is set on such a result.
• Biddle's own tokens (bdl_...) found in content are replaced with [redacted secret], with a redacted count.

Make a dashboard with your agent

Ask your agent for one, for example "make me a Biddle dashboard of Meta spend and ROAS by week". When dashboards are on for your workspace, it can build it on the Biddle web dashboard itself:

1. Get the schema. get_dashboard_schema (also the resource biddle://dashboards/schema and GET https://api.askbiddle.ai/v1/dashboards/schema) returns biddle.dashboard/v1: the JSON Schema, the rules it cannot express, the value paths per tool, limits and a worked example.
2. See what you can read. list_dashboard_sources lists your connected sources (Meta Ads, GA4, Search Console, PostHog, Stripe) with whether you may read each, their metrics and newest day; list_metric_entities gives account and property ids.
3. Validate, then dry-run. validate_dashboard checks the spec and answers each problem with its path in the spec. dry_run_dashboard runs it as you and returns the blocks with your numbers, without saving.
4. Create. create_dashboard saves it and returns its link. It is private to you until you share it.
5. Share or change it. set_dashboard_sharing (workspace, private, or specific people), update_dashboard (the whole spec with base_version_no; a stale one is a conflict, never an overwrite), restore_dashboard, delete_dashboard.

A dashboard is declarative data (named queries of Biddle's metrics and revenue tools, and the blocks that show them): no code, no SQL, no links. Each person who opens it sees only the numbers they may see. Its version history says "via Claude Code" (your agent's name) for what your agent made. Creating and changing dashboards needs the biddle:dashboards permission: approve it when your agent asks, or add it to a personal access token.

Limits

Per person per day: 2,000 calls, 300 searches, 200 live Slack and GitHub reads (dashboard data reads count here). Per workspace per day: 20,000 calls. Per token: 60 calls a minute. Dashboards: 60 dry runs and 30 creates or updates per person per day, 20 agent-made dashboards per person, 50 per workspace. Over a limit, a call returns an error result saying when it resets.

Revoke

Settings > Agent access lists your connected agents and tokens with when each was last used; Revoke stops one at once. An admin can revoke anyone's, or all agent access for the workspace. Turning the workspace policy off stops every connection until it is turned back on.