diff --git a/README.md b/README.md index f34c275516e5dc4c9106832a34a0e51ab2712bc2..ad6ef840314034b4dd77f1e0b2516130f70b99d9 100644 --- a/README.md +++ b/README.md @@ -94,6 +94,7 @@ Full docs live in [docs/](./docs). There's no docs site yet. - [Project settings](./docs/user/project-settings.md) - [Appearance preferences](./docs/user/appearance.md) - [Remote access from a phone or another machine](./docs/user/remote-access.md) +- [Connect Claude Code, Codex, ChatGPT and other agents over MCP](./docs/user/outside-agents.md) - [Keeping app and server in sync](./docs/user/updating.md) - [Source control integrations](./docs/user/source-control.md) - Multiple accounts: [Codex](./docs/user/providers-codex.md) · [Claude](./docs/user/providers-claude.md) diff --git a/docs/README.md b/docs/README.md index 7dc2b138ad661859dee0cf05d61763641641437d..ead465ccce03984c06ce6900babb0cd1b04da732 100644 --- a/docs/README.md +++ b/docs/README.md @@ -18,6 +18,7 @@ - [Usage and limits](./user/usage.md) - [Product usage data](./user/telemetry.md) - [Remote access](./user/remote-access.md) +- [Outside agents (MCP)](./user/outside-agents.md) - [Running in the background](./user/background-service.md) - [Updating T3 Code](./user/updating.md) - Provider guides: [Codex](./user/providers-codex.md) · [Claude](./user/providers-claude.md) · [OpenCode](./user/providers-opencode.md) · [Antigravity](./user/providers-antigravity.md) · [Pi](./user/providers-pi.md) diff --git a/docs/user/outside-agents.md b/docs/user/outside-agents.md new file mode 100644 index 0000000000000000000000000000000000000000..70129139206fdad31049bda991c14f9a5b3ee4ea --- /dev/null +++ b/docs/user/outside-agents.md @@ -0,0 +1,94 @@ +# Outside agents + +Agents that T3 Code did not start can work with an environment through its MCP +server. They can read projects and threads, start and message threads, and +check which providers and models are available. This covers Claude Code or +Codex in your own terminal, ChatGPT, and bots that support MCP. Each agent signs +in once, and you choose what it may do. + +## Get the MCP URL + +In **Settings → Connections**, open a saved environment's menu and choose +**Copy MCP URL**. The URL is the environment's address followed by `/mcp`, for +example: + +```text +https:///mcp +``` + +The address must use HTTPS, or `localhost` when the agent runs on the host +itself. Agents refuse to sign in over a plain `http://` LAN or tailnet address. + +- **An agent on your own computers** can use T3 Connect, Tailscale HTTPS, or + `localhost` on the host. See [remote access](./remote-access.md). +- **A hosted agent**, such as ChatGPT or a bot running in the cloud, must reach + the environment from the internet. Use the T3 Connect address. A Tailscale + address only works from your own tailnet. + +## Approve a sign-in + +The first time an agent connects, it opens a sign-in page on the environment. +The page names the agent and where its access goes: + +- For an agent on your computer, approval returns to a `localhost` address on + the computer that opened the page. +- For a hosted agent, approval goes to that service, such as `chatgpt.com`. + Anyone who runs that service gets the access. + +Only approve a sign-in you just started. To approve, enter a pairing code from +**Settings → Connections** or from `t3 auth pairing create` on the host. A +browser already signed in to the environment as an administrator can approve +without a code. + +Then choose what the agent may do: + +- **Read only** is the default. The agent can read projects and threads and see + the available providers and models. It cannot change anything. +- **Supervised** through **Full access** also let it start, message and stop + threads in every project. A thread it starts or steers cannot run with more + permissions than the mode you chose. + +## Claude Code + +```sh +claude mcp add --transport http t3 https:///mcp +claude mcp login t3 +``` + +`claude mcp login` opens the sign-in page in your browser. On a machine +without a browser, add `--no-browser`, open the printed URL elsewhere, and +paste the final URL back when asked. `claude mcp list` shows `t3` as connected +once you approve. + +## Codex + +```sh +codex mcp add t3 --url https:///mcp +codex mcp login t3 +``` + +`codex mcp login --no-browser` prints the sign-in URL instead of opening it. +`codex mcp list` shows `t3` with OAuth once you approve. + +## ChatGPT + +Add the environment as a custom MCP app in ChatGPT's apps settings: + +1. Create a new app or plugin with a custom MCP server. +2. Set the server URL to `https:///mcp`, using the T3 + Connect address. +3. Choose **OAuth** for authentication. ChatGPT discovers the rest; you do not + need a client ID or secret. +4. Create the app, then approve the sign-in page that opens. + +## Other agents and bots + +Any agent that supports remote MCP servers over HTTP with OAuth can connect. Give +it the MCP URL and choose OAuth, and the agent finds the sign-in settings itself. +Agents without OAuth support cannot connect. + +## Remove an agent + +Approved agents appear under **Settings → Connections** like other clients. +Revoke one there to cut off its access immediately. A sign-in lasts 30 days; +after that the agent asks you to approve it again. diff --git a/docs/user/remote-access.md b/docs/user/remote-access.md index f4f36d929d4f2bb9c375cc7fd9fb8ff79aa9dd0b..491470bfa2f07c4eca7a38e81b97d6e9a29899ec 100644 --- a/docs/user/remote-access.md +++ b/docs/user/remote-access.md @@ -222,31 +222,9 @@ set `T3CODE_SERVER_BROWSER_SANDBOX=0` for the environment to run without it. ## Connect an outside agent -An agent T3 Code did not start, such as Claude Code in your own terminal, can -drive threads on an environment through its MCP server. In **Settings → -Connections**, open a saved environment's menu and choose **Copy MCP URL**, then -add it to the agent. For example: - -```sh -claude mcp add --transport http t3 https:///mcp -``` - -The first time the agent connects, it opens a sign-in page on the environment. -Enter a pairing code from **Settings → Connections** on a device that can manage -access, or from `t3 auth pairing create` on the host, and choose what the agent -may do. A browser already signed in to that environment as an administrator can -approve without a code. - -- **Read only** lets the agent read projects and threads in every project, and - see which providers and models are available. It cannot change anything. -- **Supervised** through **Full access** also let it start, message and stop - threads in every project, but it cannot start or steer a thread with more - permissions than the mode you chose. - -Use an HTTPS address: T3 Connect, Tailscale Serve, or `localhost` on the host -itself. Agents refuse to sign in through a plain `http://` LAN or tailnet -address. The agent appears under **Settings → Connections** like any other -client; revoke it there. Sign-ins last 30 days. +Claude Code, Codex, ChatGPT and other agents T3 Code did not start can drive +threads on an environment through its MCP server. See +[outside agents](./outside-agents.md) for setup. ## Manage or revoke access