appmate-mcp

Model Context Protocol server for AppMate — lets Claude Desktop, Claude Code, Cursor, Codex, or any other MCP-aware client drive AppMate via typed tools. List apps, edit cancel flows, publish, export waitlists — without leaving the chat.

npx -y @fil-technology/appmate-mcp

Setup (1 minute)

1. Issue a token at https://flow.appmate.cloud/admin/api-tokens. Copy the amk_… string — it's only shown once.
2. Add the server to your MCP host's config (examples below).
3. Restart the host and ask your agent: "list my appmate apps".

Claude Desktop / Claude Code

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (on macOS) or the equivalent on your platform:

{
  "mcpServers": {
    "appmate": {
      "command": "npx",
      "args": ["-y", "@fil-technology/appmate-mcp"],
      "env": {
        "APPMATE_TOKEN": "amk_…",
        "APPMATE_API_URL": "https://flow.appmate.cloud"
      }
    }
  }
}

Cursor / Codex (.mcp.json in your project)

{
  "mcpServers": {
    "appmate": {
      "command": "npx",
      "args": ["-y", "@fil-technology/appmate-mcp"],
      "env": { "APPMATE_TOKEN": "amk_…" }
    }
  }
}

APPMATE_API_URL defaults to https://flow.appmate.cloud. Override for staging or self-hosted instances.

Tools

| Tool | Purpose | | --- | --- | | list_apps | List every app the token can see. | | get_app | Fetch one app by id or slug. | | create_app | Create a new app. | | get_qr_code | Shareable QR-code image URLs (PNG + SVG) for any flow's public page, logo centred. | | list_flows | List an app's flows. cancel, waitlist + app_promotion can have multiple per app (a promotion per placement); others are one each. | | get_cancel_flow | Read published + draft cancel config (flowSlug → a secondary flow). | | update_cancel_draft | Replace the draft with new config JSON. | | publish_cancel_flow | Promote the draft live. | | get_waitlist_flow | Read published + draft waitlist config (flowSlug → a secondary waitlist). | | update_waitlist_draft | Replace the waitlist draft. | | publish_waitlist_flow | Promote the waitlist draft live. | | list_waitlist_signups | Paginated list (cursor + nextCursor). | | export_waitlist_csv | Return the full waitlist as a CSV string. | | get_feedback_flow | Read published + draft feedback config. | | update_feedback_draft | Replace the feedback draft. | | publish_feedback_flow | Promote the feedback draft live. | | list_feedback_submissions | Paginated list of feedback rows (rating + message + email). | | get_report_flow | Read published + draft report config. | | update_report_draft | Replace the report draft (categorised). | | publish_report_flow | Promote the report draft live. | | list_report_submissions | Paginated, optional category filter. | | get_crash_flow | Read published + draft crash flow config. | | update_crash_draft | Replace the crash draft (message + optional log/email fields). | | publish_crash_flow | Promote the crash draft live. | | list_crash_submissions | Paginated crash reports incl. diagnostics + text-log attachments; optional status filter. | | set_crash_report_status | Triage a crash report: new → reviewed → resolved. | | get_contact_flow | Read published + draft contact config. | | update_contact_draft | Replace the contact draft. | | publish_contact_flow | Promote the contact draft live. | | list_contact_submissions | Paginated list of contact rows (name + email + message). | | reply_to_contact_submission | Send a branded email reply to a contact submission (Reply-To = the app's support email / account email). Counts against the email quota. | | reply_to_report_submission | Send a branded email reply to a report submission (bug/abuse/spam). Same send path + quota as the contact reply. | | get_onboarding_flow | Read published + draft onboarding (web-to-app funnel) config. | | update_onboarding_draft | Replace the onboarding draft (quiz / info / email-capture steps + handoff). | | publish_onboarding_flow | Promote the onboarding draft live. | | list_onboarding_submissions | Paginated list of funnel completions (answers + email + claim status). | | export_onboarding_csv | Return all onboarding completions as a CSV string. | | get_referral_flow | Read published + draft referral program config. | | update_referral_draft | Replace the referral draft (rewards, share text, cap, landing). | | publish_referral_flow | Promote the referral draft live. | | list_referrals | Paginated referral graph (status, source [link or typed-code], referee, reward flags). | | export_referrals_csv | Return the full referral graph as a CSV string. | | get_link_page_flow | Read published + draft link-page (link-in-bio) config. | | update_link_page_draft | Replace the link-page draft (header, icon links, link list, theme). | | publish_link_page_flow | Promote the link-page draft live (appmate.cloud/p/{appSlug}). | | get_legal_flow | Read published + draft privacy-policy/terms config + public URLs. | | update_legal_draft | Replace the legal draft — structured facts (entity, processors, declarations, platform capabilities). Returns warnings. NOT legal advice. | | publish_legal_flow | Publish; stamps today's date, freezes the version, returns { privacy, terms } URLs. | | get_app_store_privacy_declaration | Derive the App Store "App Privacy" answers from the config; each entry names the processor that caused it. | | get_app_promotion_flow | Read published + draft cross-app promotion config (flowSlug → a specific placement). | | update_app_promotion_draft | Replace the promotion draft — which of your other apps to promote (single or rotating), presentation, installed/not-installed/deferred actions, targeting, frequency. | | publish_app_promotion_flow | Promote the promotion draft live (SDK present(placement) resolves it). | | list_short_links | Paginated list of the app's short links (code, shortUrl, destinations, state, clickCount). | | get_short_link | One link + click stats: real clicks, byTarget (ios/android/fallback/expired), topCountries, botClicks. | | create_short_link | Create a short link. Only url (the fallback) is required; code is optional and immutable after. | | update_short_link | Partial update — pass null to clear a field, resetClicks: true to zero the counter. | | delete_short_link | Permanently delete a link and its clicks (prefer status: 'disabled'). |

Short links live at go.appmate.cloud/{code} and need no publish step — they redirect the moment they exist. url is the fallback destination (always required); iosUrl / androidUrl are optional per-platform overrides. A link can expire by date (expiresAt), by click budget (maxClicks), both, or neither. Link-preview fetchers (Slack, WhatsApp, iMessage…) are recorded as botClicks — never counted as real clicks and never charged against the click limit.

Each referrer gets a unique link and a short, human-readable code (e.g. K7Q4-R9XP); a friend redeems by tapping the link or typing the code (no clipboard needed). source on each referral row records which path was used.

Cross-app promotions let a source app promote your other apps (single or rotating) at a named placement, shown via Apple's StoreKit in the iOS SDK (RetentionFlow.promotions.present("placement")). Destinations are referenced by their AppMate app id — their App Store id / universal-link base / named deep-link destinations live on the destination App itself, so you don't re-enter them. One promotion flow per placement (pass flowSlug).

Tools that accept an app reference (get_app, update_cancel_draft, etc.) accept either the cuid id or the human-readable slug — use whichever you have. The full REST shape is documented at https://docs.appmate.cloud/api-reference.

Example agent prompts

"Create an AppMate app called Ledgr with bundle id com.acme.ledgr, then publish a simple cancel flow that offers a 20% discount for the too_expensive reason."

"Export the waitlist for appmate-pro as CSV and save it to ~/Downloads/waitlist.csv."

"Build a 3-question onboarding funnel for ledgr that asks the user's goal, captures their email, and hands off to the App Store, then publish it."

"Compare the published and draft cancel configs for quakemate and tell me what changed."

Local development

pnpm install
pnpm dev    # tsx src/index.ts — talks MCP over stdio
pnpm build  # emits dist/index.js

Security

• Tokens are bcrypt-hashed server-side and only shown once on creation.
• Revoke from the dashboard the moment a token leaks.
• All calls go over TLS to flow.appmate.cloud. No data sits on disk in the MCP process beyond what your MCP host logs.

License

MIT. See LICENSE.