diff --git a/apps/web/src/components/CommandPalette.tsx b/apps/web/src/components/CommandPalette.tsx index 15c00fcba186d..d3d6b104c5878 100644 --- a/apps/web/src/components/CommandPalette.tsx +++ b/apps/web/src/components/CommandPalette.tsx @@ -1643,6 +1643,8 @@ function OpenCommandPaletteDialog(props: { "mcp", "connector", "another app", + "claude code", + "codex", "poke", "claude", "chatgpt", diff --git a/apps/web/src/components/mcp/UseInAnotherAppDialog.tsx b/apps/web/src/components/mcp/UseInAnotherAppDialog.tsx index 8518f75263c81..3751dd47c8868 100644 --- a/apps/web/src/components/mcp/UseInAnotherAppDialog.tsx +++ b/apps/web/src/components/mcp/UseInAnotherAppDialog.tsx @@ -578,10 +578,26 @@ function ConnectStep({ ); if (anotherWay || app === null) { const message = app?.handoff.kind === "copy-message" ? app.handoff.message(mcpUrl) : null; + const prompt = app?.handoff.kind === "copy-prompt" ? app.handoff.prompt(mcpUrl) : null; + const commands = + app?.handoff.kind === "copy-prompt" || app?.handoff.kind === "commands" + ? app.handoff.commands(mcpUrl) + : null; return (
{message ? : null} + {prompt ? : null} + {commands !== null && commands.length > 0 ? ( +
+ {commands.map((command) => ( + + ))} +

+ Run these where {app?.name ?? "the app"} runs. +

+
+ ) : null}
    {(app?.steps ?? OTHER_MCP_APP_STEPS).map((step) => (
  1. {step}
  2. @@ -597,7 +613,11 @@ function ConnectStep({ {code} {app === null ? null : ( setAnotherWay(false)}> - {app.handoff.kind === "commands" ? "Back to commands" : "Back to one click"} + {app.handoff.kind === "commands" + ? "Back to commands" + : app.handoff.kind === "copy-prompt" + ? "Back to prompt" + : "Back to one click"} )} @@ -665,6 +685,7 @@ function PrimaryAction({ app, mcpUrl }: { readonly app: McpApp; readonly mcpUrl: // The desktop app reports a link nothing opens and falls back; a browser cannot tell, and // opens an app link in place (a new tab for it would stay blank), so its toast keeps the web. const openApp = () => { + if (link === null) return; if (appLink === null) return openLink(link); if (!isElectron) return window.location.assign(appLink); void readLocalApi() @@ -688,7 +709,7 @@ function PrimaryAction({ app, mcpUrl }: { readonly app: McpApp; readonly mcpUrl: title: copy.title, // A browser can block an open that follows the copy, and no platform reliably reports an // app link nothing handles (Linux says it opened), so these keep a way through. - ...(isElectron && appLink === null + ...(link === null || (isElectron && appLink === null) ? {} : { actionProps: { diff --git a/apps/web/src/components/mcp/agentConnectPrompt.test.ts b/apps/web/src/components/mcp/agentConnectPrompt.test.ts new file mode 100644 index 0000000000000..ce19a5045a308 --- /dev/null +++ b/apps/web/src/components/mcp/agentConnectPrompt.test.ts @@ -0,0 +1,44 @@ +import { describe, expect, it } from "vite-plus/test"; + +import { + claudeCodeConnectPrompt, + claudeCodeMcpCommands, + codexConnectPrompt, + codexMcpCommands, +} from "./agentConnectPrompt"; + +const MCP_URL = "https://prod-a1.t3coderelay.com/mcp?x=1"; + +describe("agent connect prompts", () => { + it("embeds the MCP URL in Claude Code and Codex commands", () => { + expect(claudeCodeMcpCommands(MCP_URL)).toEqual([ + `claude mcp add --transport http t3 ${MCP_URL}`, + "claude mcp login t3", + ]); + expect(codexMcpCommands(MCP_URL)).toEqual([ + `codex mcp add t3 --url ${MCP_URL}`, + "codex mcp login t3", + ]); + }); + + it("gives each agent a pasteable prompt with add, login, and confirm steps", () => { + const claude = claudeCodeConnectPrompt(MCP_URL); + expect(claude).toContain(MCP_URL); + expect(claude).toContain("claude mcp add --transport http t3"); + expect(claude).toContain("claude mcp login t3"); + expect(claude).toContain("--no-browser"); + expect(claude).toContain("claude mcp list"); + expect(claude).toContain("t3_project_list"); + expect(claude).toContain("reload"); + + const codex = codexConnectPrompt(MCP_URL); + expect(codex).toContain(MCP_URL); + expect(codex).toContain("codex mcp add t3 --url"); + expect(codex).toContain("codex mcp login t3"); + expect(codex).toContain("--no-browser"); + expect(codex).toContain("codex mcp list"); + expect(codex).toContain("configured servers"); + expect(codex).toContain("t3_project_list"); + expect(codex).toContain("reload"); + }); +}); diff --git a/apps/web/src/components/mcp/agentConnectPrompt.ts b/apps/web/src/components/mcp/agentConnectPrompt.ts new file mode 100644 index 0000000000000..e3abe0411b70b --- /dev/null +++ b/apps/web/src/components/mcp/agentConnectPrompt.ts @@ -0,0 +1,39 @@ +/** Copy-paste prompts and CLI commands so Claude Code or Codex can connect T3 over MCP. */ + +export function claudeCodeMcpCommands(mcpUrl: string): readonly string[] { + return [`claude mcp add --transport http t3 ${mcpUrl}`, "claude mcp login t3"]; +} + +export function codexMcpCommands(mcpUrl: string): readonly string[] { + return [`codex mcp add t3 --url ${mcpUrl}`, "codex mcp login t3"]; +} + +export function claudeCodeConnectPrompt(mcpUrl: string): string { + return [ + "Connect this T3 Code environment over MCP so you can use its tools from this session.", + "Tell me what you will run before you change any MCP config, then:", + "", + ...claudeCodeMcpCommands(mcpUrl).map((command) => `- \`${command}\``), + "", + "If login opens a browser, wait for me to approve the sign-in page.", + "If there is no browser, use `claude mcp login t3 --no-browser`, give me the URL, and paste the final URL back when asked.", + "When `claude mcp list` shows `t3` as connected, try a read-only T3 tool such as `t3_project_list` in this session.", + "If those tools are not available yet, tell me to reload or start a new Claude Code session, then confirm again.", + "Only when a T3 tool works here, say you are ready and ask what I want to do in T3 Code.", + ].join("\n"); +} + +export function codexConnectPrompt(mcpUrl: string): string { + return [ + "Connect this T3 Code environment over MCP so you can use its tools from this session.", + "Tell me what you will run before you change any MCP config, then:", + "", + ...codexMcpCommands(mcpUrl).map((command) => `- \`${command}\``), + "", + "If login opens a browser, wait for me to approve the sign-in page.", + "If there is no browser, use `codex mcp login t3 --no-browser`, give me the URL, and paste the final URL back when asked.", + "`codex mcp list` only shows configured servers; when it lists `t3` with OAuth, try a read-only T3 tool such as `t3_project_list` in this session.", + "If those tools are not available yet, tell me to reload or start a new Codex session (or check `/mcp` for active servers), then confirm again.", + "Only when a T3 tool works here, say you are ready and ask what I want to do in T3 Code.", + ].join("\n"); +} diff --git a/apps/web/src/components/mcp/logos/codex.png b/apps/web/src/components/mcp/logos/codex.png new file mode 100644 index 0000000000000..7a358ef60d5bb Binary files /dev/null and b/apps/web/src/components/mcp/logos/codex.png differ diff --git a/apps/web/src/components/mcp/mcpApps.test.ts b/apps/web/src/components/mcp/mcpApps.test.ts index 2e9328cf78784..c7f3ae9d9ee16 100644 --- a/apps/web/src/components/mcp/mcpApps.test.ts +++ b/apps/web/src/components/mcp/mcpApps.test.ts @@ -8,7 +8,7 @@ describe("MCP app links", () => { it("fill in T3 Code and the encoded URL", () => { const opened = (id: string) => { const app = MCP_APPS.find((candidate) => candidate.id === id)!; - return new URL(mcpHandoffAction(app, MCP_URL)!.link); + return new URL(mcpHandoffAction(app, MCP_URL)!.link!); }; const poke = opened("poke"); expect(poke.searchParams.get("name")).toBe("T3 Code"); @@ -18,6 +18,19 @@ describe("MCP app links", () => { expect(claude.searchParams.get("connectorUrl")).toBe(MCP_URL); }); + it("copies agent prompts for Claude Code and Codex without opening a link", () => { + for (const id of ["claude-code", "codex"] as const) { + const app = MCP_APPS.find((candidate) => candidate.id === id)!; + const action = mcpHandoffAction(app, MCP_URL)!; + expect(action.link).toBeNull(); + expect(action.copy?.text).toContain(MCP_URL); + expect(action.label).toContain(app.name); + expect(app.handoff.kind).toBe("copy-prompt"); + if (app.handoff.kind !== "copy-prompt") throw new Error("expected copy-prompt"); + expect(app.handoff.commands(MCP_URL).some((command) => command.includes(MCP_URL))).toBe(true); + } + }); + // The desktop app opens only https links and the bare app launch links it lists. it.each(MCP_APPS.map((app) => [app.name, app] as const))("%s opens only https", (_, app) => { const action = mcpHandoffAction(app, MCP_URL); diff --git a/apps/web/src/components/mcp/mcpApps.ts b/apps/web/src/components/mcp/mcpApps.ts index e32dac3e361e6..d26bebb017877 100644 --- a/apps/web/src/components/mcp/mcpApps.ts +++ b/apps/web/src/components/mcp/mcpApps.ts @@ -1,5 +1,12 @@ +import { + claudeCodeConnectPrompt, + claudeCodeMcpCommands, + codexConnectPrompt, + codexMcpCommands, +} from "./agentConnectPrompt"; import chatgptLogo from "./logos/chatgpt.png"; import claudeLogo from "./logos/claude.png"; +import codexLogo from "./logos/codex.png"; import geminiLogo from "./logos/gemini.png"; import grokBotLogo from "./logos/grokbot.png"; import hermesLogo from "./logos/hermes.png"; @@ -25,6 +32,15 @@ export type McpAppHandoff = readonly appLink?: (message: string) => string; readonly message: (mcpUrl: string) => string; } + /** + * Copies a prompt the person pastes into the coding agent; optional CLI commands under + * Set up another way. + */ + | { + readonly kind: "copy-prompt"; + readonly prompt: (mcpUrl: string) => string; + readonly commands: (mcpUrl: string) => readonly string[]; + } /** Commands to run where the app runs. */ | { readonly kind: "commands"; readonly commands: (mcpUrl: string) => readonly string[] }; @@ -45,6 +61,38 @@ export interface McpApp { const encoded = encodeURIComponent; export const MCP_APPS: readonly McpApp[] = [ + { + id: "claude-code", + name: "Claude Code", + logo: claudeLogo, + handoff: { + kind: "copy-prompt", + prompt: claudeCodeConnectPrompt, + commands: claudeCodeMcpCommands, + }, + steps: [ + "Paste the prompt into Claude Code and let it add and sign in to the MCP server.", + "Or run the commands yourself in the terminal where Claude Code is installed.", + ], + note: "Paste into Claude Code. It runs the MCP add and login for you.", + docs: "https://code.claude.com/docs/en/mcp", + }, + { + id: "codex", + name: "Codex", + logo: codexLogo, + handoff: { + kind: "copy-prompt", + prompt: codexConnectPrompt, + commands: codexMcpCommands, + }, + steps: [ + "Paste the prompt into Codex and let it add and sign in to the MCP server.", + "Or run the commands yourself in the terminal where Codex is installed.", + ], + note: "Paste into Codex. It runs the MCP add and login for you.", + docs: "https://developers.openai.com/codex/mcp", + }, { id: "poke", name: "Poke", @@ -183,7 +231,7 @@ export const OTHER_MCP_APP_STEPS = ["Add a remote MCP server with OAuth."] as co /** * The primary button for `app`: its label, the https page it opens, and what it copies first. - * Null for apps set up with commands. It never copies the approval code. + * Null for apps set up with commands only. It never copies the approval code. */ export function mcpHandoffAction(app: McpApp, mcpUrl: string) { const { handoff } = app; @@ -211,6 +259,13 @@ export function mcpHandoffAction(app: McpApp, mcpUrl: string) { copy: { text: message, title: "Message copied" }, }; } + case "copy-prompt": + return { + label: `Copy prompt for ${app.name}`, + link: null, + appLink: null, + copy: { text: handoff.prompt(mcpUrl), title: "Prompt copied" }, + }; case "commands": return null; } diff --git a/apps/web/src/components/settings/SavedEnvironmentRows.tsx b/apps/web/src/components/settings/SavedEnvironmentRows.tsx index 866841b4bc6b7..67bbfad86a44c 100644 --- a/apps/web/src/components/settings/SavedEnvironmentRows.tsx +++ b/apps/web/src/components/settings/SavedEnvironmentRows.tsx @@ -153,7 +153,7 @@ export function SavedBackendListRow({ toastManager.add({ type: "success", title: "MCP URL copied", - description: `Add it to an agent, e.g. claude mcp add --transport http t3 ${url}`, + description: `Paste a prompt from Use T3 Code in another app, or run: claude mcp add --transport http t3 ${url}`, }); }, onError: (error) => { diff --git a/docs/user/outside-agents.md b/docs/user/outside-agents.md index dc9af3ad5167c..cbc7c7c003963 100644 --- a/docs/user/outside-agents.md +++ b/docs/user/outside-agents.md @@ -6,6 +6,30 @@ 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. +## Let your coding agent connect + +For Claude Code or Codex, the fastest path is to have the agent set up the +connection itself. + +1. In T3 Code, open the command palette (`Cmd/Ctrl+K`) and choose **Use T3 Code + in another app (MCP)**. Pick **Claude Code** or **Codex**. +2. Copy the prompt and paste it into that agent. It adds the MCP server, runs + login, and waits while you approve the sign-in page. +3. When it confirms the connection, tell it what you want done in T3 Code. + +You can also install a skill that walks any Claude Code or Codex session through +the same steps (it will ask for the MCP URL if you have not pasted one yet): + +```sh +# Claude Code +npx skills add https://github.com/pingdotgg/t3code/tree/main/skills/t3-connect --skill t3-connect --agent claude-code +# Codex +npx skills add https://github.com/pingdotgg/t3code/tree/main/skills/t3-connect --skill t3-connect --agent codex +``` + +Then type `/t3-connect` in Claude Code, or `$t3-connect` in Codex. Hosted apps +and a manual CLI path are below. + ## Add T3 Code to an assistant app Open the command palette (`Cmd/Ctrl+K`) and choose **Use T3 Code in another @@ -98,6 +122,9 @@ T3 Code. ## Claude Code +Prefer the [prompt or skill](#let-your-coding-agent-connect) above. To run the +commands yourself: + ```sh claude mcp add --transport http t3 https:///mcp claude mcp login t3 @@ -110,6 +137,9 @@ once you approve. ## Codex +Prefer the [prompt or skill](#let-your-coding-agent-connect) above. To run the +commands yourself: + ```sh codex mcp add t3 --url https:///mcp codex mcp login t3 diff --git a/skills/t3-connect/SKILL.md b/skills/t3-connect/SKILL.md new file mode 100644 index 0000000000000..f3998ff692091 --- /dev/null +++ b/skills/t3-connect/SKILL.md @@ -0,0 +1,76 @@ +--- +name: t3-connect +description: Use when a person wants Claude Code or Codex to connect to T3 Code over MCP, add the T3 MCP server, finish MCP login, or drive T3 projects and threads from an outside agent session. +--- + +# t3-connect: connect this agent to T3 Code + +T3 Code exposes an MCP server on each environment. Once this session is signed in, +you can list projects, start and message threads, and check providers without +leaving Claude Code or Codex. + +**Goal:** this session is connected and ready to use T3 tools. Stop after you +confirm the connection unless the person already asked you to do something in T3. + +Tell them what you will run before you change MCP config. Do not broaden +permissions or rewrite unrelated config to avoid prompts. + +## 1. Get the MCP URL + +You need the environment's MCP URL (`…/mcp`). Prefer one they already pasted. + +If they do not have it yet, ask them to open T3 Code, run **Use T3 Code in +another app (MCP)** from the command palette (`Cmd/Ctrl+K`), pick Claude Code or +Codex, and copy the URL (or the ready-made prompt). **Settings → Environments → +Copy MCP URL** also works. Hosted agents need the T3 Connect address; a local +agent can use that or a reachable `https` / `localhost` URL. + +Do not invent an address. If they only have a plain-`http` LAN URL, explain that +sign-in needs `https` or `localhost`, and point them at T3 Connect or Tailscale +HTTPS in T3's outside-agents docs. + +## 2. Add and sign in + +Detect which harness you are: + +- Claude Code: `claude --version` works, or this session is Claude Code. +- Codex: `codex --version` works, or this session is Codex. + +Then run the matching pair (say so first): + +```sh +# Claude Code +claude mcp add --transport http t3 +claude mcp login t3 + +# Codex +codex mcp add t3 --url +codex mcp login t3 +``` + +If login opens a browser, wait for them to approve. If there is no browser, use +`--no-browser`, give them the printed URL, and paste the final URL back when +asked. A one-time code from T3's wizard or `t3 auth pairing create` may be needed +on older environments; only use a code they just minted. + +## 3. Confirm, then ask what to do + +- Claude Code: `claude mcp list` shows `t3` as connected. +- Codex: `codex mcp list` shows `t3` with OAuth. That lists configured servers, + not that this session already has them active (`/mcp` in the Codex TUI shows + active ones). + +Then try a read-only T3 tool in this session, such as `t3_project_list`. If the +tools are missing, tell them to reload or start a new session and confirm again. +Only when a T3 tool works here, say you are connected. If they have not already +given a task, ask what they want to do in T3 Code. Prefer T3's thread tools +(`t3_thread_launch`, `t3_thread_wait`, `t3_thread_read`) for work that should +show up in T3; tools that need an agent running inside T3 will say so when +called. + +## If something fails + +- `npx: command not found` is unrelated; this path uses `claude` / `codex` on PATH. +- Sign-in over plain `http` (non-localhost) will not finish; switch URL as in step 1. +- Revoke or inspect access later under T3 **Settings → Sharing & access**. +- Full reference: https://github.com/pingdotgg/t3code/blob/main/docs/user/outside-agents.md