Alchemist Cloud Tickets MCP

The Alchemist Cloud Tickets MCP server lets an AI client (claude.ai, ChatGPT, Claude Code, Claude Desktop, Cursor, or anything that speaks the Model Context Protocol) talk to your Alchemist Cloud project tickets directly. From inside your assistant you can dispatch tickets, list and read their status, reply to a ticket that’s paused waiting on your input, watch deploys, read your deployed app’s errors, check costs, browse the project’s repo, run read-only queries against the project database, and export files — all without leaving the conversation.

Naming note: this is a dedicated server for Alchemist Cloud (project/ticket automation), separate from the Chipp MCP server (which manages Chipp apps — system prompt, knowledge, custom actions) and separate from the in-product “Alchemist” chat assistant you talk to inside the dashboard. If you previously connected an MCP client to the plain-named “Alchemist” server, your connection keeps working unchanged — the endpoint and auth are the same, only the display name was clarified.

The server speaks Streamable HTTP at https://build.chipp.ai/alchemist-api/api/mcp. There are two ways to connect, depending on what your client supports:

• OAuth — for hosted connectors whose “add connector” dialog offers only a URL (claude.ai custom connectors, ChatGPT). You paste the URL and approve a browser consent screen; there’s no key to copy. Access is scoped to you (your user), so it reaches every project you own or are a member of.
• API key — for clients that let you set an Authorization header (Claude Code, Claude Desktop, Cursor). Access is scoped to your tenant.

Either way you only ever see your own projects, tickets, and data.

Option A — OAuth (claude.ai, ChatGPT)

Use this for hosted connectors whose dialog only takes a URL. In claude.ai: Settings → Connectors → Add custom connector.

1. Paste the server URL: https://build.chipp.ai/alchemist-api/api/mcp
2. Leave OAuth Client ID / Client Secret blank — the connector registers itself automatically (Dynamic Client Registration). Those fields are only for pre-registered clients, which you don’t need.
3. Click Add. A browser window opens an Alchemist consent screen — sign in to your dashboard if prompted, then Approve. The connector is now live.

No API key is involved. Disconnect any time from your client’s connector settings (that revokes the access immediately).

Option B — API key (Claude Code, Claude Desktop, Cursor)

These clients send a bearer token, so they use a tenant API key.

Unified endpoint: with an alch_ API key you can also point your client at https://build.chipp.ai/mcp (the same URL as the Chipp MCP Server). The server routes by key type, so one URL works for both products; the alchemist-api URL below remains fully supported.

1. Create an API key

Mint a key on the API Keys page in the Alchemist tab sidebar (owners and admins only; see API keys). The secret is shown once — copy it immediately. You can revoke it at any time.

2. Point your client at the server

Claude Code (one command):

claude mcp add --transport http alchemist https://build.chipp.ai/alchemist-api/api/mcp \
  --header "Authorization: Bearer alch_your_key_here"

Claude Desktop / Cursor (config file):

{
  "mcpServers": {
    "alchemist": {
      "url": "https://build.chipp.ai/alchemist-api/api/mcp",
      "transport": "streamable-http",
      "headers": { "Authorization": "Bearer alch_your_key_here" }
    }
  }
}

Tools

Why your client may list tools this guide does not document. On this endpoint, tools/list returns the whole server registry rather than a filtered set, so a few operations tools show up in your client: propose_data_operation, propose_script_operation, run_script_operation, propose_slack_invite, and request_credentials. They are not usable from a tenant API key or an OAuth connection. This lane binds only your tenant and your user, and those tools need a project-scoped conversation session, so every call fails immediately with no_session_bound or no_project_bound. They are reachable only from the project bridge that Alchemist’s own desktop and project-token clients use, the same one your project’s own agent talks over, see Adding Environment Variables and Secrets for request_credentials from that side. Nothing is wrong with your setup; ignore them here and use the tools below.

Tickets

• dispatch_ticket — create and dispatch a ticket. kind is feature, fix, refactor, data_operation, or org_agent_construction; there is no standalone read-only investigate mode (research runs as a node inside a ticket’s own graph). Write the title + description as a complete, self-contained brief — the platform plans and verifies its own work internally, without asking follow-up questions. Pass depends_on (an array of ticket UUIDs or #N references) to make the ticket wait until those parents succeed (DAG dependencies).
• propose_ticket_batch — draft several related tickets at once, with dependency edges between them, behind ONE approval instead of one approval per ticket. Each draft ticket carries a stable node_id you mint (never a real ticket id); a dependency can point at another draft in the same batch (type: "node", ref = its node_id) or at an already-filed ticket (type: "existing", ref = its key/UUID — this is how you extend a chain you started earlier). Validates the whole graph up front (no cycles, every project accessible, every dependency names what it consumes, one cohesive outcome per ticket) and returns an approval card plus a batch_proposal_id. Nothing is created yet.
• dispatch_ticket_batch — file every ticket in a batch proposed by propose_ticket_batch. Who approves depends on how you connect (see Who approves a batch). Only your own account’s proposals can be dispatched. Returns a scope_id for following the batch. Safe to call again for the same batch_proposal_id: an already-dispatched batch returns the same created ticket keys instead of filing duplicates.
• wait_for_tickets — follow tickets live. Pass scope_id and/or tickets; the call blocks until one of them changes (or timeout_seconds, default 90, max 110) and returns changes, a cursor to pass back on the next call, and all_terminal. Worker heartbeats never count as changes. See Following tickets live.
• start_sandbox_change — queue a small code change directly onto a project’s sandbox coding agent, instead of filing a ticket for it. Takes one instruction (plain language, written for an agent that has the repo open) and an optional idempotency_key. Use it for a change you can describe in a sentence or two; use dispatch_ticket for larger work that needs planning, review, and the full pipeline. The work runs asynchronously: the call returns as soon as the request is queued, and a human reviews the change in the project workspace before it merges. There is no project argument — the change targets the project bound to the connection, so this tool only works on a project-scoped connection (a bare tenant API key has no project bound and the call is refused). Opt-in per project, off by default: the tool is only offered to projects that have turned it on in project settings (the project’s Settings tab, Agent code changes switch). A project owner or an organization owner or admin can flip it; editors and viewers cannot. Everywhere else it is neither listed nor callable, and dispatch_ticket remains the way to request code work.
• resolve_sandbox_review — answer a sandbox change that is waiting for review. A queued change pauses before it merges so a human can look at the preview; this applies their answer. Takes the review’s message_id, a decision of approve (let it land) or request_changes (send it back), and optional feedback passed to the agent verbatim. Answering a review that was already resolved, in the project workspace or by the review timeout, is a safe no-op rather than an error. Same project-scoped connection requirement as start_sandbox_change, and gated by the same per-project opt-in — the two are enabled together, so a project that can start a change can also answer its review.
• list_tickets — recent tickets, optionally filtered by project, status, ids, scope_id, or updated_since (pass the previous response’s asOf).
• get_ticket — one ticket by UUID or number (#42). Its result field (result_version: 1) is the stable, machine-readable outcome: branch, head sha, recorded commit shas, outcome, summary, contract items, verification gaps, open questions, and cost from the credit ledger.
• get_ticket_contract — the ticket’s contract items (its negotiated done-checklist), each with a verification state: verified, not_verified, or not_recorded (in the contract but never graded). Call this before saying a ticket fixes or covers something: get_ticket answers status, this answers coverage.
• get_ticket_audit — the agent’s per-turn narration across all nodes in the ticket’s graph.
• get_ticket_reports — durable per-phase execution reports and the final completion summary.
• get_scope_graph — the dependency graph and live progress rollup for a multi-ticket scope (depends_on DAG). Every node you can access carries the same result object as get_ticket.
• update_ticket — edit a not-yet-started ticket’s title, body, or kind.
• cancel_ticket / retry_ticket — stop or re-run a ticket.
• reply_to_ticket — answer a ticket that’s paused awaiting_input (the agent asked a question mid-build — an ambiguity, a missing credential). Relay the human’s answer; a continuation ticket resumes the work automatically. Never paste a secret value here — if the agent asked for a credential, use the secure submission link from its question.

Who approves a batch

• Chipp API key (Claude Code, scripts): your dispatch_ticket_batch call is the approval. No person taps anything.
• OAuth (claude.ai, ChatGPT, desktop connectors), a Chipp developer key (chipp_sk_*) on https://build.chipp.ai/mcp, a signed-in session, or an agent filing tickets from a Chipp app’s chat (web chat, Slack, and the other channels): the assistant cannot approve. A person approves the whole batch once in Chipp. Open the Chipp Builder and ask the assistant to “dispatch ticket batch <batch_proposal_id>”. It shows one card for the whole batch, with the ticket count, the projects, and the full ticket list collapsed. One Approve tap files every ticket; no ticket asks again, whether the batch has 3 tickets or 80. Until then, dispatch_ticket_batch files nothing and returns ok: false with code: "BATCH_AWAITING_APPROVAL" and where to approve. After the approval, call it again with the same batch_proposal_id to get the scope_id.
• A host that shows views (see Views in chat): the person can also approve right in the conversation, with Approve all on the batch card.

Following tickets live

A Claude Code session can file a batch and watch it progress, then read a structured result per ticket:

1. propose_ticket_batch, then dispatch_ticket_batch. Keep the scope_id. With an API key the dispatch call is the approval.

2. Start a background Monitor on the tickets stream. Put your key in an environment variable first; never paste it into the chat.

   bash

   curl -sN -H "Authorization: Bearer $CHIPP_API_KEY" \
     "https://build.chipp.ai/alchemist-api/api/mcp/tickets/stream?scope_id=<scope_id>" \
     | grep --line-buffered '^data: '

   Each line is one JSON event: snapshot, status, phase, summary, awaiting_input (with question and request_id), terminal (with outcome and a one-line summary), and finally done, after which the stream closes. Every event has a cursor; reconnect with &cursor=<cursor> to resume without repeats. tickets=<ref>,<ref> works in place of scope_id. With a Chipp credential (chipp_sk_* or chipp_at_*) use https://build.chipp.ai/mcp/tickets/stream with the same query; it streams your org’s tickets with the same limits. If you connect over OAuth and cannot run a Monitor, call wait_for_tickets in a loop instead; it is the same feed.

   One stream follows a whole scope (up to 200 tickets). A workspace can hold 20 open streams and wait_for_tickets calls at once; past that the server answers 429. A stream that stays open for 4 hours sends a reconnect event with a cursor and closes; start it again with that cursor.

3. On awaiting_input, answer with reply_to_ticket and the event’s request_id.

4. After done, call get_scope_graph and read each node’s result.

Views in chat (MCP Apps)

Hosts that support MCP Apps (the io.modelcontextprotocol/ui extension) show some tool results as small interactive views inside the conversation. Other clients, Claude Code included, get the same tools with the same text results and no view.

Approve all records your approval of the whole batch (the same approval the Chipp Builder card gives) and then asks the assistant to dispatch it. The button calls approve_ticket_batch, a tool only the view can call: the server lists it only for a client that declared MCP Apps support, and the host keeps it away from the model. It needs a signed-in Chipp account (an API key session dispatches its own batch and needs no approval), it only approves a batch in your own workspace, and a second click changes nothing.

The dashboard and the agent graph update themselves through wait_for_tickets, so an open view counts toward the 20 open watches above. A view stops updating after 30 minutes; click Resume live updates to continue.

Projects and deploys

• list_projects — your projects, with deploy status and public URL.
• get_project — one project, with its latest deploy and a cost breakdown.
• list_deploys — recent deploys for a project, with failure reasons.
• create_project — create a new project from a template (provisions the GitHub repo, initial deploy, and public URL; returns immediately, the deploy runs async — poll get_project / list_deploys for build progress).
• get_deploy_gate_status — whether a project’s deploy gate (“deploy trains”) has work piling up: the gate mode, when it last actually released, how many contributions are currently held, and a live preview of the release notes / QA checklist a release would generate right now. Check this before proactively suggesting a deploy.
• trigger_deploy — release everything currently held behind a manual or scheduled deploy gate (same action as “Deploy now” in the dashboard). No-ops cleanly when the gate is continuous or nothing is pending.
• set_project_feature — turn a built-in feature of a project on or off. Every project ships two, switched off until you turn them on: api (API keys and paid /api/v1 routes) and mcp (an MCP server at /api/mcp with OAuth and paid tools). Both can be on at once. No code change: the live build restarts with the new setting. get_project shows which are on.

Production errors

• get_project_errors — recent error logs from a project’s live app (pick a time window and an optional substring filter).
• get_alert_status — whether the error-investigation agent is currently working an alert on a project, and how often alerts have recurred.
• get_env_status — whether the project’s production deployment is missing any required environment variables (from its startup env-validation logs; presence status only, never values).
• get_project_logs — read recent logs from a project’s deployed app: pick a time window (5m-7d), a level (error/warn/info/all), and an optional substring or regex filter. Curated query, capped at 500 lines.

Billing

• get_credit_balance — your current credit balance.
• get_project_cost / get_ticket_cost — cost breakdowns by project or ticket (LLM, sandbox, pod, storage).

Repo access

• read_repo_file — read a single file from the project’s GitHub repo (at the HEAD of the default branch).
• read_imported_repo_file — read one file from the GitHub repository the builder imported and confirmed for this project (the “rebuild an existing app” flow), not the project’s own generated repo. Returns not_found until a GitHub import has been confirmed; files over ~512KB come back with truncated: true and empty content.
• list_repo_dir — list the entries in a repo directory (capped at 500).
• search_repo — case-insensitive literal substring search across the repo.

Database

• inspect_schema — read the project database schema. Columns holding secrets are masked out.
• query_database — run a single read-only SQL query (SELECT / CTE only) against the project database. Writes and DDL are rejected at the connection level.

Email ingestion

• provision_email_ingestion — set up the inbound email pipeline for a project: mints the ingest credential, creates the MX record and inbound mail server, and wires deliveries to the project’s /api/ingest/email route. Idempotent; re-run to repair drift.
• get_email_ingestion_status — the project’s ingest address and provisioning health (never returns the token).
• deprovision_email_ingestion — tear the pipeline down (the dormant ingest route stays safe; re-provisioning reuses the credential).

Outbound mailbox

• set_project_outbound_mailbox — configure a project’s custom outbound mailbox: a real mailbox on the customer’s own mail provider (SMTP credentials), so the project’s agent sends and is addressed as that real mailbox instead of the platform default.
• get_project_outbound_mailbox_status — a project’s custom outbound mailbox status: host, port, username, whether a password is set, and a preview of the resolved From header. Never returns the password.

File delivery

• export_csv — build a CSV from { columns, rows }, store it in private R2, and return a short-lived signed download URL.
• deliver_file — upload arbitrary bytes to private R2 and return a short-lived signed download URL.

Incident diagnostics

• what_changed — correlate recent deploys against the error rate around them, the first question in any incident (“did this start after a deploy?”). Returns each deploy that completed in the window with the error count in the equal-length span before and after it, flagging the ones where errors rose.
• watch_deploy — watch a deploy settle and return a regression verdict plus the exact rollback target, comparing the error rate after it against the equal-length span before.
• get_runtime_health — read a managed project’s pod state: replica readiness, restart counts, crashloops, OOMKills, and pods stuck Pending. A pod that crashes before serving traffic writes no application logs, so this covers the blind spot get_project_errors cannot see.
• get_migration_status — compare the migrations recorded as applied on the live database against the migration files in the repo, and report which are pending. Use it when a deploy succeeded but the app errors on a missing column or table.
• get_user_journey — reconstruct one end user’s timeline: their Chipp Insights beacon events (pageviews, identify, client-side errors) merged with server-side error lines mentioning them, oldest first. This is the support-ticket tool: aggregate analytics cannot answer “what happened to THIS person”.

Release control

Platform releases govern the self-hosted project; project deploys govern a customer project. Rollback-shaped actions are deliberately ungated — they are the recovery path, and they are reversible and audited.

• get_platform_release_state — read the current mode (auto = every push deploys on the next train window, manual = builds publish but hold) and the desired-state pointer.

• set_platform_release_mode — switch between auto and manual. Switching to manual is a pause, and is allowed freely.

• list_platform_releases — recent platform releases, newest first: git sha, status (candidate / promoted / deployed / superseded / rolled_back), commit subjects, and operator notes.

• promote_platform_release — promote a release to production, the same action as “Deploy now” on the Releases tab. Moves the desired-state pointer; the reconciler applies it.

• rollback_platform_release — move the desired-state pointer back to a previously deployed release. Ungated and available in any mode.

• list_platform_release_events — the release audit trail (published / promoted / rollback / deployed / superseded / mode_changed), newest first. Answers “who moved the pointer, when, and why”.

• get_project_release_status — a project’s rollback-relevant deploy state: whether it is pinned, and which recent deploys are recalled.

• rollback_project_deploy — roll a project back to a previously completed deploy by re-applying its built image, and pin the project so nothing rolls forward past it until cleared.

• clear_release_pin — remove that pin so normal forward deploys resume.

• recall_deploy — mark a deploy known-bad so it can never be chosen as a rollback target again. If the recalled deploy is the live one, a rollback to the newest non-recalled completed deploy is queued automatically.

• clear_recall — un-mark a previously recalled deploy, when the recall turned out to be a misdiagnosis.

• get_ci_run_log — read the REAL failed GitHub Actions job log for the project’s repo: which jobs failed, the exact step that failed, and a redacted tail of each job’s log. Call this FIRST when a deploy or CI run is red — a release checkpoint’s detail is a fixed placeholder line and tells you nothing.

• run_ticket_ci — starts a ticket’s CI run in GitHub Actions (ticket-ci.yml): the whole type check plus the tests the branch touches, on the job branch’s tip. Only the ticket’s final verification node may call it, once per ticket; after a failure, a fix commit allows one more run.

• request_verification_session — signs a ticket’s deployed-app verification node in to the project’s deployed app as a dedicated verification account and checks /api/auth/me. Read-only by default; mode: "mutate" allows scoped writes that are reverted at node end.

• get_ticket_ci_result — the newest ticket CI run for a ticket: status, commit, run link, and on a finished run the type errors and failing tests. wait_seconds waits up to 240 seconds for the verdict.

• get_nightly_ci_report — last night’s CI repair list for the project. Tickets no longer run type checks or unit tests; a nightly GitHub Actions job (nightly-ci.yml) runs the whole type check and test suite instead. Returns green or red, the sha and run link, counts, and the top type errors and failing tests with file and line. Ask for it in your Daily Ping and assign the repairs with dispatch_ticket.

• get_release_digest — today’s suggested release: every ticket and commit landed but not yet deployed (fixes and features, the production errors each fix addresses, risk notes), the urgent production errors from the last 24 hours with where each one’s fix stands, last night’s CI status, and the link where a human approves the release. Nothing ships until someone clicks “Deploy now” there. Ask for it in your morning Daily Ping.

Data-layer brief

• record_data_layer_brief — record the project’s data-layer brief (what data the app stores and why). Recording after a confirmation resets the status to recorded, so a materially revised brief must be re-confirmed.
• confirm_data_layer_brief — confirm the recorded brief. This is the only thing that sets the status to confirmed, which is what opens the build gate. A confirmed brief that says “no data layer” is a valid outcome for a static app.

Chipp agent widget

Install the official Chipp chat widget into a project by AGENT NAME, so a project gets a real Chipp agent instead of a hand-rolled chat UI.

• find_chipp_agent_by_name — resolve a Chipp agent by human-readable name across every workspace the current builder can access. Returns single (safe to install directly), multiple (show a picker, then pass the chosen application_id), or no match. The discovery step; always call it first.
• install_chipp_agent_widget — install or update the widget for a project: resolves the agent by name (or by an application_id already confirmed via the picker), derives a theme from the project’s own design tokens, and commits the official widget-v2 embed to the project’s repo.
• get_chipp_agent_widget_status — report the project’s CURRENT widget config (bound application, presentation mode/position/behavior/greeting, theme), or null if never installed. Call this BEFORE generating any new chat or AI-assistant UI: if a config exists, modify it through install_chipp_agent_widget instead of building a second integration.
• remove_chipp_agent_widget — uninstall the widget: supersedes the persisted config and deletes the generated files in one commit. Never touches the underlying Chipp agent or its conversations. Idempotent.

Provider lookups

Read-only checks against a project’s OWN third-party provider account (currently the project’s Stripe), so an agent can verify provider-side facts without ever seeing the credential.

• provider_lookup — run one enumerated read-only verb against the project’s provider using its stored credential, resolved server-side: list_webhook_endpoints, list_events, get_event, subscription state, and list_paid_checkout_sessions (paid, completed sessions in a lookback window, default 48h, each with the buyer’s email) for reconciling payments against provisioned members. Operator-granted per project; a project without the grant gets a clear “not enabled” result (do not retry). Responses are field-slimmed and secret-scrubbed, and project_id is tenant-checked.
• propose_provider_webhook — propose provisioning the project’s own Stripe webhook endpoint with automatic signing-secret capture into the managed deployment. Approval-gated: files a proposal a project member approves from Slack or the dashboard; on approval the platform creates the endpoint, captures the signing secret (never shown to anyone), stores it as STRIPE_WEBHOOK_SECRET, and applies it to the deployment. Idempotent while a proposal is pending. Requires the operator write grant (provider_broker_config.stripe.allowWrites).

Tool schemas (request/response reference)

For the complete machine-readable request and response schemas for dispatch_ticket, list_tickets, and get_ticket — including all field types, required/optional markers, annotated example payloads, and error code tables — see the Tickets MCP Tool Schemas reference page.

Notes

• Reads are curated and bounded. The one SQL surface, query_database, is read-only (SELECT / CTE only, writes and DDL rejected) and tenant-scoped; there is no raw log-query tool. Every tool returns a structured result scoped to your tenant.
• An OAuth connection (Option A) is scoped to your user and uses short-lived tokens that refresh automatically; revoke it by removing the connector in your client. An API key (Option B) is scoped to your tenant and stops working the instant you revoke it on the Alchemist API Keys page.
• An API key authenticates any HTTP call to the platform API, not just MCP.
• This page is also available as raw markdown at https://build.chipp.ai/alchemist-api/api/docs/mcp-server.md, and the whole doc set at https://build.chipp.ai/alchemist-api/api/docs/llms-full.txt — point an AI agent at either.