> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://gtm-tools.sh/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://gtm-tools.sh/_mcp/server. # MCP > Streamable HTTP MCP endpoint with OAuth-first authentication. Wire it into Claude Desktop, Cursor, Windsurf, and any other MCP client. ## Overview The Model Context Protocol (MCP) is an open standard that lets AI clients call external tools. GTM Tools runs a hosted MCP server at `https://api.gtm-tools.sh/mcp` that exposes LinkedIn, Reddit, email-finding, buying-signal, and billing tools to any compatible client. The server supports two authentication paths: * **OAuth** (default, recommended for Claude Desktop and Claude.ai). The client signs in through `api.gtm-tools.sh`, and the server resolves your workspace from that identity on every call. Nothing to paste into a config file. * **API key** (for Cursor, Windsurf, and other clients that do not implement the MCP OAuth flow). Pass it as an `Authorization: Bearer sk_...` header. The handshake itself is gated, so an unauthenticated connection gets a `401` with a `WWW-Authenticate` header instead of an anonymous tool list. That response is what tells a client to start the OAuth flow. If you belong to more than one workspace, the OAuth path resolves to your first membership rather than asking you to pick. When a specific workspace matters, use an API key minted in that workspace. ## Setup ### Claude Desktop and Claude.ai (OAuth) 1. Open **Settings**, then **Connectors**, and click **Add custom connector**. 2. Set the name to `GTM Tools`. 3. Set the URL to `https://api.gtm-tools.sh/mcp`. 4. Click **Add**, then **Connect** on the new connector. 5. A browser window opens at `api.gtm-tools.sh`. Sign in. 6. Back in Claude, send a test message like `What is my GTM Tools credit balance?` to confirm the connection. > **Tip** > > OAuth is the recommended path for Claude products. You do not need an API key, and `get_credit_balance` costs 0 credits, so the test in step 6 is free. ### Cursor (API key) 1. Generate an API key with `get_api_key`, or run `gtm-tools admin login` and read it from `~/.gtm-tools/config.json`. See [Getting Your API Key](/knowledge-base/getting-started/getting-api-key). 2. Open Cursor settings, go to **MCP**, and add a server with this config: ```json { "gtm-tools": { "url": "https://api.gtm-tools.sh/mcp", "headers": { "Authorization": "Bearer YOUR_API_KEY" } } } ``` The key has to travel in the `Authorization` header. There is no query-parameter form and no custom key header, so a client that cannot set headers should use the OAuth flow above, or the `mcp-remote` bridge that `gtm-tools mcp add` writes. ### Windsurf and other MCP clients Use the same URL and API key pattern as Cursor. Windsurf's config lives at `~/.codeium/windsurf/mcp_config.json`; everything else is identical. ### Claude Code Add the server with the `claude mcp` command: ```bash claude mcp add --transport http gtm-tools https://api.gtm-tools.sh/mcp ``` Claude Code runs the same OAuth flow on first use. Connectors added on Claude.ai or Claude Desktop do not sync to Claude Code, so install it separately. To pin a key instead of using OAuth, append `--header "Authorization: Bearer YOUR_API_KEY"`. ### Any client, from the CLI 1. Install the CLI and sign in: `curl -fsSL https://api.gtm-tools.sh/cli/install.sh | bash`, then `gtm-tools admin login`. 2. Patch the client config in place: ```bash gtm-tools mcp add --client claude-desktop # or cursor / windsurf ``` 3. Restart the client. `mcp add` writes an `mcpServers` entry that runs the endpoint through the `mcp-remote` bridge, and it embeds your stored key as an `Authorization` header when one is available. Pass `--with-api-key sk_...` to choose the key explicitly, or `--url` and `--name` to override the defaults. For other clients (Codex, Goose, Raycast, VS Code, Cline, and more) see the [Connect](/connect) page. Frameworks have their own guides: [OpenClaw](/integrations/openclaw), [Hermes Agent](/integrations/hermes), [Google ADK](/integrations/google-adk), [LangChain](/integrations/langchain), and [Eve](/integrations/eve). ## Available tools MCP clients discover the live tool catalog from the hosted server, so there is no manifest to vendor into your config. The same contract is published over HTTP at `GET /api/v0`, which returns every tool name with its credit cost, and both come from one source of truth in the runtime. Tool names and costs cannot drift between the MCP server, the REST endpoint, the CLI, and these docs. The server exposes **64 tools**, grouped by category: 8 billing, 19 LinkedIn, 21 Reddit, 3 enrichment, and 13 signals. **13 of them cost 0 credits**, including every billing tool, the session reads, and the `detect_signal` dispatcher. For names and parameter shapes: * [Billing Tools](/billing-tools) * [LinkedIn Tools](/linkedin-tools) * [Reddit Tools](/reddit-tools) * [Enrichment Tools](/enrichment-tools) * [Signals Tools](/signals-tools) ## Troubleshooting **Your client connects but lists no tools.** It most likely defaulted to the SSE transport. Set the transport to Streamable HTTP explicitly if your client exposes that setting, and confirm the URL is `https://api.gtm-tools.sh/mcp` rather than the bare docs domain, which returns `405` to any POST. **Claude says it cannot access GTM Tools.** The connector is not installed or not connected. Follow the Claude Desktop steps above and confirm the connector shows as connected in **Settings**, then **Connectors**. **OAuth signed you into the wrong workspace.** The OAuth path resolves to your first workspace membership rather than asking you to choose. Disconnect the connector and reconnect if that was a stale session, or use an API key minted in the workspace you want, which is unambiguous. **A key that used to work now returns `401`.** `gtm-tools admin login` revokes the workspace's previous `CLI (...)`-named keys before minting a new one, so a key embedded in a client config stops working the moment someone signs in again. Run `gtm-tools admin keys list` to see what still exists, then re-key with `get_api_key`. Also confirm you copied the full value, including the `sk_` prefix. **A tool that needs a session fails.** LinkedIn and Reddit writes run through a pooled browser session, not a partner API. Check with `list_connected_linkedin_accounts` or `list_connected_reddit_accounts`, both free, and install the [browser extension](/extension) if the list is empty. **A tool returns `402` or `429`.** `402` means the workspace balance does not cover the call, so top up with `buy_credits` or enable `set_auto_reload`. `429` means waiting is the answer rather than paying — either a provider was busy, or you hit your own monthly spend ceiling (`reason: "spend_limit_reached"`, raised with `set_spend_controls`). Either way sleep the `retry_after_seconds` the tool returns and retry once; buying credits lifts neither. The full status-by-status contract is in the [Error Reference](/errors). ## Resources * [API Reference](/api-reference): the same tools over plain HTTP, no MCP client required. * [CLI](/integrations/cli): run tools from the terminal. * [Connect](/connect): copy-paste setup for every supported client. * [Error Reference](/errors): every status code and how to recover.