Mitzu MCP Server

Mitzu's MCP server lets you ask questions about your product data from any MCP-compatible AI client — Claude, Cursor, ChatGPT, and others. It exposes the Mitzu analytics agent over a remote endpoint, so you can run analyses, inspect artifacts, and continue conversations from your editor or chat tool.

Connect your client

Server URL

Most clients connect with a one-click install button or an in-app Connectors UI that takes the URL above. On first connect your client opens a browser for WorkOS login and prompts you to pick a workspace — the client stores the rotating access token automatically, so there is no token to copy from the Mitzu UI.

Pick a client above to see step-by-step connect instructions.

Advanced connection details

Setting	Value
Server URL	https://app.mitzu.io/mcp
Transport	Streamable HTTP (Server-Sent Events)
Authentication	OAuth 2.0 (WorkOS), discovered automatically by the client
Protected resource metadata	https://app.mitzu.io/.well-known/oauth-protected-resource
Authorization server metadata	https://app.mitzu.io/.well-known/oauth-authorization-server
Required Accept header	application/json, text/event-stream

Raw HTTP clients must send Accept: application/json, text/event-stream. The agent endpoint streams live progress over SSE; a JSON-only Accept header is rejected with a 406 response.

What the agent can do

The MCP server exposes the same Mitzu analytics agent that powers the in-app and Slack experiences — natural-language segmentation, funnels, retention, and data discovery. See Analytics Agent for the full capability list and example prompts.

Tools

The MCP server exposes 8 tools in agent mode. Most clients only need run_analytics_agent — the rest let you drill into the artifacts the agent produces without paying for another agent run.

Tool	Purpose
run_analytics_agent	Start an analytics run on a natural-language question. Returns immediately with a conversation_id.
get_analytics_agent_status	Poll an in-flight run. Long-polls by default and streams live progress over SSE.
list_agent_artifacts	List every data artifact the agent has produced in the current session.
inspect_artifact	Inspect metadata for a stored artifact.
describe_table_artifact	Get row count, columns, dtypes, and a head sample for a table artifact.
query_table_artifact	Filter, sort, project columns, and paginate rows from a table artifact.
read_json_artifact	Read bounded slices from one or more JSON artifacts.
grep_json_artifact	Regex-search rows of a JSON artifact.

Async start/poll contract

run_analytics_agent is asynchronous. It spawns the agent as a background task in the server process and returns immediately with {status: "running", conversation_id, prompt_id, conversation_url}. Clients poll get_analytics_agent_status to retrieve progress and the final answer.

All other tools are synchronous and return a single JSON response.

Tool reference

run_analytics_agent

Kick off the Mitzu analytics agent on a natural-language analytics question. Returns immediately; the background task owns the full lifecycle and persists the transcript on completion.

Parameter	Type	Required	Description
question	string	yes	The analytics question, phrased in natural language.
max_turns	integer	no	Cap on the number of agent turns.
conversation_id	string	no	Id of an existing conversation to continue. Omit to start a fresh conversation.
cancel_running	boolean	no	If true, stop any in-flight run on the same conversation_id and execute this request instead. Defaults to false, which returns {status: "busy"} while a run is in flight.

get_analytics_agent_status

Poll a run_analytics_agent run. Long-polls by default, emitting notifications/progress over SSE for every new step (plus periodic heartbeats) until the run finishes or the timeout elapses.

Parameter	Type	Required	Description
conversation_id	string	yes	The conversation_id returned by run_analytics_agent.
wait_for_completion	boolean	no	Defaults to true. Set to false for a single non-blocking snapshot.
timeout_seconds	integer	no	Per-call wait budget when wait_for_completion=true. Default 90 s, capped at 300 s.

Possible result shapes:

• {status: "running", last_progress, progress, conversation_id, conversation_url} — agent is still working.
• {status: "done", answer, artifacts, session_id, progress, conversation_id, conversation_url} — run finished successfully.
• {status: "error", message, conversation_id, ...} — agent raised.
• {status: "superseded", conversation_id, ...} — another run_analytics_agent call with cancel_running=true took over.
• {status: "lost", conversation_id, ...} — the server restarted mid-run; re-issue run_analytics_agent to retry.

list_agent_artifacts

List every data artifact (table or JSON) the agent has produced in the current MCP session, newest first. Each entry includes the originating question, source tool, row count, columns (for tables), size, and a short summary. No parameters.

inspect_artifact

Inspect metadata for a stored artifact.

Parameter	Type	Required	Description
artifact_id	string	yes	The artifact ID to inspect.

describe_table_artifact

Describe a table artifact: row count, columns with dtypes, and a small head sample. Call this before query_table_artifact to understand the table's shape.

Parameter	Type	Required	Description
artifact_id	string	yes	The table artifact ID to describe.

query_table_artifact

Filter, sort, project columns, and paginate rows from a table artifact. Use this for any ranking, top-N, or filtering question — never sort or filter rows in your own reasoning.

Parameter	Type	Required	Description
artifact_id	string	yes	The table artifact ID to query.
sort_by	string[]	no	Column names to sort by.
order	string	no	asc (default) or desc.
filters	object[]	no	Each filter is {column, op, value}. Supported ops: eq, ne, gt, gte, lt, lte, contains. Filters are AND-combined.
columns	string[]	no	Subset of columns to return. Omit to return all columns.
top_n	integer	no	Maximum rows to return.
offset	integer	no	Zero-based row offset for pagination.

read_json_artifact

Read bounded slices from one or more JSON artifacts in a single call.

Parameter	Type	Required	Description
reads	object[]	yes	List of {artifact_id, offset, limit} slices. Request every artifact you need in a single call.

grep_json_artifact

Search a JSON artifact for rows matching a regex. Returns matching rows with their offsets so you can follow up with read_json_artifact for surrounding context.

Parameter	Type	Required	Description
artifact_id	string	yes	The JSON artifact ID to search.
pattern	string	yes	Python regular expression matched against each row's JSON-serialized form.
case_insensitive	boolean	yes	If true, the regex matches without case sensitivity.
max_results	integer	no	Maximum number of matching rows to return.

Conversations and artifacts

run_analytics_agent is a durable conversation, not a stateless call. Every run is persisted server-side and surfaces a conversation_url deep link into the Mitzu webapp. Pass the returned conversation_id back into another run_analytics_agent call to continue the same conversation — including conversations that originally started in the webapp or in Slack.

Artifacts are scoped per user and project, so they're shared across every tool call you make on the MCP server. Drill into artifacts the agent produced with list_agent_artifacts followed by query_table_artifact, read_json_artifact, or grep_json_artifact — much faster than re-running the agent for follow-up questions.

Troubleshooting

• Authentication expired — re-authenticate from the client. WorkOS access tokens rotate every few minutes; refresh is automatic, but a long-idle client may need to re-run the connect flow.
• 406 Not Acceptable — the client is sending Accept: application/json only. Add text/event-stream to the Accept header.
• {status: "busy"} on run_analytics_agent — an earlier run is still in flight on the same conversation_id. Pass cancel_running=true to take over, or start a new conversation by omitting conversation_id.
• {status: "lost"} on get_analytics_agent_status — the server restarted mid-run, leaving no transcript. Re-issue run_analytics_agent to retry.