
mcp
io.diagrid/mcp
Build and operate Dapr Workflows and Durable Agents on Diagrid. Sign-in required.
Documentation
diagrid-ai
Build and operate apps on Diagrid (formerly Diagrid Catalyst) by prompting — Dapr Workflows, Durable Agents, and the running system.
Verified end to end in Claude Code — installs in under 5 seconds, every skill registers, and a real Diagrid question fires the right skill and gets a grounded answer. In Codex and GitHub Copilot the install and every skill are verified, and Codex is confirmed to put them in front of the model; neither has yet answered a Diagrid question here, for reasons that are nothing to do with the skills.
Early release. The skills drive Diagrid through the remote Diagrid MCP server: you add the server and sign in once. The one exception is an app tunnel, which lets Diagrid call into a process on your machine. No MCP tool opens one, so
diagrid-app-tunnelsinstalls the Diagrid CLI and uses it for that alone. Read What works today for what is and is not available over MCP yet.
Install
Claude Code
claude plugin marketplace add diagridio/diagrid-ai
claude plugin install diagrid@diagrid
If you installed catalyst-ai@diagrid before, that is this plugin under its old name.
See Moving from catalyst-ai.
This repo used to be diagridio/catalyst-ai. GitHub redirects the old name, so a
marketplace you added from it keeps updating, and you don't need to add it again.
Then check it landed — both commands, not just the second:
claude plugin list # expect Version: 0.10.0 or later
claude plugin details diagrid@diagrid # expect 12 skills
list reports the version you actually have. details reports the version the
marketplace is offering, reading the installed copy only when the two agree — so on its
own it can show you 12 skills while your session loads 11. If either looks wrong, jump to
If your install is behind.
The same marketplace also lists dapr-skills, for Dapr applications that run outside
Diagrid — see Also in this marketplace.
Then sign in to the Diagrid MCP server
The plugin also registers the Diagrid MCP server, https://mcp.cloud.r1.diagrid.io/mcp.
It stays empty until you sign in once. In Claude Code, run /mcp, pick
plugin:diagrid:diagrid and complete the browser sign-in. There is no API key.
If you are upgrading from 0.8.x, see Upgrading from 0.8.x.
If you already added the server yourself with claude mcp add, remove that entry
(claude mcp remove catalyst --scope user) once the plugin is installed. Otherwise you
have two copies of every Diagrid tool.
The plugin requests the scopes catalyst:read catalyst:write offline_access. Without
offline_access there is no refresh token, so you sign in again each time the session
expires. Write tools, such as diagrid_apply, are left out of the tool list entirely
when your role is read-only or the sign-in did not grant write scope. If they are
missing, sign in again and approve write access; if they are still missing, your role is
read-only.
Check it worked by asking: "Who am I in Diagrid?" The answer comes from
diagrid_whoami.
Connect other clients to the remote MCP server
Every client connects to the same remote server, https://mcp.cloud.r1.diagrid.io/mcp
(the r1 is required), and signs in with OAuth in the browser. The authorization server
does not accept dynamic registration, so a client that tries to register itself fails.
Each client below uses its registered client ID instead: codex, copilot-cli, vscode,
claude-code, or claude-web for claude.ai. VS Code and the Copilot CLI can also sign in
without one, because the server reads the client metadata they publish.
Each snippet below also sets an X-Diagrid-Plugin-Version header to the plugin version,
which lets the server see which version of these instructions a client was set up from.
It goes only on the MCP requests the client already makes. When you update the skills,
update the header to match. If you set up a client for 0.8.x, the header's name changed
as well. See Upgrading from 0.8.x.
Install the skills for the client first (below), then:
Codex
codex mcp add diagrid --url https://mcp.cloud.r1.diagrid.io/mcp --oauth-client-id codex
codex mcp login diagrid
codex mcp add has no header flag, so add this to ~/.codex/config.toml under the
server it just wrote:
[mcp_servers.diagrid.http_headers]
X-Diagrid-Plugin-Version = "0.10.2"
GitHub Copilot CLI
copilot mcp add has no client-ID flag, so add the server and then set oauthClientId in
~/.copilot/mcp-config.json:
{
"mcpServers": {
"diagrid": {
"type": "http",
"url": "https://mcp.cloud.r1.diagrid.io/mcp",
"headers": { "X-Diagrid-Plugin-Version": "0.10.2" },
"oauthClientId": "copilot-cli",
"tools": ["*"]
}
}
}
Then run /mcp inside Copilot and authenticate the server in the browser.
VS Code (Copilot Chat), in .vscode/mcp.json or your user MCP configuration:
{
"servers": {
"diagrid": {
"type": "http",
"url": "https://mcp.cloud.r1.diagrid.io/mcp",
"headers": { "X-Diagrid-Plugin-Version": "0.10.2" },
"oauth": { "clientId": "vscode" }
}
}
}
VS Code opens a browser for authorization on the first connection. See the VS Code MCP configuration reference.
claude.ai and Claude Desktop: in claude.ai, open Settings → Connectors → Add custom
connector, enter the URL above, and under Advanced settings set the OAuth client ID
to claude-web. Then Connect and sign in. Claude Desktop uses the connectors of the
same account. Without the client ID, the connector tries to register itself and the
sign-in fails. Custom connectors cannot set request headers, so this one sends no
X-Diagrid-Plugin-Version. This route gives you the MCP tools only; the skills need
a client from Install. Verified on claude.ai on 2026-10-29: the connector
signed in and the chat could say who was signed in to Diagrid. Claude Desktop shares
those connectors but has not been tried separately.
Anything else (Gemini CLI, Zed, Antigravity and so on): add the URL as a remote (streamable HTTP) MCP server in that client's own MCP setup and use its MCP sign-in.
The server is also listed in the official MCP Registry as io.diagrid/mcp
(search the registry),
so clients with a registry-backed server gallery can find it there. The earlier entry,
io.diagrid/catalyst, points at the same URL and is superseded by io.diagrid/mcp.
Moving from catalyst-ai
0.10.0 renamed the plugin from catalyst-ai to diagrid. Claude Code treats a renamed
plugin as a new one, so claude plugin update does not move you across. The
catalyst-ai entry stays in the marketplace, held at its final release, 0.9.1. That release
still works, gets no new skills, and at the start of every session shows these steps
as one command, with a reminder to sign in again through /mcp.
claude plugin marketplace update diagrid
claude plugin install diagrid@diagrid
claude plugin uninstall catalyst-ai@diagrid
Uninstall the old plugin. With both installed, every skill and every tool shows up twice.
Then run /mcp, and if plugin:diagrid:diagrid shows it needs authentication, pick it
and sign in. The commands are now /diagrid:try-workflow and /diagrid:try-agent, and the
skills are diagrid:diagrid-deploy, diagrid:diagrid-setup and so on.
In Codex, Copilot and the other clients that install with npx skills add, run your
client's install command below again. It adds the diagrid-* skills but leaves the old
catalyst-* folders in place, so the agent sees every skill twice until you delete them
from the directory the installer wrote:
rm -rf .agents/skills/catalyst-* # a per-project install
rm -rf ~/.copilot/skills/catalyst-* # a Copilot install with --global
Upgrading from 0.8.x
0.9.0 renamed two things. A client set up for 0.8.x needs both of them changed.
-
The header. The server chooses tool names by the header a request sends. A request that still sends the old
X-Catalyst-Plugin-Versionheader gets the oldcatalyst_*tool names. The 0.9.0 skills call onlydiagrid_*tools, so every call they make fails as an unknown tool. Updating the version number on the old header does not fix this. Replace the header itself withX-Diagrid-Plugin-Version, set to the current version:- Codex: in
~/.codex/config.toml, find thehttp_headerstable under your Catalyst server and change the key toX-Diagrid-Plugin-Version. - Copilot CLI (
~/.copilot/mcp-config.json) and VS Code (mcp.json): change the key in that server'sheaders.
You can also remove the old entry and add the server again from the snippets above.
- Codex: in
-
The server name in Claude Code. 0.9.0 registered the server as
plugin:catalyst-ai:diagrid, and 0.10.0 renamed the plugin itself. Follow Moving from catalyst-ai.
To check, ask "Who am I in Diagrid?" The answer should come from diagrid_whoami.
GitHub Copilot CLI
npx -y skills add diagridio/diagrid-ai --agent github-copilot --skill '*' --global --yes
Use repeated --agent flags if you pass more than one. The comma form
(-a codex,github-copilot) is what the upstream README documents, and it prints
Invalid agents:, installs nothing and exits 1 — so it fails honestly, and a step
checking the exit code catches it. Re-measured on 1.5.22 and 1.5.23; an earlier version
of this line claimed exit 0, which was a measurement error.
The failure that is silent is a missing -y where nothing can answer the prompt, which
is every CI runner: it prints Done!, installs zero skills, and exits 0. Pass -y,
and assert a skill count rather than an exit code.
--global writes all twelve skills to ~/.copilot/skills/. Copilot should read them in
every project from there. Not yet verified: we have checked only that the installer
writes that directory, not that Copilot loads skills from it. Check that Copilot sees them:
copilot skill list # expect all 12
If it shows none, run the per-project command (without --global) from the repository
root.
Without --global the skills go into .agents/skills/ under the folder you ran the
command in. Copilot reads project skills only at the root of the repository it is working
in, so an install from a subfolder, or from a folder Copilot does not treat as that root,
leaves it with no skills and no error. Don't rely on npx skills list for this —
its "Agents:" line only names agents it detects as installed on your machine, so it
will quietly leave out a client you haven't installed yet.
Gemini CLI, Zed and Antigravity
These read the shared .agents/skills/ project directory, not ~/.copilot/skills/, so
install per project, from your repository's root:
npx -y skills add diagridio/diagrid-ai --agent github-copilot --skill '*' --yes
Without --global, the github-copilot target writes that shared directory.
VS Code (Copilot Chat)
Not yet verified: we have not checked whether VS Code Copilot Chat reads skills from
~/.copilot/skills/, from .agents/skills/ at the workspace root, or both. Until then,
run the per-project command above from your workspace root, which writes .agents/skills/.
Codex
npx -y skills add diagridio/diagrid-ai --agent codex --skill '*' --yes
.agents/skills/ is Codex's project skills directory too — the installer maps codex
there by design, so seeing no .codex/ created is correct rather than a failed install.
Codex reads them: codex debug prompt-input renders the model-visible prompt, and all of them
appear in its <skills_instructions> block with their descriptions intact, byte for byte.
Codex's own guidance text says automatic skill selection is allowed by default, so you
shouldn't have to name a skill — though nobody has yet confirmed that from a real session.
What is and is not verified, per client
| skills install | skills register | a question answered | |
|---|---|---|---|
| Claude Code 2.1.241 | ✅ 4.7 s | ✅ 10/10 | ✅ right skill fires unprompted, grounded answer |
| Codex 0.149.0 | ✅ 2.0 s | ✅ 10/10, in the model-visible prompt | not yet verified |
| GitHub Copilot 1.0.80 | ✅ 2.0 s (per-project install; --global not yet re-measured) | ✅ 10/10 | not yet verified |
These were measured with the first ten skills. diagrid-app-tunnels and
diagrid-agent-harness have not been re-measured on these clients yet.
If you can get Codex or Copilot to answer a Diagrid question, that is the single most useful thing you can report — with the wording you used and which skill fired. A skill that never fires looks identical to a session where nothing relevant came up, which is why this needs a human rather than an installer's exit code.
Also in this marketplace: dapr-skills
This marketplace lists a second plugin,
dapr-skills: the same subjects on
open-source Dapr — scaffold a new app, add Dapr to an existing one, migrate a
TypeScript service onto Dapr building blocks, and review Dapr Workflow, pub/sub and
durable agent code that runs on your own machine under the Dapr CLI or .NET Aspire.
claude plugin install dapr-skills@diagrid
They are built to sit side by side. Each dapr-skills skill that overlaps with one here
says so in its description and points at this plugin for anything that runs on Diagrid,
which is meant to keep the two from both firing on the same question. Nothing in CI checks
that across repos yet, so if both plugins answer one request, please report it. The
dapr-skills source is pinned to a commit in
marketplace.json and moves only through a reviewed
change here.
Then just ask
New to Diagrid? In Claude Code, type one of these to see a crash-and-recover run end to end. Each is a single line, so there's nothing to paste:
/diagrid:try-workflow: a durable workflow crashes mid-run and resumes where it stopped./diagrid:try-agent: the same for a durable AI agent. It defaults to LangGraph, which needs no API key. Name a framework from catalyst-quickstarts to get that one instead:/diagrid:try-agent crewai.
In other clients, paste the matching prompt from commands/. It's the same
text. The agent prompt opens with "Use the agent framework I named in my message", so add
that name to what you paste — Use crewai. on the end does it.
After that, you don't learn commands. Try:
Set up Diagrid, then show me what's in my project.
or
Add a workflow to this repo that charges a card, books a room, and compensates if the booking fails.
or
My workflow run failed. Why?
The skills fire on their own from what you ask. You shouldn't need to name one — if you find yourself having to, that's a bug worth reporting (see Feedback).
What's in it
| skill | what it's for |
|---|---|
diagrid-setup | Connect this session to Diagrid and confirm it works |
diagrid-workflow-scaffold | Add a Dapr Workflow — orchestrator, activities, project wiring |
diagrid-workflow-from-diagram | Turn a flowchart, sequence diagram, BPMN file or whiteboard photo into a workflow |
diagrid-agent-scaffold | Stand up a Durable Agent as your own app, fronted by a Diagrid agent |
diagrid-agent-harness | Make your own agent loop durable — every model call and tool call its own activity |
diagrid-develop | The edit → rerun → observe loop against live Diagrid infrastructure |
diagrid-app-tunnels | Let Diagrid call into a process on your machine: app to app invocation, pub/sub delivery, an agent calling an MCP server you run locally |
diagrid-deploy | Move an application from your laptop into Diagrid |
diagrid-operate | Inspect a running project, read-only |
diagrid-debug | Diagnose why something isn't working |
diagrid-workflow-determinism | Replay-safety rails for an orchestrator body |
diagrid-activity-idempotency | Make activities safe to run twice |
Language and framework are detected, not asked. There is no catalyst-workflow-python
skill — the workflow skill reads your repo and works out that it's a Python project.
Cost: roughly 1240 tokens always-on across all twelve (~103 each, estimated from the first ten), added to every
session whether or not a skill fires. Each skill costs a few thousand more only when it
actually fires. That figure is per model — claude plugin details resolves a tokenizer
from your active model, so the same ten descriptions cost ~103 each on Sonnet 5 and Opus 5
and ~68 each on Haiku 4.5. Quote the model with the number or it isn't reproducible.
What works today
Being explicit, because the gap matters and you'll notice it:
| status | |
|---|---|
| Authoring — workflows, agents | ✅ works now |
| Operating — inspect, debug, read runs | ✅ works now, through the MCP server |
| Determinism and idempotency review | ✅ works now |
| Creating, changing, deleting and deploying resources | ✅ diagrid_apply and diagrid_delete_resource, for a role that can write |
| Workflow-run actions and access control | ✅ for a role that can write |
| Running your app, agent or MCP server locally, calling out to Diagrid | ✅ works now, through diagrid_get_connection |
Letting Diagrid call into a process on your machine — an invocation target, a subscriber, an agent endpoint, the MCP server behind an MCPServer — and printing inbound requests | ✅ through an app tunnel, the one step that uses the Diagrid CLI (diagrid-app-tunnels) |
An agent calling an MCP server on your machine through Diagrid's workflow path (dapr.internal.mcp.* child workflows) | ⛔ the workflow path does not reach a tunneled MCP server yet; the skill points agents at Diagrid's HTTP MCP endpoint, which works |
| Logs | ⚠️ diagrid_get_logs only at the full data-sharing level, and only the sidecar's API calls |
| Invoking an app, publishing, reading or writing state, cluster diagnostics | ⛔ not available over MCP yet |
If something is not available over MCP yet, the skills say so in one line rather than improvising a route. If a write tool is missing, your role is read-only, not the connection broken.
Things the skills know that you might not
These are in the skills already; listed here because they're the ones that cost people hours, and they all fail silently or with an unhelpful error.
- Don't create a project. Your org already has a
defaultproject, provisioned at signup, with managed pub/sub, KV, workflow store and agent infrastructure. AProjectmanifest in a batch creates the project it names, and projects count against a per-region limit you can read withdiagrid_get_usage. - One pub/sub and one KV store per project, on every plan, free and paid alike, so no plan upgrade buys a second one. A multi-agent topology shares one pub/sub across topics. These are plan values overlaid per organization rather than constants in the code, so the skills read the live quota instead of asserting the 1.
- An
Agentfronts your app. It takes an endpoint and archive settings, not model settings — looking for an LLM setting means you have the wrong resource. - Enable the managed workflow store before the app exists. The sidecar reads
workflow config at boot, so enabling it later leaves
FAILED_PRECONDITIONon a sidecar that never gets retrofitted. - An Agent or MCP server must be created before anything else of its name. It won't adopt an identity it doesn't own, and then stays in error permanently.
- Identities are counted org-wide per region — one per app, agent and MCP server, all from the same allowance — so splitting a topology across projects buys nothing.
- Absent is not empty. At the default
metadatadata-sharing level, workflowinput,outputandcustomStatusare withheld, not empty. A run that shows no output may have produced plenty. - Connection values are for local dev only. A deployed app gets its own from the
platform. They go inline on the launch command, into a gitignored
.envin the app's folder, or through your tool's environment option, and never into chat, a pull request or a commit. - The skills use the Diagrid MCP tools for everything in Diagrid, except opening an app tunnel. Never a public tunnel (cloudflared, ngrok) for that: it bypasses the App ID's identity and access policy.
If your install is behind
Two different things go wrong here, with two different fixes. Start with
claude plugin list, because that's the command that reports what you actually have.
Your version is older than main. The marketplace is a git clone pinned at whatever
commit it last fetched, so an install from last week stays on last week's version, with
last week's skills. claude plugin install will not move it — it reports "already
installed" and changes nothing:
claude plugin marketplace update diagrid
claude plugin update diagrid@diagrid # the command that actually upgrades
claude plugin list # expect Version: 0.10.0 or later
Your version is right but skills are missing. Claude Code caches a plugin under its
declared version at ~/.claude/plugins/cache/<marketplace>/<plugin>/<version>/ and will
not refresh a version directory it already has. Measured: a half-populated version
directory served 4 skills of 10, while both marketplace update and plugin install
reported success and repaired nothing. Deleting the directory is the only fix:
rm -rf ~/.claude/plugins/cache/diagrid/diagrid
claude plugin install diagrid@diagrid
claude plugin details diagrid@diagrid # expect 12 skills
CI now fails any change to plugin content that doesn't bump the version, so the second one shouldn't recur.
Both fixes work the same way for the other plugin in this marketplace — substitute
dapr-skills@diagrid and ~/.claude/plugins/cache/diagrid/dapr-skills. The version it
reports is its own, set in its repository, not this one's.
Feedback
The most useful thing you can report is a skill that didn't fire when it should have, with the exact wording you used. That failure is invisible from our side — it looks identical to a session where nothing relevant happened — and the wording is the whole diagnosis.
Also worth reporting, in rough order of value:
- A tool a skill named that didn't exist or didn't work. Every
diagrid_*name is checked in CI againstcontracts/diagrid-mcp-tools.txt, so a mismatch means the server changed or the check has a hole. Both are worth catching. - A skill that fired when a different one should have.
- Anything a skill told you that turned out to be wrong.
Open an issue on this repository.
For a security problem, don't open an issue. See SECURITY.md.
Contributing
Gates run on every PR, each with its own test suite, and each exists because something
got past review or past claude plugin validate --strict in practice:
python3 scripts/lint_skills.py # the real gate
python3 scripts/test_lint_skills.py # proves the gate still catches what it claims
python3 scripts/check_mcp_surface.py # tools, CLI and hosts, across skills, evals and README
python3 scripts/test_check_mcp_surface.py
python3 scripts/check_version_bump.py # a plugin change must bump the version
python3 scripts/test_check_version_bump.py
python3 scripts/check_plugin_version_header.py # the MCP version header matches the plugin version
python3 scripts/test_check_plugin_version_header.py
python3 scripts/check_server_json.py # server.json: registry name, and the same URL as the plugin
python3 scripts/test_check_server_json.py
python3 scripts/test_plan_registry_version.py # the MCP Registry version planner
lint_skills.py enforces what a client actually needs: name matching its directory, a
parseable description under 260 characters, a frontmatter allow-list, no ../ links, every
link resolving when the skill is installed alone, and a 0.20 similarity cap between any
two descriptions so skills don't compete for the same trigger. It also bans a list of
substrings that each shipped somewhere and broke.
check_mcp_surface.py holds the skills, the evals and this README to the remote MCP
surface. Every diagrid_* name must appear in contracts/diagrid-mcp-tools.txt, which
is a copy of what the server's tools/list returns; update it when the server's tool list
changes. An old catalyst_* tool name, or the old server key catalyst, fails it.
contracts/catalyst-mcp-tools.txt keeps the same list under the old names, because
plugins up to 0.8.x still call them and the server's CI checks it still serves them; leave
it as it is until those names are retired. The gate also fails on any invocation of the
Diagrid CLI, except the tunnel commands (install check, sign-in and the two tunnel commands) inside
skills/diagrid-app-tunnels/ and evals/tunnel-*/, on anything
that points at a server other than the remote one, and on any host under Diagrid's
domains that is not on its allowlist (the MCP server, the console, the docs and downloads
hosts, and the main site).
Tool names are matched case-insensitively. The skills drive Diagrid only through the
remote MCP server, so where a capability has no tool, the skill says it is not available
over MCP yet instead of reaching for something else.
If you add a skill, or change any skill's content, bump version in
.claude-plugin/plugin.json. Everyone who already installed keeps the old content
otherwise, and nothing tells them. Every bump also changes the X-Diagrid-Plugin-Version
header: set it to the new version under mcpServers.diagrid.headers in plugin.json and
in the three snippets under the install steps here (Codex, Copilot CLI and VS Code) and
in the same three setups in skills/diagrid-setup/SKILL.md (check_plugin_version_header.py checks both).
To measure a run of the plugin, finish the Claude Code session and run
python3 scripts/session_metrics.py --latest from the same directory. It reads the session log
and prints a one-row Markdown table: tokens, model requests, tool calls, user turns and the skills loaded.
It prints counts and names only, never what was typed or a tool's arguments. It is not a gate;
python3 scripts/test_session_metrics.py tests it.
License
Apache-2.0. See LICENSE.
No installation packages available.