Skip to main content
Contact Button publishes four customer-facing Streamable HTTP MCP endpoints: Start with the Documentation MCP when the task is to understand Contact Button. Connect the Workspace MCP only when the represented human wants the agent to inspect or change their account. Check the MCP manifest before connecting. It advertises the servers and their authentication and read-only boundaries. The Workspace MCP’s enabled field is the machine-readable availability signal. A disabled Workspace MCP returns a structured API error and should not be retried until the environment enables it. Authenticate to the Workspace MCP with a scoped bearer key or an OAuth access token. The preferred protocol revision is 2025-11-25; compatibility negotiation also accepts 2025-06-18 and 2025-03-26. Send the negotiated MCP-Protocol-Version header after initialization. Existing clients configured with https://app.contactbutton.com/mcp remain supported. Use the API-domain endpoint for new connections. When AGENT_OAUTH_ENABLED is enabled, interactive clients discover OAuth through /.well-known/oauth-protected-resource and /.well-known/oauth-authorization-server. Workspace owners register clients in API Keys, select workspaces and scopes, and complete Authorization Code + S256 PKCE. Dynamic client registration is disabled. Access tokens are short-lived, audience-bound to the Workspace MCP, and rechecked against active workspace grants on every request. Public page mutation tools create proposals only. They return a ContactButton review_url; the MCP client cannot approve itself and never receives the visitor’s OTP. Poll get_action_status, or use cancel_action for an MCP-originated proposal. When the page owner enables MCP access and assigns a published Agent, the public server also exposes ask_contactbutton_agent. This is a read-only, one-question answer path. ContactButton applies the Agent’s profile, ordered conversation rules, and approved knowledge on the server with mutation tools disabled. The response includes citations and redacted policy metadata; owner rule text is never returned to the MCP client or copied into public knowledge. The answer also includes the versioned Agent protocol contract. Its state vocabulary matches hosted web, REST, and A2A. Authenticated workspace REST clients can inspect the complete control manifest with content:read; public MCP deliberately receives only redacted diagnostics and observable outcomes.
The Mintlify admin connector is an internal documentation-authoring integration. It can edit the documentation project and open pull requests, so only trusted Contact Button team members should connect it. It is not either of the public endpoints above.

Why there is not one process per button

A button, page, or form is a logical resource—not a separately deployed server. The shared MCP gateway authenticates once, lists only accessible workspaces, and routes every tool call by workspace and resource UUID. This avoids thousands of idle servers, centralizes fixes and rate limits, and preserves a single authorization boundary. Each public profile can still feel like its own agent: it has a unique manifest, Agent Card, A2A tenant identifier, actions, and knowledge resources.

Workspace capabilities

The current Workspace server exposes 33 tools. Use tools/list after initialization for the exact schemas; follow nextCursor until all pages have been read. All tools except contactbutton_list_workspaces take workspace_id. Commerce tools require COMMERCE_ENABLED and return tenant-scoped reports, without paid delivery resources or private post bodies. See Products, support, and memberships for filters, privacy, and builder setup. API keys also need workspaces:read to enter the server. OAuth clients need mcp:use, an active audience-bound workspace grant, and the operation’s ability. Inbox tools require MULTICHANNEL_INBOX_ENABLED; follow-ups and bookings additionally require their own feature and access checks. Read manifests through contactbutton_get_page_manifest. The current SDK server exposes tools, not the older contactbutton://pages/{page_id}/manifest resources. Inspect the initialize response instead of assuming resource or prompt support. Show the operator a write invocation before execution. Setup and Inbox writes use a UUID request_id plus values; repeat both unchanged to retrieve the creation receipt. Original creation tools keep their earlier schemas and do not accept the new receipt contract. Inbox writes act as the authenticated operator. contactbutton_create_inbox_booking immediately creates a confirmed booking after checking live availability and queues calendar sync. It does not use the public visitor OTP lifecycle. contactbutton_update_inbox_thread can star, close, reopen, snooze, hide, or restore a thread; hiding does not erase messages.

Public Page tools

Every eligible public Page server exposes contactbutton_get_profile, list_capabilities, get_action_status, and cancel_action. Available capabilities add search_knowledge, list_booking_services, find_booking_availability, propose_booking, propose_callback, propose_form_submission, and propose_subscription. A suitable assigned Agent can add ask_contactbutton_agent. The URL selects the Page. Read list_capabilities and the returned tool schemas before proposing an action. Proposal tools require idempotency_key and return a visitor review_url; only an MCP-originated proposal can be cancelled through this server.

Direct Agent questions

Open Edit Agent → Integrations and enable public questions. Copy that Agent’s endpoint; no public Page assignment is required. The Agent must be active and published, its model connection must be tested and belong to the workspace, and the workspace must be active. Hosted Telnyx AI Assistants are unavailable on this channel. The endpoint exposes only ask_contactbutton_agent with one required string, question (up to 10,000 characters). Each call creates an isolated, closed conversation and returns an answer as MCP text. Include all relevant context on each call. There is no conversation token or multi-turn session, no transactional tool execution, and no delivery automation. The workspace stores the question and answer in Agent history; avoid submitting secrets. This endpoint differs from the Page’s structured ask_contactbutton_agent result: it does not return the Page protocol contract, action proposals, or a visitor-review lifecycle. Disabling public questions or pausing the Agent removes access. The private /mcp/assistant endpoint uses server-issued dashboard delegation credentials and a separate feature gate. Customer API keys and public clients should use one of the endpoints above.

Connect Codex

Create a key at API keys with workspaces:read and content:read. Add content:write only when the agent should create or change content. Store the key in your shell or secret manager, not in config.toml:
Add the server to ~/.codex/config.toml, or to .codex/config.toml in a trusted project:
Restart Codex, then open /mcp and confirm that the Contact Button tools are available. See the official OpenAI MCP configuration reference for client settings.

Connect Claude Code

Set CONTACTBUTTON_TOKEN in the environment and add a project .mcp.json:
Restart Claude Code and use /mcp to verify the connection. Keep .mcp.json free of literal keys so it is safe to share with a team.

Verify the connection

Use a test workspace in the target environment. The smallest useful connection check is:
  1. initialize negotiates protocol version 2025-11-25.
  2. tools/list returns contactbutton_list_workspaces.
  3. tools/call for contactbutton_list_workspaces returns only workspaces accessible to the key owner.
  4. A content tool returns a scope error unless the key also has content:read or content:write.
  5. Revoking the key in the dashboard immediately makes subsequent requests return 401.

Official MCP Registry

The Workspace MCP manifest is maintained in server.json under the domain-owned name com.contactbutton/contact-button. The manifest advertises the Streamable HTTP endpoint and prompts clients for a secret Authorization header. Enter the header value as Bearer YOUR_CONTACT_BUTTON_API_KEY; never place a real key in server.json. Publishing requires proof that the publisher controls contactbutton.com:
  1. Install the official publisher with brew install mcp-publisher.
  2. Generate an Ed25519 publishing key outside the repository.
  3. Add the generated v=MCPv1; k=ed25519; p=... TXT value to contactbutton.com.
  4. Authenticate with mcp-publisher login dns --domain contactbutton.com.
  5. Validate and publish the checked-in server.json with mcp-publisher publish.
  6. Verify the listing through the registry API by searching for com.contactbutton/contact-button.
The registry is currently a preview service. Published versions are immutable, so increment the manifest version before publishing any later metadata change.
The server validates browser Origin headers against MCP_ALLOWED_ORIGINS. Configure the exact trusted dashboard and MCP host origins; do not use * in production.

Catalog-aware draft setup

Read contactbutton_get_setup_catalog for current button, form, listing and popup starters, supported widget inputs, and Toolbox coverage. Catalog visibility does not mean that every product has an automated write tool. The authenticated workspace MCP additionally provides:
  • contactbutton_create_onboarding
  • contactbutton_create_button_draft
  • contactbutton_create_form_draft
  • contactbutton_create_widget (form, link, WhatsApp chat, and list)
  • contactbutton_create_list and contactbutton_list_lists
  • contactbutton_create_button_template
The setup write tools take workspace_id, a unique UUID request_id, and values matching the setup catalog. Reuse the same request ID and values when retrying: the resource and receipt commit together. Write scope and workspace access are required. Buttons/widgets remain disabled; forms/listings are created unattached. These draft creation tools do not publish or send messages. Onboarding completion can create its configured resources; inspect the catalog and returned state first. Existing create_button and create_form tools retain their original schemas for compatibility. The dashboard Assistant exposes corresponding proposal tools. A proposal is not a creation receipt: the user must approve its card before the server creates the resource. For dependent resources, approve the form/list first, then use its returned public ID to configure the widget, and finally attach it to a disabled button.