Skip to main content

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.

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.

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.

ScopeWhat it allows
catalyst:readThe read-only tools: list and describe resources, and read logs, metrics, and audit events.
catalyst:writeThe tools that create, change, or delete things, and the tool that returns an app's connection values.
offline_accessA 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:

ToolWhat it does
diagrid_whoamiShow the current Diagrid context: your organization, its projects, and its regions
diagrid_get_usageGet organization usage and limits
diagrid_list_projectsList projects
diagrid_get_projectGet a project
diagrid_get_regionGet a region
diagrid_list_appsList apps
diagrid_get_appGet an app
diagrid_list_app_tunnelsList app tunnels
diagrid_list_componentsList components
diagrid_get_componentGet a component
diagrid_list_workflowsList workflow definitions
diagrid_get_workflowGet a workflow definition
diagrid_list_workflow_runsList workflow runs
diagrid_get_workflow_runGet a workflow run
diagrid_export_workflow_runExport a workflow run's signed history
diagrid_list_agentsList agents
diagrid_get_agentGet an agent
diagrid_list_token_budgetsList token budgets
diagrid_list_mcp_serversList MCP servers
diagrid_get_mcp_serverGet an MCP server and its tools
diagrid_list_access_policiesList access policies in a project
diagrid_get_access_policyGet an access policy
diagrid_get_metricsGet project, app, agent, or MCP server metrics
diagrid_get_logsRead application logs
diagrid_list_audit_eventsList audit events
diagrid_list_templatesList templates
diagrid_get_templateGet a template
diagrid_get_resource_schemaGet a resource manifest's schema

Thirteen need write access. Twelve of them change something:

ToolWhat it doesDestructive
diagrid_applyCreate or replace resources from manifests, which is how the agent deploys an appYes
diagrid_delete_resourceDelete a resourceYes
diagrid_grant_accessGrant callers access to an app, agent, or MCP serverYes
diagrid_revoke_accessRevoke callers' access to an app, agent, or MCP serverYes
diagrid_start_workflowStart a workflow run
diagrid_pause_workflow_runPause a workflow run
diagrid_resume_workflow_runResume a workflow run
diagrid_raise_workflow_eventRaise an event on a workflow run
diagrid_rerun_workflow_runRerun a workflow run
diagrid_rerun_workflow_runsRerun several workflow runs
diagrid_terminate_workflow_runTerminate a workflow runYes
diagrid_purge_workflow_runsPurge workflow runsYes
diagrid_get_connectionGet 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 the diagrid_get_logs and diagrid_export_workflow_run tools. 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 in mcp.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.

Next steps​