# MCP server

The hosted Model Context Protocol server, so an AI assistant can do what your key can do and nothing more.

Bolt Claw runs a hosted Model Context Protocol (MCP) server, so an AI assistant
can manage your pages, posts, inbox, automations, leads and referral programs
directly.

- **Endpoint** — `https://mcp.boltclaw.ai/mcp` (Streamable HTTP, stateless)
- **Sign in** — add it as a connector and approve it in your browser. No key to
  copy, no file to edit.
- **Or bring a key** — `Authorization: Bearer bc_live_...` still works, at the
  same endpoint and at `https://boltclaw.ai/api/mcp`.

**The assistant can do exactly what you allowed, and nothing else.** Every tool
is one call to this API with a key, so the key's scopes, its rate limit and
every rule on these pages apply unchanged. There is no second path.

## Signing in

Add `https://mcp.boltclaw.ai/mcp` in your assistant's connector or MCP settings.
It opens a Bolt Claw page in your browser where you choose:

- **which workspaces** the assistant may work in, and
- **what it may do** in them, one row per area set to No access, Read, or Read
  and write.

Approve, and the assistant is connected. **The key is made by the server and
never passes through the conversation** — it is generated in Cloudflare, Bolt
Claw only ever sees its SHA-256, and the assistant never sees it at all. You can
see the connection, change its permissions, or end it, under
[Settings → AI agents](https://boltclaw.ai/settings/agents) — and ending it there
is what actually ends it.

A connection lasts 90 days and renews itself while it is in use, up to a year;
after that you sign in again. Signing out in your assistant ("clear
authentication", "disconnect") revokes the key too.

**Several workspaces, one connection.** Tools act on the connection's default
workspace unless the assistant passes `workspace` (an id or name from
`list_workspaces`). Each workspace gets its own key behind the scenes, so a
refusal in one is a refusal in one.

## What an assistant can never do

Whatever you grant it, a connection's key **cannot carry `keys:*`,
`webhooks:*`, `referrals:embed` or `referrals:payouts` at all** — refused in the database at the
sign-in, at every later edit, and on every request. A credential acting on its own should not be
able to issue credentials or point your data at a new address, and it sends a referral payout batch
only after a person who is signed in with two-step verification approves it.

The same goes for the AI agent settings themselves, approving its own requests,
changing your access or anyone else's, deleting a workspace or the organisation,
card details, plan changes, connecting a social account, blocking somebody from
a page, and payout details. So do the referral steps that need a credential or
your own two-step session: connecting a billing system, a payout account or a
Shopify shop, your tax details and the 1099 files, and exporting a waitlist's
email addresses. Ask an assistant to do one and it will give you the dashboard
link, and tell you what it can do instead, rather than trying.

## Asking first, and approvals

Two separate things sit between an assistant and anything consequential.

**Confirmation** is the assistant's. Any tool that publishes, replies, deletes
or costs money answers *"Nothing has been done"* and describes the consequence
until it is called again with `confirm: true`. Nothing is sent on the first
call.

**Approval** is yours. For the actions listed under
[Agents](https://boltclaw.ai/docs/api/agents), the API answers `428 APPROVAL_REQUIRED` with a link
to [an approval page](https://boltclaw.ai/dashboard/approvals) and **nothing
happens**. You decide there; the assistant then retries the identical request
with the approval id. An approval is bound to that exact request and the object
it acts on, works once, and lapses after 24 hours.

Paying a partner, adjusting a commission, approving a referral partner and
disconnecting a social account **always** ask, whatever your settings say. The
rest can be waived by your organisation's approvals switch, or trusted for a few
hours at a time.

## Tools

| Tool | Does | Scope | |
|---|---|---|---|
| `verify_api_key` | Check a key | none |  |
| `get_workspace` | Read the key's workspace | none |  |
| `list_pages` | List pages | `pages:read` |  |
| `create_page` | Create a page | `pages:write` | **public**, asks first |
| `get_page` | Read a page | `pages:read` |  |
| `update_page` | Update a page | `pages:write` | **public**, asks first |
| `list_links` | List a page's links | `pages:read` |  |
| `add_link` | Add a link | `pages:write` | **public**, asks first |
| `page_stats` | Read a page's views and clicks | `pages:read` |  |
| `update_link` | Update a link | `pages:write` | **public**, asks first |
| `remove_link` | Remove a link | `pages:write` | **permanent**, asks first |
| `list_conversations` | List conversations | `inquiries:read` |  |
| `get_conversation_messages` | Read a conversation | `inquiries:read` |  |
| `reply_to_conversation` | Reply in a conversation | `inquiries:write` | asks first |
| `list_accounts` | List connected accounts | `social:read` |  |
| `list_posts` | List posts | `social:read` |  |
| `create_post` | Create a post | `social:write` | **costs money**, **public**, asks first |
| `get_post` | Read a post | `social:read` |  |
| `cancel_post` | Cancel a scheduled post | `social:write` |  |
| `list_inbox` | List the inbox | `social:read` |  |
| `get_inbox_thread` | Read an inbox thread | `social:read` |  |
| `set_inbox_status` | Set an item's status | `social:write` |  |
| `reply_to_inbox_item` | Reply to an item | `social:write` | **costs money**, **public**, asks first |
| `list_automations` | List automations | `social:read` |  |
| `create_automation` | Create an automation | `social:write` | **costs money**, **public**, asks first |
| `update_automation` | Update an automation | `social:write` | **costs money**, **public**, asks first |
| `list_leads` | List leads | `leads:read` |  |
| `get_usage` | Read plan usage | `social:read` |  |
| `record_referral_conversion` | Report a conversion | `conversions:write` |  |
| `list_referral_programs` | List programs | `referrals:read` |  |
| `list_referral_partners` | List a program's partners | `referrals:read` |  |
| `approve_referral_partner` | Approve a partner | `referrals:write` | asks first |
| `reject_referral_partner` | Reject a partner | `referrals:write` |  |
| `list_referral_commissions` | List a program's commissions | `referrals:read` |  |
| `referral_program_stats` | Read a program's stats | `referrals:read` |  |
| `list_workspaces` | List the workspaces this connection can work on and which is the default. Every other tool takes an optional workspace to pick one. | none | |
| `upload_media` | Upload an image or video and make it ready to put on a post, in one call. | `social:write` | |
| `get_api_docs` | Read the API reference offline. The one tool that needs no key. | none | |
| `wait_for_approval` | Wait for a person to approve or deny an action that needs approval; returns as soon as they decide. Never approves anything itself. | none | |
| `search_boltclaw_actions` | Find the operation for anything beyond the everyday tools, with its input schema and whether it needs approval, costs money or deletes something. | none | |
| `read_boltclaw_action` | Run one READ operation found with search_boltclaw_actions. Changes nothing. | per action | |
| `run_boltclaw_action` | Run one operation that CHANGES something, found with search_boltclaw_actions, validated against its schema, with the same confirmation and approval steps as every other tool. | per action | |

Everything else is an **action**: find it with `search_boltclaw_actions`, then run it with
`read_boltclaw_action` (a read) or `run_boltclaw_action` (a change). The catalog today:

| Operation | Area | Runner | |
|---|---|---|---|
| `deletePage` | pages | `run_boltclaw_action` | **permanent**, asks first |
| `updateInquiry` | conversations | `run_boltclaw_action` |  |
| `setInquiryClosed` | conversations | `run_boltclaw_action` |  |
| `markInquiryRead` | conversations | `run_boltclaw_action` |  |
| `updatePost` | posts | `run_boltclaw_action` | **costs money**, **public**, asks first |
| `deletePost` | posts | `run_boltclaw_action` | **permanent**, asks first |
| `hideInboxItem` | inbox | `run_boltclaw_action` | asks first |
| `deleteAutomation` | automations | `run_boltclaw_action` | **permanent**, asks first |
| `deleteLead` | leads | `run_boltclaw_action` | **permanent**, asks first |
| `createReferralProgram` | referrals | `run_boltclaw_action` | **public**, asks first |
| `getReferralProgram` | referrals | `read_boltclaw_action` |  |
| `updateReferralProgram` | referrals | `run_boltclaw_action` | **public**, asks first |
| `adjustReferralCommission` | referrals | `run_boltclaw_action` | asks first |
| `listReferralPayouts` | referrals | `read_boltclaw_action` |  |
| `markReferralPayoutPaid` | referrals | `run_boltclaw_action` | asks first |
| `listReferralPayoutProviders` | referrals | `read_boltclaw_action` |  |
| `testReferralPayoutProvider` | referrals | `run_boltclaw_action` |  |
| `getReferralPayoutSettings` | referrals | `read_boltclaw_action` |  |
| `updateReferralPayoutSettings` | referrals | `run_boltclaw_action` | asks first |
| `getReferralPayoutPreview` | referrals | `read_boltclaw_action` |  |
| `createReferralPayoutBatch` | referrals | `run_boltclaw_action` |  |
| `getReferralPayoutBatch` | referrals | `read_boltclaw_action` |  |
| `sendReferralPayoutBatch` | referrals | `run_boltclaw_action` | asks first |
| `cancelReferralPayoutAutoSend` | referrals | `run_boltclaw_action` |  |
| `getReferralPayout` | referrals | `read_boltclaw_action` |  |
| `getReferralPayoutDetails` | referrals | `read_boltclaw_action` |  |
| `reportReferralPayoutResult` | referrals | `run_boltclaw_action` |  |
| `getReferralTaxSettings` | referrals | `read_boltclaw_action` |  |
| `updateReferralTaxSettings` | referrals | `run_boltclaw_action` | asks first |
| `listReferralTaxForms` | referrals | `read_boltclaw_action` |  |
| `forfeitReferralCommissions` | referrals | `run_boltclaw_action` | asks first |
| `getReferralTaxYear` | referrals | `read_boltclaw_action` |  |
| `listReferralPayoutInvoices` | referrals | `read_boltclaw_action` |  |
| `createReferralInvoiceLink` | referrals | `run_boltclaw_action` |  |
| `createReferralStatementLink` | referrals | `run_boltclaw_action` |  |
| `issueReferralInvoice` | referrals | `run_boltclaw_action` |  |
| `reissueReferralInvoice` | referrals | `run_boltclaw_action` |  |
| `getReferralBrand` | referrals | `read_boltclaw_action` |  |
| `updateReferralBrand` | referrals | `run_boltclaw_action` | asks first |
| `createReferralBrandUpload` | referrals | `run_boltclaw_action` |  |
| `startReferralBrandEmailVerification` | referrals | `run_boltclaw_action` |  |
| `confirmReferralBrandEmailVerification` | referrals | `run_boltclaw_action` |  |
| `listReferralDomains` | referrals | `read_boltclaw_action` |  |
| `addReferralDomain` | referrals | `run_boltclaw_action` | asks first |
| `getReferralDomain` | referrals | `read_boltclaw_action` |  |
| `removeReferralDomain` | referrals | `run_boltclaw_action` | **permanent**, asks first |
| `checkReferralDomain` | referrals | `run_boltclaw_action` |  |
| `getReferralListing` | referrals | `read_boltclaw_action` |  |
| `updateReferralListing` | referrals | `run_boltclaw_action` | asks first |
| `createReferralListingLogoUpload` | referrals | `run_boltclaw_action` |  |
| `listReferralBroadcasts` | referrals | `read_boltclaw_action` |  |
| `createReferralBroadcast` | referrals | `run_boltclaw_action` |  |
| `getReferralBroadcast` | referrals | `read_boltclaw_action` |  |
| `updateReferralBroadcast` | referrals | `run_boltclaw_action` |  |
| `testReferralBroadcast` | referrals | `run_boltclaw_action` |  |
| `sendReferralBroadcast` | referrals | `run_boltclaw_action` | asks first |
| `listReferralBroadcastReferrers` | referrals | `read_boltclaw_action` |  |
| `previewReferralImport` | referrals | `run_boltclaw_action` |  |
| `listReferralImports` | referrals | `read_boltclaw_action` |  |
| `commitReferralImport` | referrals | `run_boltclaw_action` | asks first |
| `listReferralImportInvites` | referrals | `read_boltclaw_action` |  |
| `listReferralLibrary` | referrals | `read_boltclaw_action` |  |
| `createReferralLibraryItem` | referrals | `run_boltclaw_action` |  |
| `updateReferralLibraryItem` | referrals | `run_boltclaw_action` |  |
| `deleteReferralLibraryItem` | referrals | `run_boltclaw_action` | **permanent**, asks first |
| `createReferralLibraryUpload` | referrals | `run_boltclaw_action` |  |
| `listReferralLinkHosts` | referrals | `read_boltclaw_action` |  |
| `checkReferralLinkHost` | referrals | `run_boltclaw_action` |  |
| `getReferralLeaderboard` | referrals | `read_boltclaw_action` |  |
| `listReferralContests` | referrals | `read_boltclaw_action` |  |
| `createReferralContest` | referrals | `run_boltclaw_action` |  |
| `getReferralContest` | referrals | `read_boltclaw_action` |  |
| `updateReferralContest` | referrals | `run_boltclaw_action` |  |
| `cancelReferralContest` | referrals | `run_boltclaw_action` | asks first |
| `awardReferralContest` | referrals | `run_boltclaw_action` | asks first |
| `listReferralEntries` | referrals | `read_boltclaw_action` |  |
| `upsertReferralEntry` | referrals | `run_boltclaw_action` |  |
| `getReferralEntry` | referrals | `read_boltclaw_action` |  |
| `updateReferralEntry` | referrals | `run_boltclaw_action` |  |
| `disqualifyReferralEntry` | referrals | `run_boltclaw_action` | asks first |
| `requalifyReferralEntry` | referrals | `run_boltclaw_action` |  |
| `inviteReferralEntries` | referrals | `run_boltclaw_action` | asks first |
| `getReferralSecondTier` | referrals | `read_boltclaw_action` |  |
| `updateReferralSecondTier` | referrals | `run_boltclaw_action` | asks first |
| `endReferralWaitlist` | referrals | `run_boltclaw_action` | asks first |
| `forgetReferralWaitlist` | referrals | `run_boltclaw_action` | asks first |
| `rotateReferralWaitlistPage` | referrals | `run_boltclaw_action` | asks first |
| `listReferralCodes` | referrals | `read_boltclaw_action` |  |
| `listReferralInvites` | referrals | `read_boltclaw_action` |  |
| `createReferralInvite` | referrals | `run_boltclaw_action` |  |
| `syncReferralShopifyCodes` | referrals | `run_boltclaw_action` | asks first |
| `listReferralPrivacyRequests` | referrals | `read_boltclaw_action` |  |
| `getReferralPrivacyRequest` | referrals | `read_boltclaw_action` |  |
| `answerReferralPrivacyRequest` | referrals | `run_boltclaw_action` |  |
| `getReferralDataSubject` | referrals | `read_boltclaw_action` |  |
| `eraseReferralDataSubject` | referrals | `run_boltclaw_action` | **permanent**, asks first |
| `draftReferralProgramTerms` | referrals | `run_boltclaw_action` |  |
| `exportReferralReport` | referrals | `read_boltclaw_action` |  |
| `pauseReferralProgram` | referrals | `run_boltclaw_action` |  |
| `resumeReferralProgram` | referrals | `run_boltclaw_action` | asks first |
| `archiveReferralProgram` | referrals | `run_boltclaw_action` | asks first |
| `rotateReferralSignupLink` | referrals | `run_boltclaw_action` | asks first |
| `banReferralPartner` | referrals | `run_boltclaw_action` | asks first |
| `unbanReferralPartner` | referrals | `run_boltclaw_action` | asks first |
| `createReferralCode` | referrals | `run_boltclaw_action` | asks first |
| `updateReferralCode` | referrals | `run_boltclaw_action` | asks first |
| `deactivateReferralCode` | referrals | `run_boltclaw_action` |  |
| `listReferralLinks` | referrals | `read_boltclaw_action` |  |
| `archiveReferralLink` | referrals | `run_boltclaw_action` | asks first |
| `revokeReferralInvite` | referrals | `run_boltclaw_action` |  |
| `approveReferralCommission` | referrals | `run_boltclaw_action` | asks first |
| `cancelReferralPayout` | referrals | `run_boltclaw_action` | asks first |
| `recalculateReferralLevels` | referrals | `run_boltclaw_action` |  |
| `listReferralRewards` | referrals | `read_boltclaw_action` |  |
| `createReferralReward` | referrals | `run_boltclaw_action` |  |
| `updateReferralReward` | referrals | `run_boltclaw_action` |  |
| `deleteReferralReward` | referrals | `run_boltclaw_action` | **permanent**, asks first |
| `listReferralGroups` | referrals | `read_boltclaw_action` |  |
| `createReferralGroup` | referrals | `run_boltclaw_action` |  |
| `updateReferralGroup` | referrals | `run_boltclaw_action` |  |
| `deleteReferralGroup` | referrals | `run_boltclaw_action` | **permanent**, asks first |
| `updateReferralPartner` | referrals | `run_boltclaw_action` |  |
| `createReferralBonus` | referrals | `run_boltclaw_action` | asks first |
| `createReferralEmbedToken` | referrals | `run_boltclaw_action` |  |
| `listReferralReferrers` | referrals | `read_boltclaw_action` |  |
| `upsertReferralReferrer` | referrals | `run_boltclaw_action` |  |
| `getReferralReferrer` | referrals | `read_boltclaw_action` |  |
| `updateReferralReferrer` | referrals | `run_boltclaw_action` | asks first |
| `eraseReferralReferrer` | referrals | `run_boltclaw_action` | **permanent**, asks first |
| `revokeReferralEmbedSessions` | referrals | `run_boltclaw_action` |  |
| `rotateReferralEmbedKey` | referrals | `run_boltclaw_action` | asks first |
| `listReferralGrants` | referrals | `read_boltclaw_action` |  |
| `getReferralGrant` | referrals | `read_boltclaw_action` |  |
| `fulfilReferralGrant` | referrals | `run_boltclaw_action` | asks first |
| `failReferralGrant` | referrals | `run_boltclaw_action` | asks first |
| `sendReferralGrant` | referrals | `run_boltclaw_action` | asks first |
| `getReferralOffer` | referrals | `read_boltclaw_action` |  |
| `getReferralCustomerReferral` | referrals | `read_boltclaw_action` |  |
| `syncReferralStripeCodes` | referrals | `run_boltclaw_action` | asks first |
| `getReferralIntegrationStatus` | referrals | `read_boltclaw_action` |  |
| `checkReferralTag` | referrals | `run_boltclaw_action` |  |
| `sendReferralTestSale` | referrals | `run_boltclaw_action` |  |
| `clearReferralTestData` | referrals | `run_boltclaw_action` | **permanent**, asks first |
| `recordReferralClick` | referrals | `run_boltclaw_action` |  |
| `listReferralFlags` | referrals | `read_boltclaw_action` |  |
| `getReferralFlag` | referrals | `read_boltclaw_action` |  |
| `dismissReferralFlag` | referrals | `run_boltclaw_action` | asks first |
| `confirmReferralFlag` | referrals | `run_boltclaw_action` | asks first |
| `dismissReferralFlags` | referrals | `run_boltclaw_action` | asks first |
| `confirmReferralFlags` | referrals | `run_boltclaw_action` | asks first |
| `holdReferralPartnerPayouts` | referrals | `run_boltclaw_action` |  |
| `getReferralRiskPolicy` | referrals | `read_boltclaw_action` |  |
| `updateReferralRiskPolicy` | referrals | `run_boltclaw_action` | asks first |
| `listAgentCalls` | logs | `read_boltclaw_action` |  |
| `listAuditLog` | logs | `read_boltclaw_action` |  |

Referral amounts are integers in minor units, in tools as in the API.
`record_referral_conversion` takes the same fields as
[`POST /v1/referrals/conversions`](https://boltclaw.ai/docs/api/referrals#post-v1referralsconversions), and its
`event_id` is the same idempotency key: an assistant that retries sends the
**same** `event_id` again (a repeat answers `duplicate: true` and changes
nothing), and a `409 CONFLICT` means "send the same request again" — never a
new id. A conversion recorded through MCP is filed exactly as one sent to the
API directly, so the two share one set of `event_id`s.

A tool call the API refuses comes back as a tool error carrying the API's
`error` and `code` and what to do about it; a `429` says how many seconds to
wait.

## Resources and prompts

Two resources, both generated from this same specification and both readable
with no key: `boltclaw://api-reference` (every endpoint, scope and rule) and
`boltclaw://error-codes` (every code and what to change). The `get_api_docs`
tool serves the same text for clients that do not read resources.

Three prompts, each a plan the assistant carries out through the ordinary tools:
`schedule-post`, `set-up-page` and `reply-to-inbox`.

## Setting it up

**Claude Code**

```bash
claude mcp add --transport http boltclaw https://mcp.boltclaw.ai/mcp
```

Then run `/mcp` and sign in when it asks.

**Claude, ChatGPT and other web assistants** — add a custom connector with the
URL `https://mcp.boltclaw.ai/mcp`. They will open the sign-in for you.

**Cursor** (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "boltclaw": { "url": "https://mcp.boltclaw.ai/mcp" }
  }
}
```

**VS Code** (`.vscode/mcp.json`)

```json
{
  "servers": {
    "boltclaw": { "type": "http", "url": "https://mcp.boltclaw.ai/mcp" }
  }
}
```

### With an API key instead

Any client that lets you set a header can send a key, with no sign-in:

```bash
claude mcp add --transport http boltclaw https://mcp.boltclaw.ai/mcp \
  --header "Authorization: Bearer bc_live_..."
```

The config file then holds a credential, so keep it out of a repository. A key
used this way is its one workspace, and `workspace` is not accepted.

**Give the assistant a key made for it**, with the scopes you want it to have —
and leave out `leads:read` unless it genuinely needs other people's contact
details. Signing in is better: a key you paste has no connection behind it, so
`Settings → AI agents` cannot show it to you or end it.

<!-- https://boltclaw.ai/docs/mcp as markdown. Generated from openapi.yaml; API version 1.22.0. -->
<!-- Every /docs page answers as markdown: add .md to its path, or send Accept: text/markdown. -->