Connecting AI Agents via MCP

Overmind provides a Model Context Protocol (MCP) server that lets AI-powered tools — such as Cursor, Claude Desktop, and other MCP-compatible clients — interact with your Overmind account. Your AI agent can list changes, inspect risks, review blast radius analysis, check connected sources, and even update change metadata or submit risk feedback, all through natural language.

How it Works

The Overmind MCP server is a remote, HTTPS-based endpoint that uses the Streamable HTTP transport. When your MCP client connects for the first time it performs an OAuth 2.0 authorization flow (PKCE) so that every request is scoped to your Overmind account.

The server exposes two kinds of capabilities:

• Tools — dynamic actions your AI agent can invoke (e.g. "list my recent changes", "get the risks for change X").
• Resources — read-only reference data (in the MCP protocol sense, not infrastructure resources) your agent can load as context (e.g. account info, connected sources).

tip

The MCP server gives your AI agent read access to change analysis results and infrastructure metadata, plus the ability to update change metadata and submit risk feedback. To create new changes or start analysis, use the Overmind CLI (overmind terraform plan or overmind changes submit-plan).

Prerequisites

• An Overmind account
• An MCP-compatible AI client (see Supported Clients below)

Quick Start

Cursor

Add the following to your Cursor MCP configuration (.cursor/mcp.json in your project, or your global Cursor settings):

{
  "mcpServers": {
    "overmind": {
      "url": "https://api.overmind.tech/api/mcp"
    }
  }
}

Cursor will handle OAuth authentication automatically. The first time you use an Overmind tool, Cursor will open a browser window for you to log in.

Claude Desktop

Add the following to your Claude Desktop configuration file (claude_desktop_config.json):

{
  "mcpServers": {
    "overmind": {
      "url": "https://api.overmind.tech/api/mcp"
    }
  }
}

Other MCP Clients

Any MCP client that supports remote Streamable HTTP servers with OAuth 2.0 can connect. Point it at:

https://api.overmind.tech/api/mcp

The server publishes OAuth Protected Resource Metadata (RFC 9728) at /.well-known/oauth-protected-resource/api/mcp, so spec-compliant clients can auto-discover the authorization server and required scopes.

Available Tools

Once connected, your AI agent has access to the following tools. You don't need to call them directly — just ask your agent questions in natural language and it will choose the right tool.

Change Analysis (read)

Tool	Description
list_changes	List recent infrastructure changes with pagination. Returns title, status, risk counts, and timestamps.
get_change	Get full details of a specific change by UUID — title, description, status, affected resources, planned changes.
get_change_risks	Get risks identified for a change, grouped by severity (high / medium / low).
get_hypotheses	Get investigation hypotheses formed during change analysis, with status and knowledge references.
get_change_timeline	Get the chronological analysis timeline for a change — blast radius, hypotheses, risk calculations.

Infrastructure Inventory (read)

Tool	Description
list_sources	List all connected infrastructure sources with status, type, and available resource types. Supports filtering by status or type.
get_source_status	Get detailed status of a specific source — version, health, heartbeat, and available types.
list_snapshots	List infrastructure snapshots for your account with resource and relationship counts.
get_snapshot	Get details of a specific snapshot. Optionally include full resource and relationship data (note: large snapshots may produce very large responses).

Write Operations

Tool	Description
update_change	Update metadata on an existing change — title, description, ticket link, or owner.
submit_risk_feedback	Submit positive or negative feedback on a specific risk to help improve future analysis.

Available Resources

MCP Resources are protocol-level context objects (distinct from the infrastructure resources in your cloud environment). They provide background information that your agent can load automatically.

Resource	Description
account://info	Basic account information — name, plan, and timestamps.
sources://list	All connected infrastructure sources with status and available resource types.
sources://{source_id}/types	Available resource types for a specific source (use the source UUID from sources://list).

Example Conversations

Here are some things you can ask your AI agent once it's connected to Overmind:

• "What are my recent infrastructure changes?" — The agent calls list_changes and summarizes your recent activity.
• "Show me the risks for my latest change" — The agent gets the most recent change, then fetches its risks.
• "Are any of my sources unhealthy?" — The agent calls list_sources with a status filter.
• "What was the blast radius analysis for change X?" — The agent calls get_change_timeline and get_hypotheses for the change.
• "Update the title of change X to 'Production DB migration'" — The agent calls update_change to set the new title.
• "That risk about target groups isn't relevant — mark it as negative feedback" — The agent calls submit_risk_feedback.

Authentication and Permissions

The MCP server uses your Overmind account's OAuth scopes to control access. Each tool requires specific permissions:

Scope	Tools
changes:read	list_changes, get_change, get_change_risks, get_hypotheses, get_change_timeline, list_snapshots, get_snapshot
changes:write	update_change, submit_risk_feedback
sources:read	list_sources, get_source_status, sources://list, sources://{source_id}/types
account:read	account://info

When you authenticate through your MCP client, the OAuth flow requests the scopes you need. If your account uses API keys, the key's configured permissions determine which tools are available.

On-Premises Deployments

If you are running Overmind on-premises, replace api.overmind.tech with your instance's API hostname:

{
  "mcpServers": {
    "overmind": {
      "url": "https://your-overmind-api-host/api/mcp"
    }
  }
}

Supported Clients

The Overmind MCP server works with any client that supports remote Streamable HTTP MCP servers. Tested clients include:

• Cursor — AI-powered code editor
• Claude Desktop — Anthropic's desktop app

As the MCP ecosystem grows, any client implementing the MCP specification with Streamable HTTP transport should work.

Troubleshooting

Authentication fails or loops

Make sure you're using the correct endpoint URL (https://api.overmind.tech/api/mcp). If you're behind a corporate proxy, ensure it allows connections to api.overmind.tech.

"Insufficient permissions" error on a tool

Your OAuth token or API key doesn't include the required scope for that tool. Check the permissions table above and ensure your token has the needed scopes.

No data returned from list_changes

Overmind only shows changes for your authenticated account. Make sure you have created at least one change — run overmind terraform plan in a Terraform project to generate your first analysis.

MCP client doesn't support remote servers

Some older MCP clients only support local (stdio) transports. The Overmind MCP requires a client that supports remote Streamable HTTP connections. Check your client's documentation for MCP remote server support.

Need more help? Join our Discord community or check our support documentation.