# Connect to the Catalyst MCP server

The Catalyst MCP server gives an AI agent a set of Catalyst tools over the [Model Context Protocol](https://modelcontextprotocol.io/) (see [MCP](https://docs.diagrid.io/concepts/mcp) for the concepts). With it, your agent can answer questions like "which workflow runs failed in my payments project?" and act on the answer, directly from your Catalyst organization. To also give the agent skills for building and deploying, see [Build with an AI coding agent](https://docs.diagrid.io/develop/local-development/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, as you. You add it to your agent and sign in.

This server exposes Catalyst itself as tools, to an agent you run. To put Catalyst in front of your own MCP server so your agents can call its tools, see [MCP on Catalyst](https://docs.diagrid.io/develop/mcp).

## Connect to the server

When you sign in, your browser opens: sign in with your Catalyst account, or create a free one. If you just created your account, verify your email, open [catalyst.diagrid.io](https://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`. Support for Cursor is coming soon. Use the URL exactly as shown, ending in `/mcp`.

**Claude Code**

If you installed the [Catalyst plugin](https://docs.diagrid.io/develop/local-development/ai-coding-agent), the server is already registered as `plugin:catalyst-ai:catalyst`. Run `/mcp` in Claude Code, choose it, and complete the sign-in in your browser. Keep that one entry, so your agent sees each Catalyst tool once.

To add the server on its own:

```bash
claude mcp add --transport http --scope user --client-id claude-code catalyst https://mcp.cloud.r1.diagrid.io/mcp
```

`--scope user` makes the server available in every project. Then run `/mcp`, choose `catalyst`, and sign in.

**Codex**

```bash
codex mcp add catalyst --url https://mcp.cloud.r1.diagrid.io/mcp --oauth-client-id codex
```

Then sign in in your browser:

```bash
codex mcp login catalyst
```

**VS Code (Copilot)**

:::note
Sign-in from VS Code is still being confirmed. This is the shape of the configuration.
:::

Add the server to `.vscode/mcp.json` in your workspace, or to your user MCP configuration:

```json
{
  "servers": {
    "catalyst": {
      "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.

**Copilot CLI**

```bash
copilot mcp add --transport http catalyst https://mcp.cloud.r1.diagrid.io/mcp
```

Then open `~/.copilot/mcp-config.json` and add `"oauthClientId": "copilot-cli"` to the `catalyst` entry, so Copilot signs in with its registered client ID:

```json
{
  "mcpServers": {
    "catalyst": {
      "type": "http",
      "url": "https://mcp.cloud.r1.diagrid.io/mcp",
      "oauthClientId": "copilot-cli",
      "tools": ["*"]
    }
  }
}
```

Then run `/mcp` in the Copilot CLI, choose `catalyst`, and choose **Authenticate** to sign in in your browser.

**Claude Desktop**

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.

When you sign in, you choose your Catalyst 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. If your role is read-only, the server lists the 28 read-only tools.

Ask your agent something that needs Catalyst to confirm the connection. "List my Catalyst projects" is enough.

## What the agent can do

The server exposes 41 tools, all named `catalyst_*`. Twenty-eight are read-only:

| Area | Tools |
|---|---|
| Account and usage | `catalyst_whoami`, `catalyst_get_usage` |
| Projects and regions | `catalyst_list_projects`, `catalyst_get_project`, `catalyst_get_region` |
| Apps and app tunnels | `catalyst_list_apps`, `catalyst_get_app`, `catalyst_list_app_tunnels` |
| Components | `catalyst_list_components`, `catalyst_get_component` |
| Workflows | `catalyst_list_workflows`, `catalyst_get_workflow`, `catalyst_list_workflow_runs`, `catalyst_get_workflow_run`, `catalyst_export_workflow_run` |
| Agents and token budgets | `catalyst_list_agents`, `catalyst_get_agent`, `catalyst_list_token_budgets` |
| MCP servers | `catalyst_list_mcp_servers`, `catalyst_get_mcp_server` |
| Access policies | `catalyst_list_access_policies`, `catalyst_get_access_policy` |
| Observability and audit | `catalyst_get_metrics`, `catalyst_get_logs`, `catalyst_list_audit_events` |
| Templates and manifests | `catalyst_list_templates`, `catalyst_get_template`, `catalyst_get_resource_schema` |

Twelve change something:

| Area | Tools |
|---|---|
| Resources | `catalyst_apply` creates or replaces resources from manifests, which is how the agent deploys an app. `catalyst_delete_resource` deletes one. |
| Access | `catalyst_grant_access` and `catalyst_revoke_access` change who can call an app, agent, or MCP server. |
| Workflow runs | `catalyst_start_workflow`, `catalyst_pause_workflow_run`, `catalyst_resume_workflow_run`, `catalyst_raise_workflow_event`, `catalyst_rerun_workflow_run`, `catalyst_rerun_workflow_runs`, `catalyst_terminate_workflow_run`, and `catalyst_purge_workflow_runs`. |

Every one of these is annotated as a write, so your agent can ask you before calling it. Deleting a resource, terminating a run, and purging runs are permanent, and are also annotated destructive.

Some changes take two calls. Deleting a project, 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.

One more tool is sensitive: `catalyst_get_connection` returns the connection values for an app, agent, or MCP server, so you can run it on your machine against Catalyst. It needs the same write access as the twelve above.

A read-only role sees the 28 read-only tools, and the Catalyst API checks every change against your role.

## Choose how much the agent sees

Everything a tool returns goes into your agent's context, and from there to its model provider. The data sharing level controls how much of a response the server returns:

- **`metadata`**: names, IDs, statuses, timestamps, and errors.
- **`full`**: everything in `metadata`, plus workflow `input`, `output`, and custom status, the values of inline component settings, and the `catalyst_get_logs` and `catalyst_export_workflow_run` tools. Those two belong to `full` 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. `full` adds the payloads, which often show why. The server redacts credentials at both levels.

The level is an organization setting, and it defaults to `metadata`. Contact Diagrid support to change it for your organization.

## Next steps

- [Build with an AI coding agent](https://docs.diagrid.io/develop/local-development/ai-coding-agent) — Install the Catalyst skills so your agent can build and deploy as well as inspect.
- [MCP on Catalyst](https://docs.diagrid.io/develop/mcp) — The other direction: put Catalyst in front of your own MCP server.