Skip to content
Setup

Connect to BTX with MCP

Connect ChatGPT, Codex, Claude, Cursor, or any compatible client to read BTX project data.

Before you start

BTX MCP is a private beta. It is live at the URL below and exposes project-scoped customer operations through standard OAuth 2.1.

BTX MCP server
https://btx.so/mcp

Add the URL to your client, sign in to BTX, and approve access. You do not need an API key, client secret, or BTX-issued client ID. Each connection is scoped to one BTX project.

01

Choose your agent

Choose ChatGPT / Codex, Claude, Cursor, or Manual below. Cursor supports a one-click install; the other tabs use the fastest setup their client supports.

ChatGPT

Open ChatGPT Plugins, create an MCP app, and enter the BTX server URL. ChatGPT will open BTX sign-in and consent. Availability depends on your ChatGPT plan and workspace permissions.

Open ChatGPT Plugins

Codex CLI and IDE

Add the hosted BTX server, then complete browser sign-in.

Codex
codex mcp add btx --url https://btx.so/mcp
codex mcp login btx

Run codex mcp list to verify the connection. The CLI and IDE extension share MCP configuration. See the Codex MCP guide for client configuration details.

02

Approve the connection

  1. 01

    Start the agent's sign-in flow

    The agent discovers BTX OAuth from the MCP endpoint and opens your browser.

  2. 02

    Sign in to BTX

    Use your normal BTX account, then choose the project for this connection. The selector includes only projects where that user is a direct member.

  3. 03

    Review consent

    Approve read and write access to the selected project. The token is limited to the BTX MCP endpoint, the client that started the connection, and that project.

  4. 04

    Verify the tools

    Ask the agent which BTX project it can access. It should return only the project you selected.

To connect Codex, Claude, or another client to more than one BTX project, add a separate named connection for each project, such as btx-mithril and btx-nirva. Each connection has its own authorization and can be changed by signing in again and choosing another project.

03

What agents can do

Projects and customers

Identify the connected project, find customers, and retrieve bounded customer profiles.

Conversations

Find conversations, inspect full customer context, assign owners, update state, add internal comments, draft replies, and send confirmed replies.

Issues

Search, create, and update BTX issues; manage assignees, labels, and links; and search, link, or create confirmed GitHub issues.

Knowledge

Search and manage policies, playbooks, and internal articles with revision history. Manage Help Center structure, drafts, publishing, and assets.

Customer and product context

Find customers, inspect devices, and explore bounded telemetry sessions and events without exposing a generic database query.

BTX tools never hard-delete conversations, issues, or knowledge. Mutations use current versions or stable idempotency keys where the underlying workflow supports them. The agent must show the exact content and get your confirmation before sending a customer reply, publishing Help Center content, or creating a GitHub issue.

04

Try the connection

After the client reports that BTX is connected, try prompts like:

  • Which BTX project can this connection access?

  • Find the customer named Ada in the Mithril Wearables project.

  • Show Ada's recent support conversations and summarize the open questions.

  • Draft a reply to Ada using the relevant policy, but do not send it.

  • Create a high-priority BTX issue from this conversation and link it back to the conversation.

  • Find the return policy, show its latest revision, and propose an update for review.

Tool results are bounded and redacted. BTX checks the selected project grant and current membership on every MCP request, records metadata-only audit events, and applies per-user, per-project, and per-client rate limits.

05

Disconnect

Remove or sign out of the BTX server in your agent. You can revoke its BTX OAuth grant to invalidate the server-side connection.