The best way to control Claude Code, Codex and more from any computer or phone

main
md 169 lines 7.18 KB
Rendered Raw
1 # Outside agents
2
3 Agents that T3 Code did not start can work with an environment through its MCP
4 server. They can read projects and threads, start and message threads, and
5 check which providers and models are available. This covers Claude Code or
6 Codex in your own terminal, ChatGPT, and bots that support MCP. Each agent signs
7 in once, and you choose what it may do.
8
9 ## Add T3 Code to an assistant app
10
11 Open the command palette (`Cmd/Ctrl+K`) and choose **Use T3 Code in another
12 app (MCP)**, or use the button in **Settings → Sharing & access**. Pick the
13 app and follow the step for that app. Assistants like
14 Poke and Claude run in the cloud, so the wizard first asks you to sign in to T3
15 Connect and turn it on for the environment. To reach your other machines through
16 the same connection, turn on **Linked environments** in Labs and
17 [link them](./remote-access.md#link-another-environment).
18
19 When the app opens the sign-in page, choose what it may do and approve with your
20 T3 Connect account. On an older environment, the wizard asks for the level and
21 gives you a code to paste instead. A code works once, for 5 minutes, and
22 approves only that level.
23
24 For an app that is not listed, choose **Something else…**, add a remote MCP
25 server with OAuth in that app, and paste the URL. Apps that require their own
26 client ID cannot connect.
27
28 ## Get the MCP URL
29
30 In **Settings → Environments**, open a saved environment's menu and choose
31 **Copy MCP URL**. The URL is the environment's address followed by `/mcp`, for
32 example:
33
34 ```text
35 https://<environment-address>/mcp
36 ```
37
38 When T3 Connect serves the environment, the copied URL is its T3 Connect
39 address, which agents can reach from anywhere. Otherwise it uses the route this
40 device is connected over, so an agent on the same device can reach it.
41
42 - **An agent on your own computers** can use `localhost` on the host, T3
43 Connect, or any `https` address, such as
44 [Tailscale HTTPS](./remote-access.md#tailscale-https). Signing in sends the
45 agent's credentials to the environment, and agents only do that over `https`
46 or to `localhost`. A plain-`http` LAN or Tailscale address, like
47 `http://100.x.y.z:3773`, lets an agent find the environment but not finish
48 signing in.
49 - **A hosted agent**, such as ChatGPT or a bot running in the cloud, must reach
50 the environment from the internet. Use the T3 Connect address. A Tailscale
51 address only works from your own tailnet.
52
53 ## Approve a sign-in
54
55 The first time an agent connects, it opens a sign-in page. When the agent
56 reaches the environment through T3 Connect, the page opens on the T3 Code web
57 app: sign in with the T3 Connect account the environment is linked to and
58 approve there, without a code. Otherwise the page opens on the environment.
59 Either page names the agent and where its access goes:
60
61 - For an agent on your computer, approval returns to a `localhost` address on
62 the computer that opened the page.
63 - For a hosted agent, approval goes to that service, such as `chatgpt.com`.
64 Anyone who runs that service gets the access.
65
66 Only approve a sign-in you just started. On the environment's own page, enter a
67 code from **Use T3 Code in another app (MCP)**, **Settings → Sharing & access**,
68 or `t3 auth pairing create` on the host. A browser already signed in to the
69 environment with permission to manage access can approve without a code. On the
70 web app, **Use a sign-in code instead** opens the environment's own page.
71
72 A code from **Use T3 Code in another app (MCP)** already carries the level you
73 picked there. With another code, choose what the agent may do here: **Auto** is
74 selected by default, or the closest lower mode allowed by your organization’s
75 policy. Approving without a code starts at **Read only**:
76
77 - **Read only** lets the agent read projects and threads and see
78 the available providers and models. It cannot change anything.
79 - **Supervised** through **Full access** also let it start, message and stop
80 threads in every project. A thread it starts or steers cannot run with more
81 permissions than the mode you chose.
82
83 ## What outside agents can call
84
85 Some tools only work for an agent running inside a T3 thread, because they act
86 as that thread: subagents, secret requests, rendered HTML, the browser preview,
87 devices, and worktree handoff. They still appear in an outside agent's tool
88 list, but calling one returns an error saying it needs an agent running inside
89 T3 Code.
90
91 - To hand off work, start a thread with `t3_thread_launch`, then follow it with
92 `t3_thread_wait` or `t3_thread_read`, instead of `create_threads` or
93 `delegate_task`.
94 - Tools that default to the caller's own project or thread need an explicit
95 `projectId` or `threadId`.
96 - To list threads across projects, call `t3_thread_list` with
97 `allProjects: true`, or use `t3_thread_search`.
98
99 ## Claude Code
100
101 ```sh
102 claude mcp add --transport http t3 https://<environment-address>/mcp
103 claude mcp login t3
104 ```
105
106 `claude mcp login` opens the sign-in page in your browser. On a machine
107 without a browser, add `--no-browser`, open the printed URL elsewhere, and
108 paste the final URL back when asked. `claude mcp list` shows `t3` as connected
109 once you approve.
110
111 ## Codex
112
113 ```sh
114 codex mcp add t3 --url https://<environment-address>/mcp
115 codex mcp login t3
116 ```
117
118 `codex mcp login --no-browser` prints the sign-in URL instead of opening it.
119 `codex mcp list` shows `t3` with OAuth once you approve.
120
121 ## ChatGPT
122
123 Add the environment as a custom MCP app in ChatGPT's apps settings:
124
125 1. Create a new app or plugin with a custom MCP server.
126 2. Set the server URL to `https://<environment-address>/mcp`, using the T3
127 Connect address.
128 3. Choose **OAuth** for authentication. ChatGPT discovers the rest; you do not
129 need a client ID or secret.
130 4. Create the app, then approve the sign-in page that opens.
131
132 ## Other agents and bots
133
134 Any agent that supports remote MCP servers over HTTP with OAuth can connect. Give
135 it the MCP URL and choose OAuth, and the agent finds the sign-in settings itself.
136 Agents without OAuth support cannot connect.
137
138 ## Scripts on the host
139
140 On the machine that runs the environment, `t3 thread` uses the same tools
141 without a sign-in:
142
143 ```sh
144 id=$(t3 thread start . "Find why the tests are slow")
145 t3 thread send "$id" "Now fix it" --wait
146 t3 thread show "$id"
147 t3 thread list
148 ```
149
150 `.` means the project that contains the current folder, or a git worktree of
151 its repository; a project id also works. A new thread uses the project's
152 default model and permission mode, and runs in the project folder unless you
153 pass `--worktree <base-branch>`. `send` never interrupts: a busy thread gets
154 the message as its next turn. Pass `-` as the message to read it from stdin.
155
156 To choose the model, pass `--provider <instance-id> --model <slug>`. Add
157 `--option id=value` for each model option, such as `--option effort=high`.
158 Option ids and values depend on the model; `true` and `false` set on/off
159 options.
160
161 `--wait` prints the agent's reply. It exits 1 when the run fails or stops, and
162 2 when the agent waits for an answer you give in the app. Add `--json` for a
163 result that always includes the thread id.
164
165 ## Remove an agent
166
167 Approved agents appear under **Settings → Sharing & access** like other clients.
168 Revoke one there to cut off its access immediately. A sign-in lasts 30 days;
169 after that the agent asks you to approve it again.