# Connect this AI tool to GTM Follow these instructions to connect the AI tool running this conversation to GTM through MCP. ## Shared requirements - Use the remote Streamable HTTP MCP server name `gtm` for coding clients. Name a hosted connector (Claude, ChatGPT) `GTM Work`. GTM identifies the connection by its URL, so an existing connection with either name is fine. - Install GTM for the user, not one folder, so it works in every project. - Use automatic discovery. If the fetch request does not supply a GTM MCP server URL, use `https://api.gtm-work.com/mcp` unless the user explicitly chose another discovery mode in GTM. - Treat the GTM MCP server URL supplied by the fetch request as authoritative for that environment. In the one matching client section, replace every production example URL in commands, configuration, and fallback instructions. Do not connect to, authenticate, or fall back to a different GTM server. - Identify the current client from the running session, then apply exactly one matching section below. - A running session counts as an installed client. Do not infer that a client is missing only because its CLI command is not on `PATH`. - Never install or upgrade an AI client. If this is not a supported client and no existing installation is available, stop and direct the user to its official installer. - Preserve every unrelated setting and MCP server. Replace only an existing `gtm` MCP entry. - Never print, copy, or store OAuth tokens. Complete GTM authorization through the browser flow opened by the client. - Default every AI tool to GTM activity only. MCP tool access and optional session tracking are separate checks. Install a session reporter only when the user requests session status. Lifecycle tracking never creates a Chat. Preserve saved visibility preferences. - For every client, confirm connection in the client UI, then call the read-only GTM tool `get_gtm_capabilities` with `{}`. A configured server or successful OAuth login alone is not verification. Do not claim success until the tool call succeeds through the selected environment. If session tracking was requested, verify it separately with `gtm --environment production agent status` after a new session begins. If you cannot edit the required configuration or control the required UI, give the user the exact remaining steps instead. ## Account and authorization Setup can begin before the user has a GTM account. Installing the MCP configuration does not grant access. Using GTM tools requires an authorized GTM account and workspace. After applying the matching client section: 1. Start or continue the client's native GTM OAuth flow. Never ask the user for an API key, password, OAuth token, or verification code. 2. If the user already has a GTM account and workspace, ask them to complete sign-in, choose their workspace if prompted, and grant access in the browser. 3. If the user does not have an account, ask them to choose account creation in the browser when available. If authorization cannot finish because they do not have a GTM workspace, give them `https://app.gtm-work.com/signup` and ask them to complete account and workspace onboarding there. 4. When onboarding is complete, return to the client and restart only GTM authorization. Keep the installed `gtm` MCP entry. Do not reinstall or duplicate it. 5. Call `get_gtm_capabilities` with `{}`. Do not claim success until it succeeds through the selected environment. The user must complete account creation, email verification, workspace selection, and authorization themselves. For local testing through `https://hooks-dev.gtm-work.com/mcp`, use `https://gtm.localhost` as the GTM browser app. The public tunnel serves MCP and these instructions; its origin is not the GTM sign-in page. For other nonproduction environments, use the GTM browser app supplied with the setup prompt. ## Optional session status Use the same environment for MCP, the CLI, and the GTM browser app. For local `https://hooks-dev.gtm-work.com/mcp` (or the legacy `https://gtm-mcp.localhost/mcp`), replace `--environment production` below with `--environment local`. These select separate credential profiles. Never fall back to production when local login fails. Install one adapter per environment and host; the adapters coexist and report only to their matching MCP resource. For a custom or staging endpoint, supply its matching API and credential profile explicitly. Restart the client after an environment change. With the repo-local CLI available, `gtm agent use local` or `gtm agent use production` prepares workspace configuration for Codex, Claude Code, Cursor, GitHub Copilot, and OpenCode together. Use `--client` to select one. This does not authenticate clients or install all their tracking adapters. Keep production URLs in committed configuration. Codex, Claude Code, Cursor, and OpenCode support an optional local session status reporter. MCP actions work without it. Lifecycle tracking never creates a Chat. Only an authenticated MCP tool call can create an AI tool entry in Chats, and the member's saved activity visibility preference controls whether that MCP work appears there. Real GTM actions appear in Activity by default. The adapter sends only its bound harness, host, hashed session fingerprint, bounded title, lifecycle state, and timestamps. It does not send prompts, transcript text, repository paths, model names, or MCP arguments and results. Use the GTM CLI supplied by this workspace or the user's administrator. Do not install the unrelated public registry package named `gtm`. Run `gtm --environment production auth status`; if it is not logged in, run `gtm --environment production auth login` and ask the user to complete browser sign-in. The adapter stores its reporter credential only in the private `~/.gtm` directory and does not put it in harness configuration. If the GTM CLI is unavailable, report that MCP tool access may be connected but verified session tracking is not installed. A working MCP connection does not require the optional reporter. ## Codex Confirm that this is a Codex CLI, desktop app, or IDE session. If the official `codex` CLI is available, run this command. It adds GTM to `~/.codex/config.toml`, so it works in every project: ```sh codex mcp add gtm --url https://api.gtm-work.com/mcp ``` Codex starts browser authorization when it detects OAuth. If it does not, run `codex mcp login gtm` and complete browser authorization. Otherwise, merge this table into `~/.codex/config.toml` without changing unrelated settings. If a workspace `.codex/config.toml` already has a `gtm` entry, it takes precedence: update its URL too. ```toml [mcp_servers.gtm] url = "https://api.gtm-work.com/mcp" ``` Restart or refresh Codex MCP servers. Authenticate `gtm` in the MCP servers panel or with `/mcp`, then run one read-only GTM tool. Only if session status was requested for a direct Codex session, run `gtm --environment production agent install codex`. In Codex, open `/hooks`, review the GTM user hook source, and approve it. Restart Codex, then start a new session and verify session tracking with `gtm --environment production agent status`. ## Claude Code Confirm that this is a Claude Code CLI or desktop Code session. If the official `claude` CLI is available in this session, run these commands. User scope makes GTM available in every project. The first command removes only a folder-scoped `gtm` entry, which would otherwise override the user entry with a stale URL: ```sh claude mcp remove gtm --scope local >/dev/null 2>&1 || true claude mcp add --scope user --transport http gtm https://api.gtm-work.com/mcp claude mcp login gtm ``` If the add command reports that `gtm` already exists in the user config, run `claude mcp remove gtm --scope user` and add it again. Complete browser authorization when Claude Code opens it. Otherwise, merge this object into the top-level `mcpServers` in `~/.claude.json`: ```json { "mcpServers": { "gtm": { "type": "http", "url": "https://api.gtm-work.com/mcp" } } } ``` Restart or refresh Claude Code. Authenticate `gtm` with `/mcp` or the desktop Connectors panel, then run one read-only GTM tool. Only if session status was requested for a direct Claude Code session, run `gtm --environment production agent install claude-code`. Restart Claude Code, start a new session, and verify session tracking with `gtm --environment production agent status`. ## Cursor Confirm that this is a Cursor Agent CLI or desktop session. A person can install GTM from this link, which opens Cursor and asks to install the `GTM` server: ```text cursor://anysphere.cursor-deeplink/mcp/install?name=GTM&config=eyJ1cmwiOiJodHRwczovL2FwaS5ndG0td29yay5jb20vbWNwIn0%3D ``` To configure it yourself, merge this object into `~/.cursor/mcp.json` so GTM works in every project, without changing unrelated settings. Use `.cursor/mcp.json` in the repository only if the user asks for a project-only setup. ```json { "mcpServers": { "gtm": { "url": "https://api.gtm-work.com/mcp" } } } ``` Restart or refresh Cursor MCP servers. Open Customize > MCPs, authenticate `gtm`, then run one read-only GTM tool. If the official `cursor-agent` CLI is available, `cursor-agent mcp login gtm` and `cursor-agent mcp list` are optional equivalents. Only if session status was requested for a direct Cursor session, run `gtm --environment production agent install cursor`. Restart Cursor, start a new session, and verify session tracking with `gtm --environment production agent status`. ## GitHub Copilot Confirm that this is GitHub Copilot Chat in Visual Studio Code or the Copilot CLI. In VS Code, a person can install GTM from this link, which opens VS Code and asks to install the `gtm` server: ```text https://insiders.vscode.dev/redirect/mcp/install?name=gtm&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fapi.gtm-work.com%2Fmcp%22%7D ``` In the Copilot CLI, run this command. It adds GTM to the user configuration, then open `copilot` and sign in to GTM when prompted: ```sh copilot mcp add --transport http gtm https://api.gtm-work.com/mcp ``` To configure VS Code yourself, merge this object into `.vscode/mcp.json` in the repository without changing unrelated settings: ```json { "servers": { "gtm": { "url": "https://api.gtm-work.com/mcp" } } } ``` Save the file. Select `Start` above `gtm`, then select `Auth` and complete browser authorization. Open Copilot Chat in Agent mode, confirm `gtm` appears in the tools menu, and run one read-only GTM tool. GitHub Copilot does not currently have a GTM lifecycle adapter. Confirm its connection in Copilot and check its GTM actions in Activity. ## OpenCode Confirm that this is an OpenCode CLI or desktop session. If the official `opencode` CLI is available, run this command. It adds GTM to the global OpenCode config, so it works in every project: ```sh opencode mcp add gtm --url https://api.gtm-work.com/mcp ``` Then run `opencode mcp auth gtm` and complete browser sign-in. Otherwise, merge this configuration into `~/.config/opencode/opencode.json` without changing unrelated settings. Current OpenCode releases place each server directly under `mcp`: ```json { "$schema": "https://opencode.ai/config.json", "mcp": { "gtm": { "type": "remote", "url": "https://api.gtm-work.com/mcp" } } } ``` If the existing file uses `mcp.servers`, it is using the OpenCode 2 format. Merge this configuration instead, and do not combine both shapes: ```json { "$schema": "https://opencode.ai/config.json", "mcp": { "servers": { "gtm": { "type": "remote", "url": "https://api.gtm-work.com/mcp" } } } } ``` Restart OpenCode and run one read-only GTM tool. Complete browser sign-in when prompted. If sign-in does not start, authenticate `gtm` in OpenCode's MCP management interface. If the official CLI is available, `opencode mcp auth gtm` and `opencode mcp list` are optional equivalents. Only if session status was requested for a direct OpenCode session, run `gtm --environment production agent install opencode`. Restart OpenCode, start a new session, and verify session tracking with `gtm --environment production agent status`. ## Claude A `.localhost` MCP URL is not reachable by Claude’s remote connector service. Use production or a publicly reachable development endpoint with its exact resource URL registered for OAuth. Do not describe a local URL as ready for a cloud connector. Claude web and desktop use a custom connector. If you can control the connector UI, complete these steps. Otherwise, present them to the user without claiming setup succeeded. 1. Open `https://claude.ai/customize/connectors`. 2. Select `Add custom connector`. 3. Name it `GTM Work` and enter `https://api.gtm-work.com/mcp` as the URL. Keep the recommended authentication settings. 4. Select `Add`, then select `Connect` and complete browser sign-in. 5. Enable GTM in a conversation and run one read-only GTM tool. On Team and Enterprise plans, an Owner must first add GTM in Organization settings under Connectors. Members then connect it from Customize > Connectors. Reference: `https://claude.com/docs/connectors/custom/add-unlisted` ## ChatGPT A `.localhost` MCP URL is not reachable by ChatGPT. Use production or a publicly reachable development endpoint with its exact resource URL registered for OAuth. ChatGPT connects custom MCP servers from Plugins, on the web, for Business, Enterprise and Edu workspaces. Developer mode is not required. On Business, only admins and owners can add one; on Enterprise and Edu, admins can let other members add them. If you can control the ChatGPT UI, complete these steps. Otherwise, present them to the user without claiming setup succeeded. 1. Open `https://chatgpt.com/plugins`. 2. Select the plus button, then select `Add custom MCP server`. 3. Name it `GTM Work`. Under Connection, enter `https://api.gtm-work.com/mcp`. 4. Choose OAuth authentication, review the risk warning, and select `I understand and want to continue`. 5. Select `Create as a plugin`, then install the plugin and complete browser sign-in. 6. Start a new conversation, type `@`, select GTM Work, and run one read-only GTM tool. Reference: `https://help.openai.com/en/articles/12584461-developer-mode-and-mcp-apps-in-chatgpt` ## Grok Bot Grok Bot manages custom connectors through the chat itself. It does not provide a settings form for this flow. Add GTM as a custom connector using this exact request: ```text Add this MCP server: https://api.gtm-work.com/mcp/grok ``` For development, use `https://hooks-dev.gtm-work.com/mcp/grok`. Keep the `/grok` suffix: Grok identifies itself as Cursor, and this path lets GTM display the correct tool name and connection badge. Authentication still uses the same environment's canonical `/mcp` resource and permissions. Confirm the connector details and complete browser authorization when prompted. Grok Bot runs in the cloud, so only a public HTTPS MCP endpoint using Streamable HTTP or SSE is reachable. Both GTM's production and public development endpoints meet that requirement. After setup, send a new message so the new tools become available, then run one read-only GTM tool. Reference: `https://forum.cursor.com/t/grokbot-custom-connectors/169965` ## Other MCP clients If the current client supports remote Streamable HTTP MCP servers, add a server named `gtm` with URL `https://api.gtm-work.com/mcp`. Complete browser OAuth, enable GTM, and run one read-only GTM tool. If no section matches or the client requires a different configuration surface, direct the user to `https://app.gtm-work.com/settings/integrations#integration-panel-ai-tools` and ask them to choose their AI tool.