Skip to main content
Contact Button publishes three Streamable HTTP MCP endpoints with deliberately different trust boundaries: 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. 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 Workspace MCP exposes tools for listing workspaces/pages/buttons/forms/apps, creating pages/buttons/forms, reading manifests, and searching published knowledge. It also exposes published profiles as contactbutton://pages/{page_id}/manifest resources. Write tools are annotated as mutating and accept stable public IDs. Hosts should show users the tool invocation before execution.

​
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.

​
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

The smallest useful production 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.