Connecting AI assistants (MCP)

Connect Claude, ChatGPT, Copilot or any MCP client to your BioFlow workspace over OAuth 2.1 — setup per client, the 12 tools, the 6 scopes, and the safety rails.

BioFlow ships a remote MCP (Model Context Protocol) server, so any MCP-capable AI assistant can read and edit your bio pages with your permission.

https://app.getbioflow.com/api/mcp

The transport is Streamable HTTP. Authentication is OAuth 2.1 with PKCE and dynamic client registration — no pre-shared API keys. Tokens are scoped to a single workspace, so an agent only ever sees the workspace you connected it to.

MCP access is included on every plan, including Free. Tool calls ride your plan's existing limits; over-limit calls get a structured QUOTA_EXCEEDED response instead of failing silently.

Supported clients

Any MCP client that speaks Streamable HTTP with OAuth works, including Claude (web and desktop, as a custom connector), Claude Code, ChatGPT, Microsoft Copilot, and MCP Inspector.

Claude Code — one command, then sign in when prompted:

claude mcp add --transport http bioflow https://app.getbioflow.com/api/mcp

Claude (web and desktop):

Open Settings, then Connectors.
Choose "Add custom connector".
Paste the server URL above and connect.
Approve the scopes on BioFlow's consent screen.

Everything else — ChatGPT, Copilot, MCP Inspector, your own agent framework: point the client at the same server URL. Registration is dynamic, so there is nothing to pre-provision on either side.

Available tools

The server exposes 12 tools, each guarded by one OAuth scope:

Tool	What it does	Scope
`page.list`	List every bio page in the workspace: title, slug, publish status, block count, route, and theme	`pages:read`
`page.get`	Read one page's draft and published state — blocks with ids, theme, route, and the draft `updatedAt` that write tools require	`pages:read`
`analytics.summary`	Workspace analytics for the last 7/30/90 days: views, clicks, unique visitors, CTR, top links, referrers, and tip revenue	`analytics:read`
`contacts.list`	List captured contacts and leads (newsletter signups, form submissions, gated downloads), newest first	`contacts:read`
`file.list`	List uploaded files (name, MIME type, public path) for wiring into image, file, carousel, or product blocks	`files:read`
`page.create`	Create a new bio page as an unpublished draft — it never publishes; going live requires `page.publish`	`pages:write`
`page.update_draft`	Edit the draft's title, description, theme, or existing blocks by id — everything you don't mention is preserved	`pages:write`
`page.add_block`	Append one new block to the draft, preserving every existing block byte-for-byte	`pages:write`
`page.remove_block`	Delete specific blocks from the draft by id; refuses to clear the entire page	`pages:write`
`page.reorder_blocks`	Rearrange the draft's blocks without editing their content — every block id listed exactly once	`pages:write`
`page.publish`	Publish the draft to the live public page. Two-step: the first call returns a preview plus a `confirmToken`, the second commits	`publish`
`page.schedule_publish`	Schedule the page to publish at a future time. Two-step confirm; the commit call must repeat the same `startsAt`	`publish`

page.publish and page.schedule_publish are the dangerous set: they change what real visitors see, so they need the publish scope AND a per-workspace "dangerous operations" toggle that ships OFF.

Scopes

You grant exactly what an app asked for. These are the descriptions shown on the consent screen:

Scope	What it grants
`pages:read`	See your bio pages, blocks, and themes
`pages:write`	Create and edit drafts of your bio pages
`analytics:read`	See your page views, clicks, and traffic sources
`contacts:read`	See your captured contacts and leads
`files:read`	See your uploaded files and media
`publish`	Publish changes to your live pages

An agent calling a tool outside its granted scopes gets a structured SCOPE_MISSING denial — never silent partial access.

Safety rails

Consent screen. You approve exactly which scopes an app gets when it connects, each listed in plain language.
Drafts stay drafts. Write tools only ever touch the draft; nothing an agent does reaches your live page on its own.
Publishing is off by default per workspace, and even after you enable it, every publish is a two-step flow: the first call returns a preview plus a short-lived confirm token (valid 10 minutes), and nothing commits until a second call with that token.
Optimistic concurrency. Every write tool requires the expectedUpdatedAt you read from page.get, so a stale draft is refused rather than clobbered. Writes also accept an optional idempotencyKey so a retried call cannot run twice.
Audit trail. Every tool call is logged; review it in Settings, under Connected AI apps.
Instant revocation. Revoke any connected app from Settings, under Connected AI apps — its access and refresh tokens stop working immediately.

Structured denials

Every refusal is a typed code an agent can act on, never a mystery error or a silent no-op:

Code	What it means
`SCOPE_MISSING`	The tool needs a scope this connection was never granted. Reconnect and approve it.
`DANGEROUS_OPS_DISABLED`	A publish-class tool while the workspace toggle is off. The denial carries a deep link to that setting.
`QUOTA_EXCEEDED`	The call would pass your plan's limits.
`STALE_SNAPSHOT`	The draft changed between the preview call and the commit call, so the commit was refused.
`CONFIRM_TOKEN_INVALID`	The `confirmToken` was forged, expired, or minted for a different operation.

OAuth discovery

Discovery follows RFC 8414 (authorization server metadata) and RFC 9728 (protected resource metadata); clients register themselves through unauthenticated dynamic client registration per RFC 7591. The documents are served at:

https://app.getbioflow.com/.well-known/oauth-authorization-server
https://app.getbioflow.com/.well-known/oauth-protected-resource