Connect to the Diagrid MCP server
The Diagrid MCP server gives an AI coding agent, such as Claude Code, Codex, or GitHub Copilot, a set of Diagrid tools over the Model Context Protocol (see MCP for the concepts). With it, your agent can list and inspect your projects, apps, agents, and workflow runs, deploy resources, and pause, rerun, or terminate runs, all in your Diagrid organization. It can answer a question like "which workflow runs failed in my payments project?" and act on the answer. To also give the agent skills for building and deploying, see Build with an AI coding agent.
Diagrid runs the server at https://mcp.cloud.r1.diagrid.io/mcp. Your agent connects over streamable HTTP and signs in with OAuth in your browser the first time it connects, as you. There is no API key to copy.
This server exposes Diagrid itself as tools, to an agent you run. To put Diagrid in front of your own MCP server so your agents can call its tools, see MCP on Diagrid.
Connect to the server
When you sign in, your browser opens: sign in with your Diagrid account, or create a free one. If you just created your account, verify your email, open catalyst.diagrid.io once to finish setting it up, and then authenticate again.
Each agent signs in with its own registered client ID: claude-code, codex, vscode, copilot-cli, or claude-web. For GitHub Copilot (VS Code and the Copilot CLI) you set that client ID in the server entry yourself, as shown in the tabs below. Support for Cursor is coming soon. Use the URL exactly as shown, ending in /mcp.
The examples name the server diagrid in your agent's configuration. The name is yours to choose; it only labels the entry in your agent.
- Claude Code
- Codex
- VS Code (Copilot)
- Copilot CLI
- Claude Desktop
If you installed the Diagrid AI plugin, the server is already registered as plugin:diagrid:diagrid. Run /mcp in Claude Code, choose it, and complete the sign-in in your browser. Keep that one entry, so your agent sees each Diagrid tool once.
To add the server on its own:
claude mcp add --transport http --scope user --client-id claude-code diagrid https://mcp.cloud.r1.diagrid.io/mcp
--scope user makes the server available in every project. Then run /mcp, choose diagrid, and sign in.
codex mcp add diagrid --url https://mcp.cloud.r1.diagrid.io/mcp --oauth-client-id codex
Then sign in in your browser:
codex mcp login diagrid
Add the server to .vscode/mcp.json in your workspace, or to your user MCP configuration by running MCP: Open User Configuration from the Command Palette:
{
"servers": {
"diagrid": {
"type": "http",
"url": "https://mcp.cloud.r1.diagrid.io/mcp",
"oauth": { "clientId": "vscode" }
}
}
}
VS Code opens the sign-in in your browser the first time it connects. Keep the oauth.clientId line, so VS Code signs in with its registered client ID. If VS Code tries to register itself instead, sign-in fails with Authorization server does not support dynamic client registration.
Add the server to ~/.copilot/mcp-config.json. Create the file if it does not exist, or merge the diagrid entry into your existing mcpServers object:
{
"mcpServers": {
"diagrid": {
"type": "http",
"url": "https://mcp.cloud.r1.diagrid.io/mcp",
"oauthClientId": "copilot-cli",
"tools": ["*"]
}
}
}
You can also run copilot mcp add --transport http diagrid https://mcp.cloud.r1.diagrid.io/mcp and then add the oauthClientId line to the diagrid entry it writes.
Then run /mcp in the Copilot CLI, choose diagrid, and choose Authenticate to sign in in your browser. Keep the oauthClientId line, so the Copilot CLI signs in with its registered client ID. If it tries to register itself instead, sign-in fails with Authorization server does not support dynamic client registration.
In Claude Desktop or on claude.ai, add a custom connector with the URL https://mcp.cloud.r1.diagrid.io/mcp. Under Advanced settings, set the OAuth client ID to claude-web and leave the client secret empty. Then connect, and complete the sign-in.
Ask your agent something that needs Diagrid to confirm the connection. "List my Diagrid projects" is enough.
What you approve when you sign in
When you sign in, you choose your Diagrid organization and approve the agent's access. After that, the agent acts as you: it reaches the projects your account can reach, and your role limits what it can change.
The sign-in asks for these OAuth scopes. Their names still start with catalyst; they were not renamed with the tools.
| Scope | What it allows |
|---|---|
catalyst:read | The read-only tools: list and describe resources, and read logs, metrics, and audit events. |
catalyst:write | The tools that create, change, or delete things, and the tool that returns an app's connection values. |
offline_access | A refresh token, so your agent stays signed in instead of asking you again each time the session expires. |
The server leaves the write tools out of the tool list entirely unless your sign-in granted catalyst:write and your role can write. With a read-only role, or without write consent, your agent sees the 28 read-only tools. If write tools are missing, sign in again and approve write access. If they are still missing, your role is read-only.
What the agent can do
The server exposes 41 tools, all named diagrid_*. Twenty-eight only read:
| Tool | What it does |
|---|---|
diagrid_whoami | Show the current Diagrid context: your organization, its projects, and its regions |
diagrid_get_usage | Get organization usage and limits |
diagrid_list_projects | List projects |
diagrid_get_project | Get a project |
diagrid_get_region | Get a region |
diagrid_list_apps | List apps |
diagrid_get_app | Get an app |
diagrid_list_app_tunnels | List app tunnels |
diagrid_list_components | List components |
diagrid_get_component | Get a component |
diagrid_list_workflows | List workflow definitions |
diagrid_get_workflow | Get a workflow definition |
diagrid_list_workflow_runs | List workflow runs |
diagrid_get_workflow_run | Get a workflow run |
diagrid_export_workflow_run | Export a workflow run's signed history |
diagrid_list_agents | List agents |
diagrid_get_agent | Get an agent |
diagrid_list_token_budgets | List token budgets |
diagrid_list_mcp_servers | List MCP servers |
diagrid_get_mcp_server | Get an MCP server and its tools |
diagrid_list_access_policies | List access policies in a project |
diagrid_get_access_policy | Get an access policy |
diagrid_get_metrics | Get project, app, agent, or MCP server metrics |
diagrid_get_logs | Read application logs |
diagrid_list_audit_events | List audit events |
diagrid_list_templates | List templates |
diagrid_get_template | Get a template |
diagrid_get_resource_schema | Get a resource manifest's schema |
Thirteen need write access. Twelve of them change something:
| Tool | What it does | Destructive |
|---|---|---|
diagrid_apply | Create or replace resources from manifests, which is how the agent deploys an app | Yes |
diagrid_delete_resource | Delete a resource | Yes |
diagrid_grant_access | Grant callers access to an app, agent, or MCP server | Yes |
diagrid_revoke_access | Revoke callers' access to an app, agent, or MCP server | Yes |
diagrid_start_workflow | Start a workflow run | |
diagrid_pause_workflow_run | Pause a workflow run | |
diagrid_resume_workflow_run | Resume a workflow run | |
diagrid_raise_workflow_event | Raise an event on a workflow run | |
diagrid_rerun_workflow_run | Rerun a workflow run | |
diagrid_rerun_workflow_runs | Rerun several workflow runs | |
diagrid_terminate_workflow_run | Terminate a workflow run | Yes |
diagrid_purge_workflow_runs | Purge workflow runs | Yes |
diagrid_get_connection | Get the connection for running an app, agent, or MCP server locally |
Every one of these is annotated as a write, so your agent can ask you before calling it. The tools marked destructive are also annotated destructive, because they replace, remove, or permanently end something: a replace drops fields the manifest leaves out, a grant or revoke of * opens or closes an app or agent to every caller not listed, and deletes, purges, and terminations cannot be undone.
Some changes take two calls. Deleting a resource, purging runs, and rerunning several runs at once first return a preview of what would change, with a confirmation code. The change happens when the agent calls again with that code, so the agent can show you the preview first.
diagrid_get_connection changes nothing, but it is sensitive: it returns the connection values, including the API token, for an app, agent, or MCP server, so you can run it on your machine against Diagrid. That is why it needs the same write access as the twelve tools above. Your agent sets the values in the process's environment; never paste the token into chat, pull requests, or commits.
The Diagrid API checks every call against your role, whatever tools your agent sees.
Choose how much the agent sees
Everything a tool returns goes into your agent's context, and from there to its model provider. Your organization's Data shared with AI tools setting controls how much of a response the server returns:
- Metadata: names, IDs, statuses, timestamps, and errors. Workflow
input,output, and custom status are marked as withheld, so the agent can tell a withheld value from an empty one. - Metadata and application data: everything in Metadata, plus workflow
input,output, and custom status, the values of inline component settings, and thediagrid_get_logsanddiagrid_export_workflow_runtools. Those two tools need the higher level because a log line is whatever your application printed, and an exported run carries its payloads.
Metadata shows your agent that a run failed and where. Metadata and application data adds the payloads, which often show why. The server removes credentials at both levels.
The setting defaults to Metadata. An organization admin changes it on the Organization Overview page in the Diagrid Console, and it is the most any MCP client in your organization can read. When you sign in, the consent screen lets you pick a lower level for that one connection. What each level allows is listed in Data shared with AI tools.
Tool names before the rename
The server was previously named catalyst-management, and its tools were named catalyst_*, for example catalyst_whoami. They are now named diagrid and diagrid_*. Each tool keeps the rest of its name and does the same thing. The URL and the OAuth scopes did not change.
The catalyst_* names are deprecated. The server still uses them only for versions 0.7.3 to 0.8.1 of the Diagrid AI plugin, which identify themselves with a request header, so those versions keep working. Move to the current plugin to get the diagrid_* names.
Every other client, including one you added by hand, gets the diagrid_* names. If a prompt, a script, or a tool permission rule in your agent names a catalyst_* tool, change it to the diagrid_* name. An existing server entry named catalyst keeps working; the entry's name does not affect the tool names.
The catalyst_* names will be removed in a later release. This page will give the date once it is set.
Troubleshooting
Sign-in fails with Authorization server does not support dynamic client registration
Symptom: You added the Diagrid MCP server to GitHub Copilot and sign-in fails with Authorization server does not support dynamic client registration.
Cause: Diagrid does not let clients register themselves. Each supported agent signs in with a client ID Diagrid registered for it. When the server entry does not set it, Copilot tries to register itself instead.
Fix: Set the client ID in the diagrid entry, then sign in again.
- VS Code: add
"oauth": { "clientId": "vscode" }to the entry inmcp.json. - Copilot CLI: add
"oauthClientId": "copilot-cli"to the entry in~/.copilot/mcp-config.json.
The full entries are in the VS Code and Copilot CLI tabs. If you installed the Diagrid AI plugin into Copilot, it registered a diagrid server set up for Claude Code. Disable that server and add the user-level entry above instead, because edits to a plugin's own files are overwritten when the plugin updates. If you installed only the skills with npx skills add, add the entry above.