> For the complete documentation index, see [llms.txt](https://developers.gleantap.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.gleantap.com/connect-ai-tools-mcp.md). # Connect AI Tools (MCP) Connect Claude, ChatGPT, Cursor, VS Code, and any other MCP-compatible AI tool to your Gleantap account using the Gleantap MCP server. The **Gleantap MCP server** lets AI assistants work directly with your Gleantap account. Once connected, you can ask an assistant like Claude or ChatGPT to look up a contact, build a segment, draft a template, check how a campaign performed, or move a lead through a pipeline. The assistant handles these tasks with Gleantap's tools, not by guessing. MCP ([Model Context Protocol](https://modelcontextprotocol.io)) is an open standard for connecting AI tools to outside systems. Any client that supports remote MCP servers can connect to Gleantap. {% hint style="info" %} **Not a developer?** If you just want to use Gleantap from Claude or ChatGPT, follow the simpler guide in the help center: [Use Gleantap with AI Assistants](https://help.gleantap.com/use-gleantap-with-ai-assistants). {% endhint %} ## Server details | | | | ------------------ | -------------------------------------------------------------------------- | | **Server URL** | `https://mcp.gleantap.com/mcp` | | **Transport** | Streamable HTTP | | **Authentication** | OAuth 2.1 (recommended) or a Gleantap API key | | **Tools** | 267 tools covering the [Gleantap v3 API](https://api.gleantap.com/v3/docs) | ## Choose how to sign in There are two ways to authenticate. Pick one before you start. | | **OAuth (recommended)** | **API key** | | ------------ | --------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | | Best for | People connecting their own AI assistant | Scripts, headless agents, clients without OAuth support | | How it works | You add the server URL and sign in to Gleantap in a browser window. Your client stores and refreshes the token. | You paste your **API Secret** into the client's configuration. | | Access | Only the permissions and workrooms you approve on the consent screen | Full access to every workroom in the account | | Revoking | Disconnect the connector in your AI client | Delete the secret in **Settings → API** | {% hint style="info" %} **Use OAuth whenever your client supports it.** You approve access on a Gleantap consent screen and can limit it to specific workrooms. You never handle a secret yourself. {% endhint %} ### Getting an API key (only if you're not using OAuth) 1. In Gleantap, go to **Settings → API**. If the table is empty, click **Generate New Key**. 2. Copy the value in the **API Secret** column. This is the key the MCP server uses. The "API Key" column is your account ID and isn't needed here. 3. Store it like a password. It has full access to your account and every workroom in it. ## Connect your AI tool {% tabs %} {% tab title="Claude (web & desktop)" %} Works on claude.ai and in the Claude desktop app for Mac and Windows. 1. Open **Settings → Connectors**. 2. Click **Add custom connector**. 3. Enter: * **Name:** `Gleantap` * **Remote MCP server URL:** `https://mcp.gleantap.com/mcp` 4. Click **Add**, then **Connect**. 5. Sign in to Gleantap in the window that opens. Review the permissions, choose which workrooms to share, and click **Allow**. To use it, start a chat and make sure **Gleantap** is turned on in the tools menu (the **+** / tools icon in the message box). {% hint style="info" %} **Claude Team and Enterprise:** an organization Owner may need to add the connector first under **Admin settings → Connectors**. Members then connect their own Gleantap login from **Settings → Connectors**. {% endhint %} {% endtab %} {% tab title="Claude Code" %} Add the server from your terminal: ```bash claude mcp add --transport http gleantap https://mcp.gleantap.com/mcp ``` Then, inside Claude Code, run: ``` /mcp ``` Select **gleantap → Authenticate** and finish signing in to Gleantap in your browser. Add `--scope user` to make Gleantap available in every project, not just the current one. **Using an API key instead:** ```bash claude mcp add --transport http gleantap https://mcp.gleantap.com/mcp \ --header "Authorization: Bearer YOUR_API_SECRET" ``` {% endtab %} {% tab title="ChatGPT" %} ChatGPT connects to custom MCP servers through **Developer mode**. It's available on paid plans; Business, Enterprise, and Edu workspaces may require an admin to enable it. 1. Open **Settings → Apps & Connectors → Advanced settings** and turn on **Developer mode**. 2. Back in **Apps & Connectors**, click **Create**. 3. Enter: * **Name:** `Gleantap` * **MCP server URL:** `https://mcp.gleantap.com/mcp` * **Authentication:** `OAuth` 4. Confirm you trust the server and click **Create**. 5. Sign in to Gleantap when prompted and approve access. To use it, start a new chat, open the **+** menu, choose **Developer mode**, and enable **Gleantap**. {% hint style="warning" %} ChatGPT's menu names change often. If you can't find these options, search ChatGPT's help center for "Developer mode" or "custom connectors". {% endhint %} {% endtab %} {% tab title="Cursor" %} Add Gleantap to `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (one project): ```json { "mcpServers": { "gleantap": { "url": "https://mcp.gleantap.com/mcp" } } } ``` Open **Cursor Settings → MCP**. Gleantap appears in the list. Click **Login** (or **Needs authentication**) to sign in through OAuth. **Using an API key instead:** ```json { "mcpServers": { "gleantap": { "url": "https://mcp.gleantap.com/mcp", "headers": { "Authorization": "Bearer YOUR_API_SECRET" } } } } ``` {% endtab %} {% tab title="VS Code (Copilot)" %} Create `.vscode/mcp.json` in your workspace, or run **MCP: Add Server** from the Command Palette: ```json { "servers": { "gleantap": { "type": "http", "url": "https://mcp.gleantap.com/mcp" } } } ``` Click **Start** above the server entry. VS Code opens a browser window to sign in to Gleantap. The tools then become available in Copilot Chat's **Agent** mode. {% endtab %} {% tab title="Windsurf" %} Add Gleantap to `~/.codeium/windsurf/mcp_config.json`: ```json { "mcpServers": { "gleantap": { "serverUrl": "https://mcp.gleantap.com/mcp" } } } ``` Refresh the MCP list in Cascade and sign in when prompted. {% endtab %} {% tab title="Gemini CLI" %} Add Gleantap to `~/.gemini/settings.json`: ```json { "mcpServers": { "gleantap": { "httpUrl": "https://mcp.gleantap.com/mcp" } } } ``` Start Gemini CLI and run `/mcp auth gleantap` to sign in. {% endtab %} {% tab title="OpenAI Codex" %} ```bash codex mcp add gleantap --url https://mcp.gleantap.com/mcp codex mcp login gleantap ``` The second command opens a browser window to sign in to Gleantap. {% endtab %} {% endtabs %} ### Any other MCP client If your client supports **remote MCP servers over Streamable HTTP**, point it at: ``` https://mcp.gleantap.com/mcp ``` * **Clients with OAuth support** find Gleantap's sign-in automatically. The server advertises it through standard [OAuth Protected Resource Metadata](https://datatracker.ietf.org/doc/html/rfc9728) and supports dynamic client registration, so you don't need a client ID. * **Clients without OAuth support** send an API key on every request: ``` Authorization: Bearer YOUR_API_SECRET ``` * **Clients that only support local (stdio) servers** can connect through the [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) bridge: ```json { "mcpServers": { "gleantap": { "command": "npx", "args": ["-y", "mcp-remote", "https://mcp.gleantap.com/mcp"] } } } ``` ## Check that it works After connecting, ask your assistant: > List my Gleantap workrooms. If it returns your workrooms, you're set up. If not, see [Troubleshooting](#troubleshooting). ## What you can do The server exposes 267 tools across every major part of Gleantap: | Area | Examples | | ---------------------------------------- | --------------------------------------------------------------------------------------------- | | **Contacts & events** | Find, create, update, merge, and opt contacts in or out; record events; add notes | | **Segments** | Build segments from a description, preview who matches, refresh, convert to static | | **Templates & campaigns** | Draft and preview email/SMS templates, send tests, schedule or send campaigns, pull analytics | | **Flows** | Create and publish automations, enroll or unenroll contacts, test-run, view flow analytics | | **Conversations** | Read the inbox, reply, assign, tag, close and reopen conversations | | **Pipelines, tasks & sales automations** | Move contacts between stages, create and complete tasks | | **Appointments & calendars** | Book, reschedule, and cancel appointments; manage calendars and appointment types | | **Forms & pages** | Build, publish, and read submissions from forms and landing pages | | **Keyword campaigns** | Create SMS keyword campaigns and view their reports | | **Reporting** | Contact, message, conversion, campaign, and flow reports; scorecards and custom metrics | | **Settings** | Workrooms, phone numbers, email addresses, custom fields, tags, webhooks, imports | ### Example prompts * *"How many contacts joined in the last 30 days who haven't booked a class yet?"* * *"Build a segment of members whose membership expires in the next two weeks, and show me 10 of them before saving."* * *"Draft a friendly SMS template inviting lapsed members back for a free class. Don't send it."* * *"How did last Tuesday's newsletter perform compared to the one before?"* * *"Show me every open conversation assigned to me and summarize what each person needs."* * *"Move Jane Doe to the 'Trial Booked' stage in the Leads pipeline and create a follow-up task for tomorrow."* ## Safety: what happens before the assistant changes something Every tool tells your AI client whether it only **reads** data (117 tools) or **changes** it (150 tools). Most clients use this to decide when to ask for your approval. Read-only tools may run on their own; tools that change data prompt you first. Some actions **cannot be undone**. Read the confirmation carefully before approving them: | Type | Tools | Why it matters | | ------------------- | -------------------------------------------------------------------------------- | ------------------------------------------ | | **Sends** | Send email / SMS / voice, send campaign now, reply to conversation | Delivered immediately — no recall | | **Going live** | Publish flow / form / page / template, schedule campaign, enroll contact in flow | Keeps sending automatically afterwards | | **Deletes** | Any delete or remove action | No trash, no undo | | **One-way changes** | Merge contacts, convert segment to static | The original state can't be restored | | **Secret rotation** | Rotate webhook secret, rotate form submission token | Live integrations break until updated | | **Cancellations** | Cancel campaign, cancel appointment | Someone was expecting that send or booking | {% hint style="warning" %} **Tips for working safely** * Ask the assistant to **preview** first: "show me who's in this segment," "preview this template," "send a test to me." * There is no sandbox, so every action hits your real account. Practice on a **test contact** or a **test workroom**, and with OAuth, share only that workroom while you get comfortable. * Don't use your client's "always allow" setting on tools that send messages or delete data. {% endhint %} ## Workrooms If your account has more than one workroom (for example, one per location): * **With OAuth**, the consent screen asks which workrooms to share. The assistant can only see the ones you choose. * **With an API key**, the assistant can see every workroom in the account. Tell it which one to use: *"In the Downtown workroom, ..."* The assistant can always run **List workrooms** to see what's available. ## Disconnecting * **OAuth:** remove or disconnect the Gleantap connector in your AI client (for example, **Settings → Connectors → Gleantap → Disconnect** in Claude). * **API key:** delete the secret in Gleantap under **Settings → API**. Any client using it stops working immediately. ## Troubleshooting | Problem | What to do | | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **`401 Unauthorized` / "Missing Authorization"** | Your client isn't sending credentials. Reconnect and finish the sign-in, or check the `Authorization: Bearer ...` header (it needs the word `Bearer` and a space). | | **Sign-in window never appears** | Your client may not support OAuth for remote servers. Use an API key header or the `mcp-remote` bridge above. | | **Connected, but no Gleantap tools show up** | Turn the connector on for the current chat (Claude: tools menu; ChatGPT: **+ → Developer mode**). In IDEs, restart the MCP server from settings. | | **"Not found" for a contact or workroom you know exists** | Your OAuth sign-in probably didn't include that workroom. Disconnect, reconnect, and select it on the consent screen. | | **"Permission denied" / missing scope** | You declined a permission during sign-in. Reconnect and approve the permissions the task needs. | | **Rate limit errors (`429`)** | Too many requests in a short time. Wait a moment, or ask the assistant to work in smaller batches. | | **Can't find "Add custom connector" (Claude) or "Developer mode" (ChatGPT)** | Your plan or workspace admin may not allow custom connectors. Ask your admin. | Still stuck? Email with the name of your AI client and the exact error message. ## For developers * The MCP server is a thin layer over the **Gleantap v3 REST API**. Every tool maps to one v3 endpoint, with the same permissions, errors, and limits. If you're building a traditional integration (not an AI agent), call the [v3 API](https://api.gleantap.com/v3/docs) directly. * **OAuth discovery:** `https://mcp.gleantap.com/.well-known/oauth-protected-resource` → authorization server `https://api.gleantap.com/v3` (Authorization Code + PKCE, dynamic client registration, rotating refresh tokens). * **Accepted credentials:** `gltp_at_...` OAuth access tokens, or the API Secret from **Settings → API** (optionally prefixed `gltp_sk_live_`), sent as `Authorization: Bearer `. * **Errors** come back as typed MCP errors translated from the API's [RFC 9457](https://datatracker.ietf.org/doc/html/rfc9457) problem details. * **Retries:** the server automatically adds an `Idempotency-Key` to retryable `POST` requests, so a retried create isn't duplicated.