T3 Code thread MCP
This MCP server globally manages persistent T3 threads across projects and computers, without requiring a parent thread ID, by connecting to T3 desktop or direct server environments.
Environment & project discovery:
list_environments,list_projects, andcreate_projectlet agents find or create projects on configured computers.Thread creation:
create_threadcreates an empty persistent thread in a project with optional model selection and command ID.Thread listing & reading:
list_threadsandread_threadexpose active conversation history with pagination and truncation limits.Messaging & workflow:
send_message_to_threadsends follow-ups, starts or queues work, revives settled threads, and can include reply routing.Waiting on threads:
wait_threadswaits for up to eight threads to finish or need attention, using cursors to avoid repeated results.Lifecycle control:
set_thread_settled,interrupt_thread,set_thread_archived,delete_thread,set_thread_title,set_thread_pinned, andset_thread_snoozedmanage thread state.Approval and user input handling:
respond_to_approval,respond_to_user_input, anddismiss_user_inputmanage explicit pending requests.Provider/model awareness:
list_providersreads installed providers, authentication status, and model catalog; tools accept model selections.Multi-environment routing: Supports desktop discovery or direct connections, with per-environment IDs and optional source thread references for replies.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@T3 Code thread MCP create a thread titled "Auth refactor" and ask it to fix the failing login tests"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
T3 Code thread MCP
Manage persistent T3 threads across projects and computers from one globally installed MCP server. No parent thread ID is required. Each computer needs a running T3 server and an authorized connection. Threads remain visible in T3's desktop, web, and mobile clients.
Install globally
Requires Node 22 or later. Desktop discovery requires the companion T3 desktop build linked below. Direct connections were tested with released T3 0.0.40 and 0.0.42.
npm install -g https://github.com/samdickson22/t3code-thread-mcp/releases/download/v0.3.0/t3code-thread-mcp-0.3.0.tgz
t3code-thread-mcp --helpThis package is distributed through GitHub releases; it is not currently published to the npm registry. You can also clone this repository, run npm ci, and launch node src/cli.js.
Related MCP server: t3code-mcp
Connect computers
Reuse the T3 desktop connection manager
On macOS or Linux, with a T3 desktop build that supports the connection bridge, run:
t3code-thread-mcpRegister that command with your MCP host. It uses the running desktop app's computer list and authenticated connections, including T3 Connect and SSH. Add or remove computers in T3's Settings → Connections; the MCP refreshes that list on each call. No parent ID, server URL, or access token is required.
Desktop discovery is the default when no direct connection is configured. It requires the companion T3 desktop change. Windows desktop mode is disabled until its named-pipe endpoint can be authenticated; use direct connection configuration on Windows. The MCP runs on the same computer as the desktop app. Agents on another computer need access to a bridge-enabled desktop there; this does not automatically install tools into remote provider sessions.
For a custom T3 home, use --desktop-state-dir /path/to/t3-home/userdata.
The app must remain open. Closing it rejects new operations; agent work already
accepted by a server may continue. Connection credentials stay inside T3. The
existing direct-connection and legacy scoped modes below are unchanged.
Configure direct connections
For one computer, supply T3_URL and T3_ACCESS_TOKEN to the MCP process through your host's environment or secret manager. Use HTTPS remotely; loopback HTTP is supported. Obtain the access token through T3's normal pairing/token-exchange flow. When it expires, refresh it and restart the MCP process.
For several computers, create ~/.config/t3code-thread-mcp/config.json:
{
"environments": [
{
"id": "desktop",
"label": "My desktop",
"url": "http://127.0.0.1:3773",
"tokenEnv": "T3_DESKTOP_TOKEN"
},
{
"id": "server",
"label": "Remote server",
"url": "https://your-t3-server.example",
"tokenEnv": "T3_SERVER_TOKEN"
}
]
}Use your actual server addresses and supply the named token variables to the MCP process. The file contains variable names, not secret values. Keep environment IDs consistent between agents that will reply to each other. This does not discover arbitrary computers or bypass T3 authentication. For T3 Connect, use a supported reachable server endpoint; a UI connection label is not an API URL.
Pass --config /absolute/path/config.json or set T3_MCP_CONFIG to use a different file. With multiple environments, calls select environmentId; an optional top-level defaultEnvironment supplies a default. A single configured environment is selected automatically. T3_URL takes precedence over the default file.
Upgrading from 0.1.x: remove T3_SOURCE_THREAD_ID from the MCP configuration to use global mode. An explicit source ID plus T3_URL retains legacy project scope, even when T3_MCP_CONFIG is inherited. An explicit --config selects the global configuration.
Register with your agents
Installing the executable and registering an MCP server are separate steps. Register once at user scope on each computer/provider home where agents should have these tools. Newly started T3 provider sessions can then load that registration. Existing sessions may need to restart.
Codex user configuration (~/.codex/config.toml):
[mcp_servers.t3_threads]
command = "/absolute/path/to/t3code-thread-mcp"Find the executable path with command -v t3code-thread-mcp. No arguments or token variables are needed for desktop discovery. For direct connections, add --config arguments and forward the required token variable names through env_vars.
Claude Code user registration:
claude mcp add --scope user t3_threads -- /absolute/path/to/t3code-thread-mcpFor direct connections, supply token variables in the environment that launches Claude/T3. If T3 uses a custom Codex or Claude home, register there. Alternatively, configure the MCP through T3's provider launch arguments. The live validation exercised both providers using per-environment launch settings.
For other MCP hosts, launch the same executable with stdio transport, optional --config arguments, and the required environment variables. The MCP does not print credentials or write logs to stdout.
Global tools
Tools | Behavior |
| Discover configured computer IDs. |
| Discover or create projects on a selected computer. Workspace paths belong to that computer. |
| Read the server's actual installed providers, authentication status, and model catalog. |
| Create a persistent thread in any project. Requires |
| List threads across projects with optional project filtering and pagination. |
| Read active conversation history and pending requests. Message text is capped at 8,000 characters with truncation indicated. Restore archived threads before reading their history. |
| Send or queue work and revive settled threads. Optional |
| Wait for up to eight threads across environments, using cursors to suppress repeated results. Unobserved/unavailable targets are reported separately. A zero wait allows one bounded network observation. |
| Interrupt work or stop its provider session while retaining conversation history. |
| Settle or reactivate threads. T3 rejects settlement while work or blocking requests remain. |
| Rename, pin/unpin, or snooze/unsnooze. Use |
| Archive/restore or permanently delete a thread. |
| Manage explicit pending requests by request ID. |
Start with list_environments, then list_projects and list_providers. For example:
{
"name": "create_thread",
"arguments": {
"environmentId": "server",
"projectId": "project-id-from-list-projects",
"title": "Investigate issue 123",
"commandId": "issue-123-create",
"modelSelection": {
"instanceId": "codex",
"model": "gpt-6-astra",
"options": [{ "id": "reasoningEffort", "value": "low" }]
}
}
}Send work using the returned thread ID and the same environment ID. Select a Claude model from that environment's provider catalog; the current Fable 5.1 canonical slug is claude-fable-5-1 with instance claudeAgent and option { "id": "effort", "value": "low" }.
Mutations accept an optional commandId. Persist it before dispatch and reuse it only for the identical operation and arguments. T3 stores receipts, including rejected commands. A receipt means accepted, not completed; use read/wait to inspect execution. Global retry identities include routing, operation, project/target, and optional source. Keep these stable across retries.
Legacy compatibility and parity limits
Setting T3_SOURCE_THREAD_ID retains the original seven project-scoped tools, schemas, defaults, sender attribution, and retry behavior. Agentdoc's existing scoped configuration continues to work. src/tools.json remains generated from the native T3 peer-tools PR; global mode adds routing and management tools beyond that PR's scoped contract.
This release does not claim full Codex app feature parity. T3's public API does not expose equivalent conversation forks or host-to-host session handoff. It also withholds archived message history until the thread is restored. The MCP reports that limitation instead of returning false empty history or silently unarchiving it. Creating a new thread does not copy history, clone a provider session, or create a worktree. Changing an existing thread's provider driver may be rejected by T3; threads owned by different providers can communicate across environments.
The HTTP and WebSocket routes are existing T3 application APIs, not a guaranteed stable third-party protocol. This integration is independent of Agentdoc or any task board.
Validation
npm test
npm run checkTests cover the real MCP stdio boundary, global installation/configuration, cross-project and cross-environment routing, legacy scope, retry identities, attention states, and unavailable hosts. Browser screenshots and real-provider evidence show Astra-low creating Fable-low on another environment, Fable replying through its own MCP tools, and settlement/archive/restoration/revival with retained context.
Available Tools
7 toolscreate_threadA
Create an empty persistent peer thread in this project, at its workspace root. Inherits this thread's model and permission mode unless modelSelection is supplied. Returns its ID; use send_message_to_thread to start work. Does not copy history or create a worktree.
Inputs: title (required), commandId, modelSelection.
interrupt_threadBDestructive
Request interruption of a peer thread's current turn in this project. History remains available for a follow-up.
Inputs: threadId (required), commandId.
list_threadsBRead-onlyIdempotent
List persistent peer threads in this project, including settled threads. Archived threads are excluded. Results sort by ID; pass nextBeforeThreadId to fetch the next page.
Inputs: limit, beforeThreadId.
read_threadARead-onlyIdempotent
Read a peer thread's state and a page of conversation messages in this project. Tool output and attachments are omitted; message text is capped at 8000 characters. Use the returned page.beforeCursor for older turns.
Inputs: threadId (required), turnLimit, beforeCursor.
send_message_to_threadA
Send a visible follow-up to a peer thread in this project, starting or queuing work and reviving settled threads. Includes your thread ID so the recipient can reply. Optional modelSelection changes the model. T3 can reject changing the provider of an already-bound thread.
Inputs: message (required), threadId (required), commandId, replyToSource, +1 more.
set_thread_settledADestructive
Settle or reactivate a peer thread in this project. Settling is rejected while work is running or queued, or blocking approvals are pending. Use interrupt_thread to stop a turn first.
Inputs: settled (required), threadId (required), commandId.
wait_threadsARead-onlyIdempotent
Wait for any peer thread to finish or need attention. Pass each last returned cursor to avoid repeated notifications. Returns current state on timeout; commentary does not wake this tool. Maximum wait is 60 seconds.
Inputs: targets (required), timeoutSeconds.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Each tool maps to a distinct action on the thread resource (create/list/read/send/wait/settle/interrupt). Descriptions clarify boundaries, e.g. create_thread vs send_message_to_thread and set_thread_settled vs interrupt_thread.
All tools use snake_case with a verb-first pattern and 'thread(s)' as the resource noun. send_message_to_thread is slightly longer but still follows the same convention.
7 tools is well-scoped for peer thread management; each tool covers a necessary operation without redundancy.
Core thread lifecycle (create, list, read, message, wait, settle, interrupt) is covered, but there is no explicit archive or delete operation despite archived threads being referenced. This is a minor gap that agents can work around if archiving is handled elsewhere.
Maintenance
Related MCP Connectors
Project management shared by people and AI agents, with persistent project state through MCP.
Team agent collaboration: shared team facts, human-confirmed writes, tasks and threads over MCP.
- aXDeprecatedio.github.ax-platform
Agent-native collaboration network: orchestrate a team of long-running agents from any MCP client.
Hosted MCP server and Agent Skills for specs, engineering threads, and project memory.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables MCP clients to spawn and control Codex CLI and Claude Code sessions on the host machine, with session management and filesystem access.4MIT
- FlicenseAqualityDmaintenanceMCP server for interacting with a running T3 Code instance. Enables viewing agent threads, sending messages, and approving permission requests from Claude Code or voice-controlled models.192-
- AlicenseNot gradedqualityCmaintenanceEnables coding agents to start, monitor, and control T3 Code / T3 Turbo threads locally via MCP.2MIT
- AlicenseAqualityBmaintenanceEnables external agents to list T3 environments and projects, start coding threads, monitor progress, send follow-up instructions, and interrupt running turns via MCP.73MIT