MCP server

Setup

Other clients

Any client that speaks Streamable HTTP connects the same way, with the URL and an Authorization header. Try the server with the MCP Inspector.

npx @modelcontextprotocol/inspector --cli https://gemlead.ai/mcp \
  --transport http \
  --header "Authorization: Bearer $GEMLEAD_API_KEY" \
  --method tools/list

Several X accounts

A connection is for one X account. To work on several at once, add Gemlead once for each account, each with its own server URL, https://gemlead.ai/mcp/ and a name you choose, like https://gemlead.ai/mcp/acme and https://gemlead.ai/mcp/julien. The name is only a label, made of letters, digits, - and _.

Connect each one and pick its X account on Gemlead's consent page. A name that is the account's X username picks it for you. If the accounts are on different Gemlead logins, sign in to the right one before you connect.

Each connection reads and acts on its own account only, and tells the assistant which @handle it is, so a DM always goes out from the account you asked for. Name each connector after its account, like Gemlead Acme, to tell them apart in the chat.

Tools

The server has 67 tools, one for each thing the API does. Read tools only read. Write tools change data or act on X from your account, so they need the write scope, and the assistant asks you before it sends, starts or deletes anything.

Click an endpoint's MCP tag in the API reference to land on its tool.

No tool sets or removes the X Chat passcode, by design, so a passcode never goes through an AI chat. Set it in the app or with Set the X Chat passcode.

Arguments and results

• A tool takes the parameters of its endpoint, with IDs named after their object, like lead_id, persona_id, campaign_id, conversation_id or export_id. Lists page with limit and cursor, as in Pagination.
• A tool that does several things takes an action, a kind or a status, like lead_action with action set to rescore, refresh, follow or unfollow.
• list_campaigns takes status as an array of draft, active, paused and archived. get_campaign_stats counts from from up to to, both ISO 8601 times, to by default now and from 30 days before it.
• create_export takes the filters of search_leads in filters, without limit and cursor. With type set to conversations, it exports every DM conversation with its whole thread, and filters takes persona_id and unread. It runs on a read key, as Create an export does.
• ask_julien_ai sends text to Julien AI, with chat_id to go on in a chat. An answer that takes more than 25 seconds comes back running with its id. Call the tool again with only reply_id set to it, and it waits up to 25 seconds more.
• get_conversation and list_messages list each message's media with a url. view_media takes the url of an image or a GIF and shows the image itself to the assistant, so it can read a screenshot a lead sent. send_message sends one with media, a public https url or base64 data with its mime_type.
• A wrong argument comes back as a tool error that names it. An API error comes back as a tool error with its code and the argument it is about.

Each tool answers with the JSON of its endpoint, as structured content and as text. The tools publish no output schema, the API reference describes every object.

On the Free and Starter plans the server installs and lists its tools, and each call answers with a plan_required error the assistant can explain. Tool calls count toward the key's 120 requests a minute, shared with the REST API.

Example prompts

• Show me today's hot leads for my Tipsters persona, with the reason each one scored high.
• Which campaign had the best reply rate over the last 30 days, and how many DMs did it send?
• List my unread conversations and summarize what each lead is asking for.
• Export every hot lead found this week to CSV and give me the link.
• Export all my DM conversations, then tell me which openers get the most replies and how leads answer the price.
• Mark the lead @jane_builds as closed and save her HubSpot ID hs_48213 in its metadata.
• Put Sam AI on Semi-auto for my Tipsters persona and add our pricing PDF to what it reads.

Security

• The assistant only sees the X account you connected.
• Revoke a connection or a key in the app, under API, at any time.
• Give a read key to an assistant that only needs to read.
• Assistants can be tricked by text they read. Check what a write tool is about to do before you allow it.