> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openops.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server

> How to connect AI agents such as Claude Code and Codex to OpenOps

OpenOps provides a Model Context Protocol (MCP) server that lets an AI agent running on your machine work with your OpenOps environment. Once connected, you can ask the agent about your workflows, runs, and connections, and have it act on them for you.

The agent never receives your OpenOps password. Instead, you approve access once in your browser, and you can revoke it at any time.

<Note>
  This page is about connecting external agents to OpenOps. For the AI assistant built into OpenOps, see [AI Assistance](/ai-assistance/overview).
</Note>

## Prerequisites

* An OpenOps environment with the MCP server enabled. If you administer the environment, see [Enabling the MCP server](#enabling-the-mcp-server).
* A user account in that OpenOps environment.
* An AI agent that can connect to remote MCP servers and sign in through your browser, such as Claude Code, Codex, or the Claude app.

Throughout this page, the MCP server URL is:

```text theme={null}
https://<YOUR_OPENOPS_HOST>/mcp
```

Replace `<YOUR_OPENOPS_HOST>` with the host you use to open OpenOps in your browser.

## Connecting your agent

There are two ways to add the OpenOps MCP server to an agent: run the agent's `add` command, or add an entry to its configuration file. Both point the agent at the same URL. After adding the server, authorize it once from the agent, as described in [Authorizing access](#authorizing-access).

<AccordionGroup>
  <Accordion title="Claude Code" defaultOpen>
    Run the following command:

    ```bash theme={null}
    claude mcp add --transport http openops https://<YOUR_OPENOPS_HOST>/mcp
    ```

    Alternatively, add the server to `.mcp.json` in your project, or to `~/.claude.json` for all projects:

    ```json theme={null}
    {
      "mcpServers": {
        "openops": {
          "type": "http",
          "url": "https://<YOUR_OPENOPS_HOST>/mcp"
        }
      }
    }
    ```

    Run `/mcp` inside Claude Code and select **openops**:

    <img src="https://mintcdn.com/openops-ecb4f397/xngKm1ZDlguCP8ZV/images/claude-code-mcp-list.png?fit=max&auto=format&n=xngKm1ZDlguCP8ZV&q=85&s=597fb28136f2ea1194f1742a54168891" alt="The /mcp server list in Claude Code" width="2164" height="794" data-path="images/claude-code-mcp-list.png" />

    Select **Authenticate**. Claude Code opens the OpenOps authorization page in your browser, where you grant access to the agent. Alternatively, run `claude mcp login openops` from your terminal.

    <img src="https://mintcdn.com/openops-ecb4f397/xngKm1ZDlguCP8ZV/images/claude-code-mcp-authenticate.png?fit=max&auto=format&n=xngKm1ZDlguCP8ZV&q=85&s=41fad31fede3be5975e546551e78c675" alt="The openops server details in Claude Code with the Authenticate option" width="2164" height="494" data-path="images/claude-code-mcp-authenticate.png" />

    To remove the server later, run `claude mcp remove openops`.
  </Accordion>

  <Accordion title="Codex">
    Run the following commands:

    ```bash theme={null}
    codex mcp add openops --url https://<YOUR_OPENOPS_HOST>/mcp
    codex mcp login openops
    ```

    Alternatively, add the server to `~/.codex/config.toml` and then run `codex mcp login openops`:

    ```toml theme={null}
    [mcp_servers.openops]
    url = "https://<YOUR_OPENOPS_HOST>/mcp"
    ```

    Codex doesn't start the authorization flow on its own, so the `login` command is required in both cases. The Codex CLI, the Codex IDE extension, and the ChatGPT desktop app share this configuration file.
  </Accordion>

  <Accordion title="Claude">
    In the Claude desktop or web app, go to **Settings → Connectors**, click **Add custom connector**, enter the server URL, and click **Add**. Then click **Connect** next to the OpenOps connector to authorize. To remove it later, open the connector's menu and choose **Remove**.
  </Accordion>

  <Accordion title="Other clients">
    Any client that can connect to a remote MCP server works with the same URL. Add the server the way you add other remote MCP servers in that client.
  </Accordion>
</AccordionGroup>

## Authorizing access

When you authorize your agent for the first time:

<img src="https://mintcdn.com/openops-ecb4f397/xngKm1ZDlguCP8ZV/images/access-llm-mcp-consent.png?fit=max&auto=format&n=xngKm1ZDlguCP8ZV&q=85&s=f1bb3b280dac18cec368145b85486ffd" alt="Authorize access dialog" width="2992" height="1432" data-path="images/access-llm-mcp-consent.png" />

1. When you start authorization from your agent, it opens OpenOps in your browser. If you're not logged in, log in first.
2. OpenOps shows the **Authorize access** dialog on the **Connected apps** settings page. The dialog names the application asking for access and lists what it will be able to do:
   * View your workflows, runs, and connections
   * Create and change workflows on your behalf
   * Run workflows and retry runs
   * Act in any project you have access to
3. Click **Allow access**. The browser returns control to the agent, which now has access to the OpenOps tools. To deny the request, click **Cancel** or close the dialog.

<Note>
  **Only approve requests you started:** The dialog shows the name of the application asking for access. If you didn't start connecting from that application, click **Cancel**.
</Note>

Access is renewed automatically while the agent is in use. You're asked to approve again only if you disconnect the agent in [Connected apps](#managing-connected-apps), your account is deactivated, or the agent isn't used for 30 days.

## Using your agent with OpenOps

Once connected, ask your agent about your OpenOps environment in plain language. For example:

* "Which workflows are enabled in my OpenOps environment, and what do they do?"
* "Show me the failed runs of the EBS gp2 to gp3 migration workflow from this week and explain why they failed."
* "Retry the run that failed this morning."
* "Which connections does the Slack notification workflow use?"
* "Create a workflow that finds unattached Elastic IPs every Monday and posts them to Slack, then test the first step." (Enterprise edition)
* "Switch to the Production workspace and list its workflows." (Enterprise edition)

### What the agent can do

The tools available to the agent depend on your OpenOps edition. See [pricing](https://www.openops.com/pricing/) for the differences between editions.

| Capability                                      | Community | Enterprise |
| ----------------------------------------------- | --------- | ---------- |
| List and inspect workflows                      | Yes       | Yes        |
| List runs, inspect run details, and retry a run | Yes       | Yes        |
| List, inspect, and update connections           | Yes       | Yes        |
| Create workflows, add, update, and delete steps | No        | Yes        |
| Test a step or start a test run of a workflow   | No        | Yes        |
| Work in more than one workspace                 | No        | Yes        |

<Note>
  **Workspaces (Enterprise edition):** An authorized agent isn't limited to one workspace. Name the workspace you want to work in, and the agent passes it along with each request. If you don't name one, the agent acts in your default workspace.
</Note>

## Managing connected apps

<img src="https://mintcdn.com/openops-ecb4f397/xngKm1ZDlguCP8ZV/images/access-llm-mcp-connected-apps.png?fit=max&auto=format&n=xngKm1ZDlguCP8ZV&q=85&s=39a978a6a7e63ef75deb202dcc3eec43" alt="Connected apps" width="2992" height="854" data-path="images/access-llm-mcp-connected-apps.png" />

Every agent you authorize appears in OpenOps, where you can review and disconnect it:

1. In the OpenOps left sidebar, click the **Settings** icon at the bottom.
2. In the **Settings** view, click **Connected apps**. Each entry shows the application name, when it was connected, and when it was last used. If you connect the same agent from two machines, you see two entries.
3. To revoke access, click **Disconnect** next to an entry and confirm. The agent loses access immediately and has to be authorized again to reconnect. Other connected apps aren't affected.

Removing the server from your agent's configuration doesn't revoke the agent's access in OpenOps. The agent stays listed in **Connected apps** until you disconnect it there. To fully disconnect, do both.

## Enabling the MCP server

This section is for OpenOps administrators. The MCP server is disabled by default and requires OpenOps [0.7.0](https://github.com/openops-cloud/openops/releases/tag/0.7.0) or later. To upgrade, see [Updating OpenOps](/getting-started/updating-openops). Agents sign in through OAuth, which OpenOps serves only over HTTPS; plain `http` is accepted only when `OPS_PUBLIC_URL` is `http://localhost`.

### Docker Compose

1. Enable TLS for your installation. See [Enabling TLS](/getting-started/deployment/aws-ec2#enabling-tls) in the deployment guide.
2. Open the `.env` file in your OpenOps installation directory and set the following variables. If your installation was created before 0.7.0, the variables aren't in the file yet, so add them:
   ```shell theme={null}
   OPS_OAUTH_ENABLED=true
   OPS_OAUTH_ISSUER_URL=${OPS_PUBLIC_URL}/api
   OPS_MCP_RESOURCE_URL=${OPS_PUBLIC_URL}/mcp
   OPS_OAUTH_RS_CLIENT_SECRET=<random value of at least 32 characters>
   COMPOSE_PROFILES=mcp
   ```
   Generate the secret with `openssl rand -hex 32`. The MCP container doesn't start while the secret is empty. `COMPOSE_PROFILES=mcp` makes `docker compose up -d` start the MCP container.
3. After making any changes to the `.env` file, restart the OpenOps containers:
   ```shell theme={null}
   sudo docker compose down
   sudo docker compose up -d
   ```
4. Verify that the server is reachable:
   ```shell theme={null}
   curl https://<YOUR_OPENOPS_HOST>/.well-known/oauth-protected-resource/mcp
   ```
   The command returns a JSON document that names your host as the `resource`. A `502 Bad Gateway` response means the MCP container isn't running. Check that `COMPOSE_PROFILES=mcp` is set and the secret isn't empty, then inspect the container with `sudo docker compose logs openops-mcp`.

To disable the MCP server, set `OPS_OAUTH_ENABLED=false`, remove the `COMPOSE_PROFILES=mcp` line, and run `sudo docker compose --profile mcp down` followed by `sudo docker compose up -d`. All connected agents lose access.

### Helm chart

The [OpenOps Helm chart](https://github.com/openops-cloud/helm-chart) version [0.7.0](https://github.com/openops-cloud/helm-chart/releases/tag/0.7.0) or later includes the MCP server as an opt-in component. Your release must already serve OpenOps over HTTPS, whether through the chart's ingress TLS settings or a load balancer that terminates TLS. See [TLS/HTTPS configuration](https://github.com/openops-cloud/helm-chart#tlshttps-configuration) in the chart's README. Then add the following to your values file and upgrade the release:

```yaml theme={null}
global:
  publicUrl: "https://<YOUR_OPENOPS_HOST>"

openopsEnvSecrets:
  OPS_OAUTH_RS_CLIENT_SECRET: "<random value of at least 32 characters>"

mcp:
  enabled: true
```

The chart derives the remaining OAuth settings from `publicUrl`. See [MCP server for external agents](https://github.com/openops-cloud/helm-chart#mcp-server-for-external-agents) in the chart's README for details, including how to supply the secret from an external secret manager.

## Troubleshooting

* **The agent reports that the server needs authentication:** Run the agent's login step, such as `/mcp` in Claude Code or `codex mcp login openops`, and check that the server URL ends with `/mcp`.
* **The browser shows "This authorization request cannot be completed":** The request has expired or has already been used. Connect again from your agent.
* **Tool calls fail with an authorization error after working before:** The agent was disconnected in **Connected apps**, your user account was deactivated, or the agent hasn't been used for 30 days. Connect again from your agent.
* **The agent works in the wrong workspace (Enterprise edition):** Name the workspace in your prompt. See the note in [What the agent can do](#what-the-agent-can-do).

## Support

Feel free to join our [Slack community](https://slack.openops.com) if you have any questions or need help with your installation.