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 limited to the BTX projects you approve.

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 one or more projects 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 projects. The token is limited to the BTX MCP endpoint and the client that started the connection. BTX checks the live project allowlist on every request.

  4. 04

    Verify the tools

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

To change an existing connection after you create another workspace, open MCP connections, select the projects, and save. The change applies without recreating the connection.

03

What agents can do

BTX tools never hard-delete threads, 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 projects can this connection access?
  • Find the customer named Ada in the Mithril Wearables project.

  • Show Ada's recent support threads 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 thread and link it back to the thread.

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

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

For device history, use get_device_activity with project_id and either days (1, 7, or 30) or both start_date and end_date as inclusive UTC dates. Custom ranges support up to 90 days ending today or earlier. To query one previous day, use that date for both bounds. Set selected_date within the range to retrieve its firmware distribution; otherwise, the last day is selected. The result includes daily device counts, firmware counts and shares, and the first recorded observation date. Dates before that coverage are unavailable, rather than zero activity.

Use get_device_directory to discover workspace device labels and shared saved views. Both list_devices and get_device_activity accept filters or view_id, plus temporary search. Device lists also accept sort_by and sort_direction. Saved views supply filters and default ranges; explicit dates override the saved range. Historical labels reflect current assignments; firmware and model values come from the selected day's observations.

With write access and a workspace owner or administrator role, manage_device_label creates, renames, archives, or assigns labels to up to 200 devices. manage_device_view saves or archives shared views. Use stable client_request_id values for creates and the returned expected_revision for edits or archives.

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.