T3Code MCP bridge

A self-hosted MCP server for working with T3Code from an MCP client, including voice conversations. Find threads, read updates, answer questions, review approvals, start or stop coding turns, and settle or archive threads through Streamable HTTP.

This is an independent project and is not affiliated with the authors of T3Code.

Requirements

• Node.js 24 or newer.

• A reachable T3Code orchestration API and a credential with orchestration:read and orchestration:operate scopes.

• A Cloudflare Access application for your MCP hostname, restricted to one email address.

• A tunnel or reverse proxy connecting that hostname to the bridge.

The bridge exposes every project visible to its T3Code credential. It has no separate project allowlist or multi-user isolation. New threads default to full-access; choose runtime_mode: "approval-required" to review requested actions.

Related MCP server: t3code-mcp

Get started

npm ci
cp .env.example .env

Edit .env with your T3Code address, a token path outside the checkout, and Cloudflare Access settings. See the configuration reference for each variable.

If an authorized t3 CLI is available, obtain a scoped credential:

node --env-file=.env scripts/refresh-token.mjs

The script writes the token with mode 0600. Set T3_BINARY if the CLI is outside PATH. You can also provision the scoped token yourself at T3_TOKEN_FILE.

Start the bridge:

node --env-file=.env src/index.mjs

When configuration is already exported in the environment, use npm start and npm run refresh-token instead. These commands do not automatically load .env.

Route your MCP hostname through Cloudflare Access to the bridge, then add https://your-mcp-hostname.example/mcp in your MCP client. Follow the deployment guide for Access setup, systemd services, and connection checks.

Tools

The bridge exposes 18 tools.

start_thread defaults to full-access, including the advertised input-schema default. Explicit runtime-mode overrides remain available.

stop_thread uses exact project, thread, and run IDs from get_thread. It works with pending input or approval, holds queued work when interrupting an active run, and distinguishes a cancellation request from observed stopped state. Retry using the same IDs. Check thread_stopped and verification before reporting that work stopped.

Settled, completed and archived are separate states. A completed run (turn_state, activity_status) is not Settled. settled is T3Code's done marker. archived hides a thread from the lists and can be undone. The four lifecycle tools take exact project_id and thread_id values. Before sending anything, they refuse running, blocked, queued, archived-for-settle and subagent threads. A repeated call on a thread already in that state is a no-op, and each call reports the state read back from T3Code. Settling and archiving stop idle background work only with stop_background_work: true. Settling cancels unanswered asynchronous questions only with cancel_pending_input: true. Use find_thread with include_archived to locate an archived thread.

See the tool guide for cancellation and lifecycle parameters and outcomes, runtime modes, approval decisions, cursors, and model selection limits.

Project layout

src/
  index.mjs          Application startup
  config.mjs         Environment configuration
  errors.mjs         Errors safe to return to MCP clients
  auth/              Cloudflare Access verification
  http/              HTTP routing and MCP transport lifecycle
  mcp/               Tool schemas, descriptions, and registration
  t3/                T3Code client, RPC, and response interpretation
tests/
  unit/              Client behavior, configuration, and parsing tests
  integration/       MCP calls over a local HTTP server
  helpers/           Shared test fixtures
scripts/             Credential maintenance
deploy/systemd/      Example service and timer units
docs/                Configuration, deployment, tools, and architecture

Development

npm test
npm run test:unit
npm run test:integration
npm run test:coverage

Tests use temporary credentials and simulated T3Code responses. They do not require a running T3Code server or Cloudflare account. GitHub Actions runs the suite on Node.js 24.

Read CONTRIBUTING.md and the architecture guide before changing the bridge.

License

MIT. See LICENSE.