@freeticket/mcp

FreeTicket's official MCP (Model Context Protocol) server. It exposes the B2B domain — events, dates, sales, tickets, memberships, venues, staff, reports — as tools to any MCP client (Claude Code, Claude Desktop, claude.ai).

Same contract and same session as the ft CLI: if you have run ft login, the MCP is already authenticated with nothing to configure (it reads ~/.freeticket/config.json).

Install as a Claude plugin

The repo is a Claude Code plugin and its own marketplace. The plugin wires the remote server (https://mcp.appfreeticket.com/mcp, declared in .mcp.json) and ships four skills.

/plugin marketplace add AppFreeticket/freeticket-mcp
/plugin install freeticket@freeticket

Or in one step (Claude Code 2.1.275+): /plugin install freeticket --marketplace AppFreeticket/freeticket-mcp.

Authentication is OAuth — the same embedded authorization server claude.ai uses (see below): Claude Code discovers it from the 401 + WWW-Authenticate (RFC 9728) and registers itself (RFC 7591). Run /mcp, pick freeticket, and sign in with your FreeTicket account in the browser. No API key or header goes in the plugin.

Files: .claude-plugin/plugin.json (version kept equal to package.json by src/plugin.test.ts), .claude-plugin/marketplace.json (plugin source: "./", the repo root), .mcp.json and skills/. Check them with claude plugin validate .. None of them is published to npm (files is dist only).

Local stdio instead of the remote server (CI, headless, or a pinned build): add it yourself rather than through the plugin —

claude mcp add --env FT_API_KEY=ft_live_... --transport stdio freeticket \
  -- npx -y @freeticket/mcp

(subject to the npm caveat below). If you also keep the plugin enabled, toggle its freeticket server off in /mcp so the tools are not listed twice.

Related MCP server: thinker-mcp

Use (Claude Code / Claude Desktop)

{
  "mcpServers": {
    "freeticket": {
      "command": "npx",
      "args": ["-y", "@freeticket/mcp"]
      // No env: uses the `ft login` session. For CI or headless:
      // "env": { "FT_API_KEY": "ft_live_...", "FT_WORKSPACE_ID": "ws_..." }
    }
  }
}

⚠️ @freeticket/mcp is not published on npm yet, so this stdio entry does not work today — npx cannot resolve the package. Use the remote server below until it ships.

Config precedence: env > ~/.freeticket/config.json > default. Variables: FT_API_URL (base, without /api/v1), FT_API_KEY, FT_WORKSPACE_ID, FT_ADMIN_SESSION (enables the admin_* tools of the superadmin contract /api/admin).

Remote use over URL (HTTP)

Beyond stdio, the server runs over Streamable HTTP so it can be added as a connector by URL (claude.ai, remote Claude Code, curl) with nothing installed locally. It is live at https://mcp.appfreeticket.com/mcp.

freeticket-mcp-http          # listens on :3333 (PORT to change it)

It is stateless: every request carries its own credentials and the server builds per-session isolated clients (it never reads disk), so one process serves many workspaces without crossing sessions. Endpoints:

Connecting from claude.ai (Add custom connector)

The server ships an embedded OAuth 2.1 authorization server — that is the only thing claude.ai knows how to speak (it cannot send API keys or custom headers). Steps:

1. claude.ai → Settings → Connectors → Add custom connector.

2. Remote MCP server URL: https://mcp.appfreeticket.com/mcp. Client ID and Secret: leave empty (it uses dynamic client registration, RFC 7591).

3. Connecting opens the consent page: the "Continue with FreeTicket" button signs you into free-admin with your usual account and asks for approval (device flow, RFC 8628 — the same backend as ft login). No keys to paste, and no workspace to pick: the connection reaches every workspace your account does. Under "Advanced options" there is still the manual form (an API key for CI, the superadmin cookie for the admin_* tools, and a workspace field if you want this connection tied to a single tenant).

4. Credentials are sealed (AES-256-GCM, MCP_TOKEN_SECRET) inside the issued token — the server persists nothing: no database, multi-tenant safe.

The full standard flow: RFC 9728/8414 discovery → /register → /authorize (PKCE S256) → /token (with refresh). FT_OAUTH_ISSUER delegates all of it to an external AS (for instance, once free-admin publishes its own).

Direct auth (curl, your own clients)

curl -X POST http://localhost:3333/mcp \
  -H 'authorization: Bearer ft_live_...' \      # raw API key
  -H 'x-workspace-id: ws_...' \                 # optional — pins it to one workspace
  -H 'x-admin-session: <cookie>' \              # optional — enables admin_*
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Deploying on Vercel

The repo already carries vercel.json + api/server.ts (the same logic as the binary, as a Vercel Function):

vercel                                        # preview
vercel env add MCP_TOKEN_SECRET production    # openssl rand -hex 32
vercel --prod

Env on Vercel: MCP_TOKEN_SECRET (required — without it tokens die on every cold start), FT_API_URL (optional, defaults to production), MCP_PUBLIC_URL (optional — derived from the Host header). The resulting connector URL is https://<project>.vercel.app/mcp.

Domain verification (OpenAI plugin directory)

The submission portal issues a token and fetches it back as plain text from /.well-known/openai-apps-challenge. The server hands back whatever is in OPENAI_APPS_CHALLENGE, trimmed:

vercel env add OPENAI_APPS_CHALLENGE production   # paste the portal's token
vercel --prod
curl https://mcp.appfreeticket.com/.well-known/openai-apps-challenge

The token belongs to the deployment, not to the repo — a committed one is a verification anybody can serve from a fork. Unset, the path answers 404 and names the variable rather than inventing a value that would pass and prove nothing.

Tools

B2B /api/v1 (one tool = one contract operation). Destructive writes (*_delete, *_refund, *_cancel, and every operation the contract flags x-ft-destructive, such as sales_abandon, event_dates_access_close_sign, content_channels_archive or content_members_ban) carry destructiveHint and ask for confirmation.

Minting and revoking credentials (ft api-keys, ft admin tokens) is left out of the MCP on purpose: an agent lists credentials to audit them, it does not issue them. The customer_* tools are for enterprise integrations: they need an enterprise service API key and the buyer's session token (X-Customer-Session). The exchange that issues that token is not a tool either — it mints third-party sessions.

settlements_document and settlements_proof return a signed URL with a 5-minute TTL, not the file: the API answers 302, and following the redirect would drop the whole PDF into the model's context.

🔒 = the result carries a secret: the stream key of a live (streamKey, broadcast rights in the organization's name; only content_lives_create and content_lives_reset_key return it) or the code/URL of a master QR (opens the sale flow, cannot be rotated). The descriptions tell the agent not to echo it into the chat or docs unless the human explicitly asks. The server does not log or store tool results: the value only lives in the client's transcript. Videos cannot be uploaded through the API (the Mux upload needs a browser).

The content tools list what is published without the playback id; to play anything you need content_playback_token (30 min live, 1 h video), and memberOnly content additionally requires a buyer session with a membership.

Public B2C /api/public (no credentials — a buyer's agent):

The public_* tools are always registered (anonymous). The agent never touches the payment: public_orders_create returns the Mercado Pago link for the human to pay. Checkout scope: general admission (not seated, not members-only).

Superadmin /api/admin (only with FT_ADMIN_SESSION):

Launching, advancing or stopping batches and cancelling CRM campaigns is not exposed: those operations send real email and WhatsApp to buyers. The contract marks them x-ft-mcp: { expose: false } and src/coverage.test.ts fails if a tool calls them. Use the CLI (ft admin crm) or the panel.

UI in the host (MCP Apps)

The server implements the io.modelcontextprotocol/ui extension (MCP Apps, spec 2026-01-26), so lists and reports do not arrive as a wall of JSON: the host draws them.

• Resource: ui://freeticket/view.html, mimeType text/html;profile=mcp-app.

• Tools with a view point at it through _meta.ui.resourceUri; the result also travels in structuredContent so the view can read it.

• A single view picks the render from the shape of the payload: array → table (currency formatting, status pills, horizontal scroll), object → KPI tiles.

• The HTML is self-contained: no external scripts, no fetch, no remote fonts. It declares csp: {} — it asks for no network, so the host's deny-by-default sandbox has nothing to block.

• The brand is ours, the theme is the host's. The view adopts the host's CSS variables (hostContext.styles.variables) to blend into the chat, but only those in the extension's contract (--color-*, --font-*): the FreeTicket logo and brand accent are not overridable. On a theme change it sets data-theme and color-scheme, otherwise light-dark() would follow the OS and the view would render light inside a dark chat.

• It listens only to the frame that mounted it (event.source), reports its height with ui/notifications/size-changed, formats currency in the host's locale, and answers ui/resource-teardown so unmounting is clean.

• Hosts without the extension (or terminal clients) ignore _meta and see the same text as always: nothing breaks.

49 tools with a view (v0.20.0) — every list and every report. Details (*_get) and writes deliberately have none: a lone object or a delete acknowledgement gains nothing from a table, and drawing one suggests there is data where there is not. src/ui.test.ts mounts the real view in jsdom and fails if a new list registers without _meta.ui, if the host manages to override the branding, or if an API payload renders unescaped.

Support and privacy

• Support: soporte@freeticket.us, or open an issue at AppFreeticket/freeticket-mcp.

• Privacy policy: appfreeticket.com/legal/privacidad. The server is stateless: it keeps no log or store of tool results.

Development

pnpm install
pnpm generate     # regenerates src/client/, src/admin-client/ and src/public-client/ from the specs
pnpm dev          # runs the server over stdio
pnpm typecheck && pnpm test

Contracts this build targets: B2B 1.36.0, superadmin 1.8.0, public 0.10.1. All three are served by free-admin and are the only source of truth, on separate semver lineages. To propagate a backend change, use the contract-sync agent from the ai-native umbrella — and check for drift first: what free-admin serves today may already be ahead of the numbers above.

MIT.