Skip to main content
Glama
Gleap

Gleap

Official
by GleapSDK

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)

Related MCP server: concierge-mcp

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.

  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:

Header

Value

x-gleap-api-key

Your Gleap API key

x-gleap-project-id

Your 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

Tool

Description

search_tickets

Full-text search across tickets

find_tickets

Filter tickets by status, priority, assignee, tags, date

get_ticket

Get a specific ticket by ID

create_ticket

Create a new ticket

get_ticket_types

List ticket types with their custom fields, status lanes and priorities

get_ticket_messages

Get the full conversation history (messages) for a ticket

get_ticket_activity_log

Get 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_message

Reply 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_composer

Stage 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_progress

Report 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_plan

Live checklist on the Gleap coding session (sessionId or ticketId, like report_progress): the whole list each call, statuses pending/in_progress/completed/cancelled

wrap_up

End-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_screenshot

Post 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_artifact

Publish a self-contained HTML page (≤ 1 MB) into the session thread; artifactId publishes a new version

get_agent_workflow

The Gleap ticket workflow (fix, answer, feature) as Markdown, plus the .gleap/session.json content for the Gleap plugin

get_ticket_screenshot

The ticket's SDK screenshot as image content (Gleap file hosts only, ≤ 2 MB)

describe_database

The 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_database

One 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_result

The 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_workflows

List 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_ticket

List the live workflows startable on a specific ticket

run_ticket_workflow

Manually start a workflow on a ticket (the "Start a workflow" action)

get_setup_status

Where 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_agents

The project's AI agents: name, live or draft, customer-facing or team

set_ai_mode

Removed (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_resolve

Removed (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_workflow

Change which channels a workflow runs on (addChannels / removeChannels) and whether it is live; never its steps

get_workflow_build_options

What a workflow can use, by name: teams, tags, Your API endpoints, webhooks, integrations, sequences, contact fields, message variables

get_workflow_steps

One workflow step by step, with path ids and step numbers, what could go live and the hashes publish_workflow_draft needs

create_workflow_draft

Build a new conversation workflow from steps; always a draft, no customer gets it

change_workflow_draft

Edit a workflow's name, trigger, channels, audience and steps; a change to a live workflow waits as a draft

publish_workflow_draft

Make 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_team

Create a team, rename it, add or remove members (others stay), change how it hands out tickets

set_default_team

The team agents escalate to when nobody else is named (admins)

search_contacts

Full-text search across contacts

get_contacts

Filter contacts by email, name, company

get_contact

Get a specific contact by ID

create_contact

Create a new contact

get_companies

List/search the project's companies (organisations)

get_company

Get a company by its external companyId, incl. custom data

update_company

Create or update a company (name, plan, value, custom data)

get_pipelines

List CRM pipelines with their stages

get_pipeline

Get a pipeline incl. stages and fields (fieldIds for entry values)

get_pipeline_stats

Per-stage counts and field aggregations (e.g. sum of deal values per stage) plus pipeline totals

get_pipeline_entries

List a pipeline's entries, optionally for one stage

get_pipeline_entry

Get one entry with its pipeline context

add_pipeline_entry

Add a company/contact to a pipeline (stage + initial values)

move_pipeline_entry

Move an entry to another stage

update_pipeline_entry_values

Update an entry's field values (merge; null clears)

remove_pipeline_entry

Remove an entry from a pipeline (record itself is untouched)

get_record_pipelines

Which pipelines a company/contact is on

get_help_center_sites

List 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_collections

List help center collections; optional site (default or a site id) lists one site's

get_help_center_collections_tree

Full tree of collections and subcollections (each carries its site)

get_help_center_articles

List articles in a collection

get_help_center_article

Get a specific article by ID

create_help_center_collection

Create a new collection; optional site for a top-level collection

move_help_center_collections_to_site

Move top-level collections (with sub-collections and articles) to another help center site

update_help_center_collection

Update an existing collection

upload_image

Store 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_link

Single-use, 15-minute link that uploads one image from disk (curl -F file=@cover.png <link>), for agents with a shell

create_help_center_article

Create a new article (TipTap JSON content)

update_help_center_article

Update an existing article. Partial per-locale updates: locales you send are changed, locales you omit are preserved

get_statistics_facts

Fact metrics: response times, ticket counts, SLA, AI stats

get_statistics_list

List metrics: top agents, top articles, team performance

get_statistics_bar_chart

Bar chart data: tickets over time, ratings, SLA

get_raw_data_statistics

Individual event rows behind the metrics, filtered by action type, agent, ticket

get_targeting_options

Events and contact attributes outbound messages can target, with the condition syntax

get_event_tracking_guide

Tracking code (SDKs + backend) for an event or contact attribute targeting needs but the project lacks

list_outbound_messages

List one outbound type: surveys, chat messages, banners, info cards, checklists, tours, tooltips, news, emails, push, WhatsApp

get_outbound_message

One outbound item: content, targeting, reviewUrl, optional stats

create_outbound_draft

Draft a survey, chat message, banner, info card, checklist, push, product tour or tooltip set

update_outbound_content

Revise a non-live outbound item's content

configure_outbound_targeting

Trigger, frequency, page rules, audience and schedule of a non-live outbound item

preview_outbound_audience

Count and sample who an audience matches; saves nothing

publish_outbound

Set an outbound item live after operator approval (one-offs: with the approved recipient count)

pause_outbound

Take a live outbound item off

list_sequences

Sequences (Outreach › Sequences) with status, how contacts are enrolled, goal, counts and reply/goal rates

get_sequence

One sequence: enrollment, exit, goal, sending, the step tree as an outline plus editable steps, unpublished changes and what blocks going live

get_sequence_templates

The starter templates (blank, onboarding, trial, reengage) and the full step/settings/condition/variable reference with a worked example

create_sequence

New draft sequence from a template and/or a full definition in one call

update_sequence

Change 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_changes

Make a live sequence's unpublished changes live, or drop them

set_sequence_status

Turn a sequence live or pause it (server validation messages returned verbatim)

enroll_in_sequence

Enroll 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_stats

Counts, reply and goal rates, exit reasons and per-step funnel

list_sequence_enrollments / get_sequence_enrollment

Contacts in a sequence (filter by status, search) and one contact's timeline

manage_sequence_enrollment

Pause, resume or exit one contact's run

preview_sequence

Render every message for a contact and list variables that resolve empty; sends nothing

send_sequence_test_email

Send one email step as a test to yourself or up to 5 addresses

search_feature_requests

Semantic dedupe search over feature requests: up to 5 matches with rerank scores, including requests not on the public roadmap yet (public: false)

get_feature_request

Read one feature request by id or ticket number: title, description excerpt, status, upvote count, share link (never voter identities)

subscribe_to_feature_request

Idempotently add a customer as upvoter; returns the request's status and share link

create_feature_request

File 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_surveys

Surveys with id, SDK id, status, format, published version and unpublished changes (get_surveys is an alias)

get_survey

One survey's draft (or published) definition, page settings and in-app targeting

create_survey

New survey from a definition; always an unpublished draft

update_survey

Replace a survey's draft definition; on a live survey it saves the next draft version

validate_survey

Server validation of a definition or the stored draft, without saving

publish_survey

Launch: publish the draft as the next version; goLive: true also shows it in the app

pause_survey

Stop showing a survey in the app (page and emails keep working)

get_survey_results

Totals, NPS, per-question counts, drop-off, endings and paths from stored counters, plus the step funnel when analytics events exist

get_survey_analytics

Event 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_insights

Stored AI themes, drivers, segments and alerts

ask_survey_results

Plain-language question about the responses → answer with cited response ids (AI, billed)

get_survey_responses

Compact response rows with filters (status, answer by key, theme, channel, contact, text) and cursor pagination

get_survey_response

One response with labelled answers, path, ending and contact

search_survey_responses

Keyword search over the answers of every survey (or one), with snippet, NPS and contact per hit

reach_out_to_respondent

Draft (default) or, with send: true, start a conversation linked to a response

get_survey_summary

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

Tool

Outcome

create_news_draft

Unpublished news or changelog; defaults to CHANGELOG

update_news_draft

Revise an unsent news/changelog draft

create_newsletter_draft

Unpublished fixed, one-time email campaign

update_newsletter_draft

Revise an unsent newsletter draft

get_newsletter_drafts

Paginated summaries of fixed, one-time email drafts

get_newsletter_draft

Full newsletter draft content and review link

create_email

Unpublished email of any kind: newsletter, automated or kai (Kai-written)

update_email

Revise 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_email

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

Kind

Stored as

Default look

Tracking

newsletter: written once, sent once to an audience

frequencyType: "fixed"

company

on

automated: written once, sent per contact on an event trigger (+ delay)

frequencyType: "dynamic"

personal

on

kai (Kai-written): Kai writes one email per recipient, teammates review the first ones

kai.enabled: true, fixed or dynamic

plain

off

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:

Tool

Outcome

get_email_automation

An email's status, kind, look, Kai-written config, trigger, frequency, targetAudience and conditions, plus reviewUrl

configure_email_automation

Set a non-live email's event trigger, frequency, audience and/or dropIfConditionsFail. Never publishes

publish_email

Set the email live

pause_email

Take 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.

Tool

Outcome

get_targeting_options

The 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_guide

The SDK and backend code to start tracking a missing event or contact attribute, and whether it is already tracked

list_outbound_messages / get_outbound_message

Items of one type; one item's content (survey questions included), targeting, reviewUrl and optional stats

create_outbound_draft

Unpublished 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_content

Revise a non-live item's content; lists (questions, steps, tooltips) are replaced whole

configure_outbound_targeting

Delivery (triggered / one-off), trigger + delay, frequency, page rules, audience (incl. one level of rule groups) and schedule of a non-live item

preview_outbound_audience

Who the rules match now, with a few sample contacts; nothing is saved

publish_outbound / pause_outbound

Go 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

Variable

Default

Description

GLEAP_API_BASE

(required)

Gleap REST API base URL, e.g. https://api.gleap.io/v3

GLEAP_AUTH_ISSUER

https://api.gleap.io

OAuth issuer URL

GLEAP_JWKS_URI

{GLEAP_AUTH_ISSUER}/.well-known/jwks.json

JWKS endpoint for token verification

MCP_SERVER_URL

http://localhost:{PORT}/mcp

Public 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.

PORT

3000

HTTP port

MCP_JSON_BODY_LIMIT

10mb

Maximum 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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers