Integrations

MCP

Connect any MCP-compatible AI agent to the GTM Tools server

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 token balance? to confirm the connection.

OAuth is the recommended path for Claude products. You do not need an API key, and get_token_balance costs 0 tokens, 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.
  2. Open Cursor settings, go to MCP, and add a server with this config:
1{
2  "gtm-tools": {
3    "url": "https://api.gtm-tools.sh/mcp",
4    "headers": { "Authorization": "Bearer YOUR_API_KEY" }
5  }
6}

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:

$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:

    $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 page. Frameworks have their own guides: OpenClaw, Hermes Agent, Google ADK, LangChain, and 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 token 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 63 tools, grouped by category: 8 billing, 19 LinkedIn, 21 Reddit, 1 email, 13 signals, and 1 geocoding. 13 of them cost 0 tokens, including every billing tool, the session reads, and the detect_signal dispatcher.

For names and parameter shapes:

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 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_tokens or enable set_auto_reload. 429 means a provider was busy rather than that you hit a limit of ours, so sleep the retry_after_seconds the tool returns and retry once. The full status-by-status contract is in the Error Reference.

Resources

  • API Reference: the same tools over plain HTTP, no MCP client required.
  • CLI: run tools from the terminal.
  • Connect: copy-paste setup for every supported client.
  • Error Reference: every status code and how to recover.