Connect an AI coding assistant to Catalyst
diagrid mcp serve runs a local Model Context Protocol server that gives an AI coding assistant a curated set of Catalyst tools. The assistant can then answer questions like "which workflow runs failed in my staging project?" and act on the answer, without you pasting CLI output into the chat.
The server runs on your machine, over stdio, as a subprocess of the assistant. It uses the credentials from your existing diagrid login — there is nothing to deploy, no public endpoint, and no separate authorization step.
This is not the same thing as an MCP server hosted in your project. That feature puts Catalyst in front of an upstream MCP server so your agents can call its tools. This page is the reverse: it exposes Catalyst itself as tools, to an assistant running on your laptop.
Prerequisites
- The Diagrid CLI, installed and on your
PATH. - A completed
diagrid login. The server re-reads your credentials on every call, so a long assistant session outlives the token it started with. - One of the supported assistants: Claude Code, Claude Desktop, Codex, or GitHub Copilot.
Register the server
diagrid mcp install writes the configuration your assistant needs, so you do not assemble it by hand:
diagrid mcp install --client claude-code
Pass one of claude-code, claude-desktop, codex, or copilot. Claude Code is configured by running its own claude mcp add; the other three have their configuration file written directly.
| Flag | What it does |
|---|---|
--client | Required. The assistant to configure. |
--name | Name to register the server under. Defaults to catalyst. |
--data-sharing | Pins the response-filtering level in the written config. See Choose how much the assistant sees. |
--dry-run | Reports what would be written, and writes nothing. |
--force | Replaces an existing server of this name, backing up the configuration file first. |
An existing server of the same name is never overwritten silently. If the entry is already identical, nothing happens; if it differs, the command stops and tells you, and --force replaces it after copying the file aside.
--force rewrites Codex's config.toml rather than appending to it, which drops the comments in that file. The backup the command leaves behind is how you get them back.
Restart the assistant after installing, then ask it something that needs Catalyst — "list my Catalyst projects" is enough to confirm the connection.
What the assistant can do
The server exposes 22 tools, all named catalyst_*. Sixteen only read:
| Area | Tools |
|---|---|
| Account | catalyst_whoami |
| Projects | catalyst_list_projects, catalyst_get_project |
| App IDs | catalyst_list_appids, catalyst_get_appid |
| Components | catalyst_list_components, catalyst_get_component |
| Workflows | catalyst_list_workflows, catalyst_get_workflow, catalyst_list_workflow_runs, catalyst_get_workflow_run |
| Agents | catalyst_list_agents, catalyst_get_agent |
| MCP servers | catalyst_list_mcp_servers, catalyst_get_mcp_server |
| Metrics | catalyst_get_metrics |
Six change state, and are annotated as writes so your assistant can prompt you before calling them: catalyst_start_workflow, catalyst_pause_workflow_run, catalyst_resume_workflow_run, catalyst_raise_workflow_event, catalyst_rerun_workflow_run, and catalyst_terminate_workflow_run. Of those, catalyst_terminate_workflow_run is annotated destructive — it ends a run that cannot be resumed.
The assistant acts as you. It can reach exactly the projects your own login can reach, and nothing more.
Choose how much the assistant sees
--data-sharing controls how much of a response the server is allowed to return:
full— the default. Full responses, payloads included.metadata— names, IDs, and status only. Workflowinput,output, andcustomStatusare withheld.
The default is full, because the payloads are what make a failed run diagnosable — and they go to your assistant's model provider along with everything else in the transcript. metadata keeps application data out of that context, at the cost of the payloads that explain why a run behaved the way it did.
Set the level per invocation on diagrid mcp serve:
diagrid mcp serve --data-sharing metadata
Or pin it once in the written config at install time:
diagrid mcp install --client claude-code --data-sharing metadata
install writes the flag into the config only when you pass it; without it, serve applies its own default.
Pick the level from what your assistant does with the transcript, not from the sensitivity of the CLI: the same data is on your screen either way.
Register the server by hand
If your assistant is not one of the four install supports, register diagrid mcp serve as a stdio subprocess yourself. For Claude Code that is:
claude mcp add catalyst -- diagrid mcp serve
diagrid mcp serve is not meant to be run interactively — its output is JSON-RPC on stdout. If you are logged in to a non-production Catalyst environment, pass --management-base-url with that environment's Management API base URL; the flag defaults to production, and the host is not published per environment.
What's next
- Diagrid CLI — every command the assistant's tools wrap.
- Dapr Skills plugin — scaffold and review Dapr Workflow applications in Claude Code.
- MCP on Catalyst — the other direction: put Catalyst in front of an upstream MCP server for your agents to call.
