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.

This page is about connecting external agents to OpenOps. For the AI assistant built into OpenOps, see AI Assistance.

Prerequisites

• An OpenOps environment with the MCP server enabled. If you administer the environment, see 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:

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.

Claude Code

Run the following command:

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:

{
  "mcpServers": {
    "openops": {
      "type": "http",
      "url": "https://<YOUR_OPENOPS_HOST>/mcp"
    }
  }
}

Run /mcp inside Claude Code and select openops:

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.

To remove the server later, run claude mcp remove openops.

Codex

Run the following commands:

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:

[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.

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.

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.

Authorizing access

When you authorize your agent for the first time:

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.

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.

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, 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 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

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.

Managing connected apps

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 or later. To upgrade, see 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 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:
   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:
   sudo docker compose down
   sudo docker compose up -d
   
4. Verify that the server is reachable:
   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 version 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 in the chart’s README. Then add the following to your values file and upgrade the release:

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 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.

Support

Feel free to join our Slack community if you have any questions or need help with your installation.