Repository avatar
Security
v1.0.1
active

mcp

ai.gleap/mcp

Gleap's official MCP server: tickets, contacts, CRM, help center and support stats. OAuth sign-in.

Documentation

Gleap MCP Server

Connect your Gleap workspace to Claude and other AI assistants via the Model Context Protocol. Manage tickets, contacts, help center articles, and statistics using natural language.

Prerequisites

  • A Gleap account with at least one project
  • An API key (Gleap → Settings → Developer → API keys) and your project (the Project ID from Settings → Project → General, or the project's internal ID)

Local development

Install dependencies, then build and run the server locally:

npm install    # install dependencies
npm run build  # compile TypeScript to build/
npm start      # run the compiled server (node build/index.js)

Use npm run dev to recompile automatically on file changes while you work.

Node.js 22 (engines in package.json). Before opening a PR, run npm run typecheck, npm test and npm run build; CI runs them too. Coding agents: see AGENTS.md.

Connecting to Claude (OAuth — recommended)

  1. In Claude, open Settings → Connectors and add a custom connector
  2. Enter the Gleap MCP server URL of the region your Gleap workspace is hosted in:
    • EU: https://mcp.gleap.ai/mcp
    • US: https://mcp.us.gleap.ai/mcp
  3. Click Connect — you'll be redirected to Gleap to authorize access
  4. Select the project you want Claude to access and approve the requested scopes
  5. Done. Claude can now read and manage your Gleap workspace with your role in that project.

No API key or client ID setup is required. The OAuth flow handles authentication automatically.

Alternative: API key auth (for clients that support custom headers)

Send these headers with every request:

HeaderValue
x-gleap-api-keyYour Gleap API key
x-gleap-project-idYour project: the Project ID (Settings → Project → General) or its internal ID

Coding sessions

A coding agent working a Gleap ticket names its coding session, with the sessionId argument of a tool (report_progress, send_message, …) or for every call with the header x-gleap-session-id (the client sets it from .gleap/session.json, a Kai Code sandbox from its MCP config; OAuth and API-key connections alike). The server then sends X-Gleap-Session-Id with every write of that tool call (reads go without it), plus X-Gleap-Session-Explicit: 1 when the id came from the tool's own sessionId argument (Gleap refuses every write that explicitly names a stopped session): Gleap books the writes to the session's agent (an agent's reply does not stop the agent the way a teammate's does) and checks each write against the session (the episode guard). A session id that does not count for the write (another project's session, one not linked to the written ticket, or one left behind in .gleap/session.json) is ignored: the write is then the caller's own, as without a session. The results then also carry what Gleap says about the session, whatever the tool:

  • stop: true: the ticket is no longer the session's (a teammate took it over, replied to the customer, unassigned the agent or stopped the session). The result is only the STOP instruction, with structuredContent.gleapStop: true: the field Kai Code's runner and the Gleap plugin act on (never words in a result). Only this server sets it; a field of that name in API data is dropped.
  • newCustomerMessages: what the customer wrote that the agent has not been shown, listed after the result.
  • A send written before the customer's newest message is refused (409) with those messages (staleThread: true in the result): the agent reads them, adjusts and sends once more.

Without a session id nothing changes: no header, no extra lines.

Available Tools

ToolDescription
search_ticketsFull-text search across tickets
find_ticketsFilter tickets by status, priority, assignee, tags, date
get_ticketGet a specific ticket by ID
create_ticketCreate a new ticket
get_ticket_typesList ticket types with their custom fields, status lanes and priorities
get_ticket_messagesGet the full conversation history (messages) for a ticket
get_ticket_activity_logGet the console logs, network requests and click trail the SDK captured with a ticket. Coding agents call it on bug reports before reproducing, to see the console errors, failed requests and the user's clicks. Headers are never returned, secrets are redacted and long logs are trimmed (errors and failed requests first); section and search narrow it
send_messageReply to a customer or add an internal note (Markdown). Agent workflows: the agent asks its operator in its own conversation (an instruction to answer or update the customer is the approval), then sends; with sessionId the reply is the session agent's and Gleap refuses a stale one (stale_thread, with the new messages) or one after a stop
draft_reply_to_composerStage a drafted reply in the ticket's dashboard composer for a person to review, edit and send. Sends nothing. For a person's own AI client, also when a .gleap/session.json from another ticket is still around: Gleap refuses Kai runs and the coding session working that ticket (410), which ask their operator and send with send_message
report_progressReport the fix status on the Gleap coding session you were started from (deeplink hand-off loop; session-scoped since 2026-08), the same snapshot every runtime reports: status (queued, working, needs_input, completed, failed, cancelled), step while working (investigating, reproduced, fixing), a one-line message, question with needs_input (kind, prompt, options, audience customer or team), customerLine (one sentence of status the customer may read), howSolved (one paragraph on how the ticket was solved, sent with the last report; it feeds Kai Support's learning), agentKind, agentName and device. The older phase still works: status wins, and a report with only status also sends the phase it stands for, for a Server from before the fix status. Registers PRs (completed with prUrl) and takes the two fix messages: customerUpdateMessage (sent right away) and customerShipMessage (sent when the fix is live, by the project's post-merge setting); the result says what happened to each. The ticket is done when the customer confirms or 24 hours after the last answer without a reply, not at the merge. The result also carries stop, newCustomerMessages (see Coding sessions) and the hook block for .gleap/session.json
update_planLive checklist on the Gleap coding session (sessionId or ticketId, like report_progress): the whole list each call, statuses pending/in_progress/completed/cancelled
wrap_upEnd-of-turn card on the session: recap, at most one question, 0-2 actions (merge_pr, open_pr, review_changes, open_preview; send_customer_update is removed and refused)
share_screenshotPost a screenshot (optionally a before/after pair) into the session thread. Returns the curl -T upload commands to run (the server cannot read local files); imageBase64 (≤ 1.5 MB each) for agents without a shell
publish_artifactPublish a self-contained HTML page (≤ 1 MB) into the session thread; artifactId publishes a new version
get_agent_workflowThe Gleap ticket workflow (fix, answer, feature) as Markdown, plus the .gleap/session.json content for the Gleap plugin
get_ticket_screenshotThe ticket's SDK screenshot as image content (Gleap file hosts only, ≤ 2 MB)
describe_databaseThe team's own databases Kai Code may read (read-only, this ticket's customer only): tables, columns, masked columns, query format. Kai Code runs on a ticket only (the run key's ticket pin); refused for every other connection
query_databaseOne read-only query (a SQL SELECT or a MongoDB JSON request) on the team's database, kept to the ticket's customer (scope: team across customers always waits for a data owner); at most 200 rows, sensitive columns masked. It may wait for a person's approval (status: pending with a queryId). Values from results never go into code, tests, fixtures, commits or PRs. Kai Code runs on a ticket only
get_query_resultThe status of a query that waited for approval, and its rows once a data owner let it run (kept a day). Kai Code runs on a ticket only
get_workflowsList all workflows in the project (live and draft), with their channels, whether Kai Support answers in them (kaiAnswers) and the agent they pass to
get_workflows_available_for_ticketList the live workflows startable on a specific ticket
run_ticket_workflowManually start a workflow on a ticket (the "Start a workflow" action)
get_setup_statusWhere the project stands for AI support: the Hard tickets settings (hardTickets: on a click or automatically, on Kai Code Cloud or a Bridge machine; ticketDone: thank-you and review ask), the default team, and (admins of a new workspace) the signup steps left
get_agentsThe project's AI agents: name, live or draft, customer-facing or team
set_ai_modeRemoved (stub for one release): AI-first and AI-assisted are gone; does nothing and points to update_workflow and the Hard tickets settings
start_kai_resolveRemoved (stub for one release): Kai Resolve is Kai Support's hard-ticket mode, started with Work on it on the ticket or automatically; does nothing and says so
update_workflowChange which channels a workflow runs on (addChannels / removeChannels) and whether it is live; never its steps
get_workflow_build_optionsWhat a workflow can use, by name: teams, tags, Your API endpoints, webhooks, integrations, sequences, contact fields, message variables
get_workflow_stepsOne workflow step by step, with path ids and step numbers, what could go live and the hashes publish_workflow_draft needs
create_workflow_draftBuild a new conversation workflow from steps; always a draft, no customer gets it
change_workflow_draftEdit a workflow's name, trigger, channels, audience and steps; a change to a live workflow waits as a draft
publish_workflow_draftMake a draft live or apply a waiting change, for the version the person agreed to (draftHash), with the editor's publish checks
create_team / update_teamCreate a team, rename it, add or remove members (others stay), change how it hands out tickets
set_default_teamThe team agents escalate to when nobody else is named (admins)
search_contactsFull-text search across contacts
get_contactsFilter contacts by email, name, company
get_contactGet a specific contact by ID
create_contactCreate a new contact
get_companiesList/search the project's companies (organisations)
get_companyGet a company by its external companyId, incl. custom data
update_companyCreate or update a company (name, plan, value, custom data)
get_pipelinesList CRM pipelines with their stages
get_pipelineGet a pipeline incl. stages and fields (fieldIds for entry values)
get_pipeline_statsPer-stage counts and field aggregations (e.g. sum of deal values per stage) plus pipeline totals
get_pipeline_entriesList a pipeline's entries, optionally for one stage
get_pipeline_entryGet one entry with its pipeline context
add_pipeline_entryAdd a company/contact to a pipeline (stage + initial values)
move_pipeline_entryMove an entry to another stage
update_pipeline_entry_valuesUpdate an entry's field values (merge; null clears)
remove_pipeline_entryRemove an entry from a pipeline (record itself is untouched)
get_record_pipelinesWhich pipelines a company/contact is on
get_help_center_sitesList the project's help center sites (id, name, url, access mode, layout, collection and article counts); older servers answer with the default site only
get_help_center_collectionsList help center collections; optional site (default or a site id) lists one site's
get_help_center_collections_treeFull tree of collections and subcollections (each carries its site)
get_help_center_articlesList articles in a collection
get_help_center_articleGet a specific article by ID
create_help_center_collectionCreate a new collection; optional site for a top-level collection
move_help_center_collections_to_siteMove top-level collections (with sub-collections and articles) to another help center site
update_help_center_collectionUpdate an existing collection
upload_imageStore a PNG, JPEG, GIF or WebP (base64 data or public url) on the project's Gleap CDN and get its permanent fileUrl
create_image_upload_linkSingle-use, 15-minute link that uploads one image from disk (curl -F file=@cover.png <link>), for agents with a shell
create_help_center_articleCreate a new article (TipTap JSON content)
update_help_center_articleUpdate an existing article. Partial per-locale updates: locales you send are changed, locales you omit are preserved
get_statistics_factsFact metrics: response times, ticket counts, SLA, AI stats
get_statistics_listList metrics: top agents, top articles, team performance
get_statistics_bar_chartBar chart data: tickets over time, ratings, SLA
get_raw_data_statisticsIndividual event rows behind the metrics, filtered by action type, agent, ticket
get_targeting_optionsEvents and contact attributes outbound messages can target, with the condition syntax
get_event_tracking_guideTracking code (SDKs + backend) for an event or contact attribute targeting needs but the project lacks
list_outbound_messagesList one outbound type: surveys, chat messages, banners, info cards, checklists, tours, tooltips, news, emails, push, WhatsApp
get_outbound_messageOne outbound item: content, targeting, reviewUrl, optional stats
create_outbound_draftDraft a survey, chat message, banner, info card, checklist, push, product tour or tooltip set
update_outbound_contentRevise a non-live outbound item's content
configure_outbound_targetingTrigger, frequency, page rules, audience and schedule of a non-live outbound item
preview_outbound_audienceCount and sample who an audience matches; saves nothing
publish_outboundSet an outbound item live after operator approval (one-offs: with the approved recipient count)
pause_outboundTake a live outbound item off
list_sequencesSequences (Outreach › Sequences) with status, how contacts are enrolled, goal, counts and reply/goal rates
get_sequenceOne sequence: enrollment, exit, goal, sending, the step tree as an outline plus editable steps, unpublished changes and what blocks going live
get_sequence_templatesThe starter templates (blank, onboarding, trial, reengage) and the full step/settings/condition/variable reference with a worked example
create_sequenceNew draft sequence from a template and/or a full definition in one call
update_sequenceChange name, enrollment, exit, goal, sending (merged) and steps (whole list or stepChanges by id); on a live sequence saved as unpublished changes
publish_sequence_changes / discard_sequence_changesMake a live sequence's unpublished changes live, or drop them
set_sequence_statusTurn a sequence live or pause it (server validation messages returned verbatim)
enroll_in_sequenceEnroll up to 500 contacts by email, userId or contact id in a live sequence (they start getting real messages); skipped contacts with reasons
get_sequence_statsCounts, reply and goal rates, exit reasons and per-step funnel
list_sequence_enrollments / get_sequence_enrollmentContacts in a sequence (filter by status, search) and one contact's timeline
manage_sequence_enrollmentPause, resume or exit one contact's run
preview_sequenceRender every message for a contact and list variables that resolve empty; sends nothing
send_sequence_test_emailSend one email step as a test to yourself or up to 5 addresses
search_feature_requestsSemantic dedupe search over feature requests: up to 5 matches with rerank scores, including requests not on the public roadmap yet (public: false)
get_feature_requestRead one feature request by id or ticket number: title, description excerpt, status, upvote count, share link (never voter identities)
subscribe_to_feature_requestIdempotently add a customer as upvoter; returns the request's status and share link
create_feature_requestFile a feature request with the customer as first upvoter. Matching requests refuse it with {ok: false, duplicate: true, candidates}; notDuplicateOf lists candidates that are a different need
list_surveys / get_surveysSurveys with id, SDK id, status, format, published version and unpublished changes (get_surveys is an alias)
get_surveyOne survey's draft (or published) definition, page settings and in-app targeting
create_surveyNew survey from a definition; always an unpublished draft
update_surveyReplace a survey's draft definition; on a live survey it saves the next draft version
validate_surveyServer validation of a definition or the stored draft, without saving
publish_surveyLaunch: publish the draft as the next version; goLive: true also shows it in the app
pause_surveyStop showing a survey in the app (page and emails keep working)
get_survey_resultsTotals, NPS, per-question counts, drop-off, endings and paths from stored counters, plus the step funnel when analytics events exist
get_survey_analyticsEvent analytics with previous-period deltas: views, starts, submissions, rates, step funnel with drop-off, worst step, timing, score, versions, device/channel breakdowns, busiest times, reminders, email, quality
get_survey_insightsStored AI themes, drivers, segments and alerts
ask_survey_resultsPlain-language question about the responses → answer with cited response ids (AI, billed)
get_survey_responsesCompact response rows with filters (status, answer by key, theme, channel, contact, text) and cursor pagination
get_survey_responseOne response with labelled answers, path, ending and contact
search_survey_responsesKeyword search over the answers of every survey (or one), with snippet, NPS and contact per hit
reach_out_to_respondentDraft (default) or, with send: true, start a conversation linked to a response
get_survey_summaryStored AI summary of a survey's responses (legacy)

Error results set isError: true. Reads retry transient API failures (5xx, 429, network errors) twice with backoff, within a 20-second budget. Writes retry only when the request never reached the API (connection refused, DNS failure); calls that pass idempotent: true (feature-request create and subscribe) also retry 502-504. Other writes such as send_message are never repeated.

Prompts and MCP Apps view

  • Prompts fix_ticket and answer_ticket (argument ticket: #number or id) start a ticket workflow with the workflow text and a ticket summary.
  • update_plan, wrap_up, share_screenshot and publish_artifact carry _meta.ui.resourceUri = "ui://gleap/kai-session": hosts that support MCP Apps render the result inline from structuredContent.view; every other client reads the text content.

Examples

Marketing drafts and human review

Use these tools after a human approves the content plan:

ToolOutcome
create_news_draftUnpublished news or changelog; defaults to CHANGELOG
update_news_draftRevise an unsent news/changelog draft
create_newsletter_draftUnpublished fixed, one-time email campaign
update_newsletter_draftRevise an unsent newsletter draft
get_newsletter_draftsPaginated summaries of fixed, one-time email drafts
get_newsletter_draftFull newsletter draft content and review link
create_emailUnpublished email of any kind: newsletter, automated or kai (Kai-written)
update_emailRevise any unsent draft email (content, look, Kai-written config), or the content and look of a live/paused automated email in place (queued sends keep going with the new content)
get_emailAny email's content, kind, look, Kai-written config and review link

Creation requires name, subject (locale-to-string map), and message (locale-to-TipTap-document map). Do not wrap inputs in localized; the tools apply the backend's storage format. sender is optional; review it in Gleap. News creation also accepts subType: "NEWS" or "CHANGELOG". Updates take draftId and the content fields being changed. Use existing get_news / get_news_item to find and read news drafts.

Email kinds and looks

Gleap has three kinds of email. The kind is derived from the stored email, not stored itself:

KindStored asDefault lookTracking
newsletter: written once, sent once to an audiencefrequencyType: "fixed"companyon
automated: written once, sent per contact on an event trigger (+ delay)frequencyType: "dynamic"personalon
kai (Kai-written): Kai writes one email per recipient, teammates review the first oneskai.enabled: true, fixed or dynamicplainoff

emailStyle is the look: plain looks like a message typed in Gmail (no layout, no tracking pixel; best for personal notes, check-ins and Kai-written emails), personal is a clean white page signed by the sender with a photo card (onboarding, lifecycle), company has the logo header, a content card and a footer with links and postal address (newsletters, product updates), and custom renders one of the project's HTML templates (emailTemplate). Passing emailTemplate alone selects custom; custom needs a template of the project's, and emailTemplate with another look is refused. A new email is saved with an explicit emailStyle and no template; the tools no longer fall back to "the first template" (new projects have no Personal/Plain/Company templates). Emails stored without emailStyle keep rendering as before (custom with a template, otherwise personal).

preheader (locale → string) is the inbox preview text; plain ignores it. tracking: { opens, links } defaults off for plain and on for the other looks. An update that changes the look without passing tracking moves tracking that is still at the old look's default to the new look's default, and keeps tracking somebody set on purpose.

create_email takes kind, name, the content and look fields, and for kind: "kai" a kai object (prompt required) plus optional delivery: "one_off" | "triggered" (default triggered). Kai-written defaults: sources contact, company, events, tickets, helpcenter, website, rules { maxWords: 120, linkAllowlist: [], forbidden: [] }, review { mode: "firstN", n: 20 }, onNothingToSay: "skip", caps { perDay: 500, costPerDayUsd: 25 }. Subject and message are required for newsletter and automated emails; for a Kai-written email they are the fallback email and required only with onNothingToSay: "fallback". update_email merges kai into the stored config (kai.enabled: false turns it back into an email written once). The MCP never sets review mode none (send without any review): that stays a dashboard decision, and publish_email refuses a Kai-written email whose review is off or that has no instructions. Kai writes nothing until the email is live; set trigger and audience with configure_email_automation as for any email.

create_newsletter_draft / update_newsletter_draft keep working for fixed one-off newsletters and accept the same emailStyle, emailTemplate, preheader and tracking fields. update_newsletter_draft with only draftId is now refused (there is no template to repair).

Every new draft write explicitly sends status: "draft". The draft tools provide no publication, scheduling, audience, or send controls; for emails those are the lifecycle email tools below. News draft creation disables push and subscriber email settings. Newsletter creation uses the dashboard's fixed/once email shape, with no trigger; create_email with automated or kai saves a dynamic email without a trigger. Successful creation and revision return the saved record plus reviewUrl and a review instruction.

The intended workflow is: approve plan → create/revise draft → open reviewUrl → approve completed content → choose sender, audience, delivery settings and publish/send in the Gleap dashboard. Plan approval is not publication approval. The MCP does not implement a human approval authority or Slack integration. Tool descriptions guide the agent; the host/operator must enforce approvals.

Revision checks the current record's type, draft status, and send history before writing, and refuses live, paused, or previously sent records. It preserves omitted content and delivery fields. The backend does not provide a conditional draft update: this read-before-write check is not a transaction or version lock. Avoid concurrent dashboard publication and agent revision of the same draft. Use a new draft for changes to published content. After an ambiguous write error, inspect existing drafts before retrying creation to avoid duplicates.

Lifecycle emails: trigger, audience, publish

Turn an email (e.g. a newsletter draft) into an event-triggered email and set it live, without the dashboard:

ToolOutcome
get_email_automationAn email's status, kind, look, Kai-written config, trigger, frequency, targetAudience and conditions, plus reviewUrl
configure_email_automationSet a non-live email's event trigger, frequency, audience and/or dropIfConditionsFail. Never publishes
publish_emailSet the email live
pause_emailTake a live email off (the dashboard's Unpublish: status back to draft). Every queued pending send is deleted and never re-created on publish; do not pause just to edit content

configure_email_automation takes emailId plus any of:

  • trigger: { event, type?, delaySeconds }: a streamed event name; type is firstoccured or lastoccured (default firstoccured for once, lastoccured otherwise); the delay is 0 to 365 days in seconds. Stored as the dashboard stores it, { event, type, dateOperator: "relative", matchOperator: "greaterthan", data: <delaySeconds>, ti }, and switches the email to frequencyType: "dynamic". Contact attributes (gleap-up-*, tags) and pageView are refused as triggers: they match every existing contact at once or need page rules.
  • frequency: { mode: "once" } (frequency: "once"), { mode: "every_time" } ("continuously"), or { mode: "every_n_days", days } ("continuously", frequencyDays: days).
  • audience: { targetAudience?, logicalOperator?, conditions? }: targetAudience is all, users or guests; conditions replaces all rules (AND by default) and is checked when the email is due, so it doubles as stop conditions. Shapes, as stored:
    • event count: { event, type: "count", matchOperator: "is", data: 0 }
    • current page: { event: "pageView", type: "latestdata", dataKey: "page", matchOperator, data }. Custom events keep no other data, so any other dataKey is refused: put the value on the contact instead
    • contact attribute: { event: "gleap-up-<attribute>", type: "latestdata", matchOperator, data }, e.g. exclude your team with { event: "gleap-up-email", type: "latestdata", matchOperator: "notcontains", data: "gleap.io" }
    • event date: { event, type: "firstoccured" | "lastoccured", dateOperator: "relative", matchOperator: "greaterthan" | "lessthan" | "exactly", data: <seconds> }
  • dropIfConditionsFail: boolean ("Skip if conditions no longer match" in the dashboard): when the email is due and its audience conditions fail, the send is dropped instead of waiting for them to match (by default it stays pending and may go out up to 30 days later). For sequences keyed on state that moves on, e.g. onboarding step emails conditioned on gleap-up-customData.onboardingGoal. It is a sending policy, not targeting: the only setting the tool also changes on a live email.

Every write goes through PUT /engagement/emails/:id, the route the dashboard saves and publishes with, so the API applies the same project scoping, role permission (engagement.email.update: admins and members, not viewers), plan gate, live-edit lock and publish checks. The tools add their own guards:

  • configure_email_automation refuses a live email (pause it first; a call that only sets dropIfConditionsFail is the exception) and an email that sends to an uploaded CSV list, and never sends status.
  • publish_email publishes an email only when it is triggered by a streamed event and has no unfinished audience rule. A sessionStarted trigger, which every contact fires, also needs at least one audience condition.
  • A one-off email (no trigger: it goes to everyone who matches at once and cannot be recalled) is refused unless the call passes oneOffAudience equal to the email's stored targetAudience, which must be users or guests (never all) with at least one audience condition. CSV-list sends stay in the dashboard.
  • A Kai-written email is published only with instructions (kai.prompt), at least one source, fallback content when onNothingToSay is fallback, and review all or firstN. Once live, the emails held for review wait in the email's Review tab in the dashboard.
  • publish_email / pause_email on an email already in that state change nothing; an already-sent one-off cannot be paused.
  • pause_email deletes every queued pending send (contacts waiting out a trigger delay); publishing again does not re-create them. To fix content of a live automated email, use update_email instead: it writes only the content fields passed (never status, trigger, audience or frequency), the email stays live and queued sends go out with the new content. It refuses kai changes on a published email and any edit of a sent one-off.

Each tool returns the email's resulting status, trigger, frequency, audience and reviewUrl, and reports an error when the saved email does not show the requested change. Finish content with the newsletter draft tools before configuring: update_newsletter_draft edits only fixed, one-time drafts. Publishing needs the operator's approval; the tool descriptions say so, the host must enforce it. Customer-scoped runs cannot use these tools.

Sequences: build, check, go live, enroll

Sequences (Outreach › Sequences) walk enrolled contacts through emails, chat messages, waits, "wait until they do X" with did/didn't paths, if/else branches and actions (tag, attribute, pipeline, another sequence, end) until they finish, reply, convert (goal) or hit an exit rule. The tools call the dashboard's routes (/v3/sequences), so permissions (engagement.email.*), the plan gate and the go-live validation run on the Server; its 400 messages reach the agent verbatim.

Typical flow: get_targeting_options (real event and attribute names) → create_sequence (template and/or definition; steps as JSON, email content as plain text with {{session.firstName|there}} variables) → preview_sequence (every message rendered for a contact, missing variables listed) → send_sequence_test_email → set_sequence_status live after the operator approves → enroll_in_sequence for manual enrolling. Edits to a live or paused sequence are saved as unpublished changes until publish_sequence_changes.

The tools check a definition before writing (unique step ids, known step types, wait units and limits, condition rules) and merge partial settings onto the current ones, since the Server replaces each settings object whole. Customer-scoped runs cannot use these tools.

Outbound messages: draft, target, preview, publish

Every outbound type works through the same tools: survey, chat_message, banner, modal (info card), checklist, product_tour, tooltip, news, email, push, whatsapp.

ToolOutcome
get_targeting_optionsThe project's events (triggers / event rules) and contact attributes (audience rules) plus the condition syntax; search narrows it and says when nothing matches
get_event_tracking_guideThe SDK and backend code to start tracking a missing event or contact attribute, and whether it is already tracked
list_outbound_messages / get_outbound_messageItems of one type; one item's content (survey questions included), targeting, reviewUrl and optional stats
create_outbound_draftUnpublished survey, chat message, banner, info card, checklist, push, product tour or tooltip set, in the shape the dashboard editor writes (emails and news: the draft tools above)
update_outbound_contentRevise a non-live item's content; lists (questions, steps, tooltips) are replaced whole
configure_outbound_targetingDelivery (triggered / one-off), trigger + delay, frequency, page rules, audience (incl. one level of rule groups) and schedule of a non-live item
preview_outbound_audienceWho the rules match now, with a few sample contacts; nothing is saved
publish_outbound / pause_outboundGo live / take off through the dashboard's publish path

Guards: an item without content, sender (banners, chat messages, news), steps or a trigger is not published (it would show nothing); triggers on contact attributes are refused (use audience rules); one-offs and news with push need confirmedReach, the recipient count from preview_outbound_audience the operator approved, and are refused if the audience grew beyond it; one-off emails, push and WhatsApp never go to everyone without rules; live items must be paused before their targeting or content changes, and sent one-offs cannot be paused. Tools outside the customer-session allowlist are refused in customer-scoped runs.

Surveys 2.0: drafts, validation and publishing

Agents build surveys from one JSON definition (the same one the dashboard editor, the API and Kai use): blocks (questions with a stable id, a snake_case answer key, a type, title, options and logic jumps), endings and hidden fields. Jumps are { if: condition, go: <later block or ending id> }, checked top to bottom; otherwise next, otherwise the next block. The tool descriptions carry the full format and an NPS example (0–6 / 7–8 / 9–10 to three follow-ups).

  • create_survey and update_survey write drafts only: they always send status: "draft" (create) or only { definition } to PUT /engagement/surveys/:id/draft (update), never a status, the published definition or targeting on update. On a live survey the live version keeps running until the draft is published.
  • Definitions are checked before anything is written: unknown properties, duplicate ids/keys, jump targets that do not exist or go backwards, conditions that do not fit the question type (choice ids, not labels; NPS ranges inside 0–10), missing choices, unknown hidden fields. The Server's validator (reachability, limits) then runs on the saved draft and its result comes back as validation.
  • publish_survey calls POST /engagement/surveys/:id/publish (with { goLive: true } it also switches the in-app survey on). Agents publish like teammates; the tool description has them launch only once the operator agreed, the same rule as publish_outbound. Invalid drafts come back with the validator's errors (422). A Server that still answers "needs approval" (403 or requiresApproval: true) comes back as { published: false, requiresApproval: true, reviewUrl }.
  • Contact questions: an email question, or a short question with contactField: "name" | "phone". With skipWhenKnown (unset = on) an identified contact whose value is known is not asked and the Server fills the answer in; false always asks. contactField on other types and skipWhenKnown: true on other questions are rejected before writing. Responses list those answer keys as prefilled. A Server without these fields drops them on save; create_survey / update_survey then return a contactSettingsNote.
  • reach_out_to_respondent sends nothing unless send: true; the default returns the draft message and recipient for the operator to approve.
  • Results tools return compact JSON: capped lists, clipped text, cursor pagination for responses. Stats and insights are read from stored data; only ask_survey_results runs AI.

Customer-scoped runs cannot use any survey tool.

Images: covers and inline images

  1. Get the image onto Gleap's CDN. A file on disk (e.g. a generated cover): create_image_upload_link, then run the returned curl -sS -F "file=@cover.png" "<uploadUrl>" — the JSON response carries fileUrl. The link works once and expires after 15 minutes. Small base64 data or a public URL: upload_image (data or url) returns fileUrl. PNG, JPEG, GIF and WebP only, judged by the bytes; base64 up to 5 MB, links up to 20 MB. Everything is stored in the connected project's upload folder through the Gleap API with your credentials; the MCP server itself never fetches a URL (the API does, behind its SSRF guard).

  2. News/changelog cover: pass coverImageUrl to create_news_draft or update_news_draft (null removes it). A URL that is not on Gleap's file hosts is copied onto the CDN first, so published content never hotlinks a third-party host. The draft-only rules above still apply. create_news / update_news accept the same field. Help center articles and newsletters have no cover image.

  3. Inline images (news, newsletters, help center articles): add a top-level block node next to the paragraphs — never inside one:

    { "type": "imageBlock", "attrs": { "src": "<fileUrl>", "width": "100%", "align": "center", "alt": "What the image shows" } }
    

    width is a percentage string (pixel widths such as "540px" in existing content are accepted), align is left, center or right; optional link + target: "_blank" make the image clickable. This is the node the dashboard editors insert, and the widget and help center render it the same way. The legacy { "type": "image", "attrs": { "src" } } still renders. Writes are refused (nothing saved) when an image node has no src, a data: URI, a non-http(s) src, or sits inside a paragraph.

Customer-scoped runs cannot upload images or create upload links.

The legacy create_news now explicitly sends draft status (matching the existing backend default). Legacy update_news still edits the specified item, including live items; marketing agents should use update_news_draft for this workflow. Customer-scoped runs cannot access the new marketing draft tools.

Run npm test for the mocked API regression tests; they run on the TypeScript sources, without a build. Tests do not connect to a live project or send messages. Deploy the updated MCP server and refresh the client's tool discovery before using the new tools.

Example 1: Triage unassigned tickets

Prompt: "Show me all open high-priority tickets that haven't been assigned to anyone"

What happens:

  • Claude calls find_tickets with status: "OPEN" and priority: "HIGH" (the filter takes priority keys or names; custom priorities have p_… keys listed by get_ticket_types)
  • Filters the results to surface unassigned tickets
  • Returns a ranked list with ticket IDs, titles, and creation dates so you can start triaging immediately

Example 2: Look up a customer and their history

Prompt: "Find the contact for sarah@acme.com and show me her recent support tickets"

What happens:

  • Claude calls search_contacts with the email address
  • Retrieves the contact record including name, company, and custom attributes
  • Calls find_tickets filtered by the contact's session ID
  • Summarizes the contact profile and ticket history in one response

Example 3: Create a ticket from a conversation

Prompt: "Create a high-priority bug report titled 'Payment fails on checkout for EU customers'"

What happens:

  • Claude calls get_ticket_types to find the right ticket type, its required fields and its priorities
  • Calls create_ticket with the type, title, and priority (a key such as HIGH or a priority title such as "Urgent"; built-in keys are LOW, MEDIUM, HIGH)
  • Returns the new ticket ID and a direct link to it in Gleap

Example 4: Browse and navigate the help center

Prompt: "What help center collections do we have, and which articles are in the 'Getting Started' collection?"

What happens:

  • Claude calls get_help_center_collections_tree to get the full structure
  • Identifies the matching collection and calls get_help_center_articles
  • Returns a structured list of all articles with their titles and IDs

Example 5: Write a new help center article

Prompt: "Create a help center article explaining how to reset a password. Write it in English and German."

What happens:

  • Claude asks which collection to add it to (or uses get_help_center_collections to list options)
  • Drafts localized title, description, and body content in TipTap JSON format for both locales
  • Calls create_help_center_article with isDraft: true so you can review before publishing

Example 6: Check support performance

Prompt: "What was our average first response time last month, and how does it compare to the month before?"

What happens:

  • Claude calls get_statistics_facts with chartType: "avgFirstResponseTime" for each date range
  • Compares the two values and calculates the percentage change
  • Presents a concise summary with the trend direction

Example 7: Update an existing help center article

Prompt: "Update our 'Getting Started' article to mention the new dark mode feature"

What happens:

  • Claude calls get_help_center_collections_tree to find the article
  • Retrieves the current article content with get_help_center_article
  • Appends the new section while preserving existing content
  • Calls update_help_center_article with the revised TipTap document
  • For large multi-language articles, Claude updates one locale per call (e.g. content: { "de": ... }); untouched locales keep their current content

Configuration

VariableDefaultDescription
GLEAP_API_BASE(required)Gleap REST API base URL, e.g. https://api.gleap.io/v3
GLEAP_AUTH_ISSUERhttps://api.gleap.ioOAuth issuer URL
GLEAP_JWKS_URI{GLEAP_AUTH_ISSUER}/.well-known/jwks.jsonJWKS endpoint for token verification
MCP_SERVER_URLhttp://localhost:{PORT}/mcpPublic URL of this server (used as OAuth audience)
MCP_SERVER_URL_ALIASES(none)Other public URLs this server answers on, comma-separated (e.g. the legacy https://mcp.gleap.io/mcp). Each host serves its own OAuth metadata, and tokens for any of them are accepted.
PORT3000HTTP port
MCP_JSON_BODY_LIMIT10mbMaximum JSON body size accepted on the MCP endpoint (body-parser size string). Large multi-locale help center article updates need more than body-parser's 100 KB default.
OPENAI_APPS_CHALLENGE_TOKEN(current token)Token served at /.well-known/openai-apps-challenge so OpenAI can verify domain ownership for the ChatGPT plugin directory. Override only when OpenAI issues a new token.

Support

No installation packages available.

Remote