opa-mcp-server

# OPA MCP Server

[![CI](https://github.com/OrygnsCode/opa-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/OrygnsCode/opa-mcp-server/actions/workflows/ci.yml)
[![CodeQL](https://github.com/OrygnsCode/opa-mcp-server/actions/workflows/codeql.yml/badge.svg)](https://github.com/OrygnsCode/opa-mcp-server/actions/workflows/codeql.yml)
[![npm version](https://img.shields.io/npm/v/@orygn/opa-mcp.svg)](https://www.npmjs.com/package/@orygn/opa-mcp)
[![Docker pulls](https://img.shields.io/docker/pulls/orygn/opa-mcp.svg)](https://hub.docker.com/r/orygn/opa-mcp)
[![OPA Ecosystem](https://img.shields.io/badge/OPA-ecosystem-blue.svg)](https://www.openpolicyagent.org/ecosystem/entry/opa-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
[![Node.js](https://img.shields.io/node/v/@orygn/opa-mcp.svg)](./package.json)
[![opa-mcp-server MCP server](https://glama.ai/mcp/servers/OrygnsCode/opa-mcp-server/badges/score.svg)](https://glama.ai/mcp/servers/OrygnsCode/opa-mcp-server)

A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server
that turns any MCP-compatible client (Claude Desktop, Claude Code, Cursor,
VS Code, Windsurf, Zed, and others) into a first-class
[Open Policy Agent](https://www.openpolicyagent.org/) and Rego authoring
environment.

```
+--------------------+ MCP/stdio  +-----------------+ spawn/HTTP +---------------------+
|  Claude · Cursor · |----------> | @orygn/opa-mcp  |----------> | opa · regal         |
|   VS Code · ...    |<---------- |                 |<---------- | conftest · REST API  |
+--------------------+  52 tools  +-----------------+            +---------------------+
```

> **Status:** v0.7.0. Tool surface, error codes, and
> environment variables follow [SemVer](https://semver.org/) from
> v0.1.0 forward.

> **Upgrading to 0.7.0:** Node.js 22 or later is required. The bundled OPA
> is 1.21, which reads YAML against the 1.2 schema: bare `yes`, `no`, `on`
> and `off` in data files are strings now, not booleans. If you supply your
> own binary via `OPA_BINARY` or `PATH`, only the Node requirement applies.

> **Upgrading to 0.6.0:** `rego_bench` reports `iterations`, `nsPerOp`,
> `allocsPerOp` and `bytesPerOp`. The fields opa prints (`N`, `T`, `Bytes`,
> `MemAllocs`, `MemBytes`, `Extra`) were top-level and now sit under `raw`
> for a single run, so anything that read them from the top level has to
> look there. With `count` above one, `raw` is omitted: every document is in
> `runs`, and `fastest` indexes the one the top-level figures come from.

> **Upgrading to 0.4.0:** subprocesses no longer inherit the server's
> environment. A policy that read a variable through `opa.runtime().env`
> will no longer see it; name the variable in `OPA_MCP_PASSTHROUGH_ENV` if
> it is genuinely needed. See the security section for why.

> **Upgrading to 0.3.0:** the bundled OPA is now 1.19, so Rego v0 policies
> no longer parse (`if` is required before a rule body, `contains` before a
> partial set). Run `rego_migrate_v1` to convert them. If you supply your own
> binary via `OPA_BINARY` or `PATH`, nothing changes.

---

## Table of contents

- [What you can do with it](#what-you-can-do-with-it)
- [Why this MCP](#why-this-mcp)
- [Install](#install)
- [Configuration](#configuration)
- [Tool reference](#tool-reference)
- [Prompts](#prompts)
- [Resources](#resources)
- [Cookbook](#cookbook)
- [Architecture](#architecture)
- [Security](#security)
- [Troubleshooting](#troubleshooting)
- [Development](#development)
- [Versioning & support](#versioning--support)
- [License](#license)

## What you can do with it

Once an MCP client is connected, an agent can:

- **Author Rego.** Generate, format, and refactor policies. The server
  runs the real `opa fmt` and `opa parse` so output is byte-identical to
  what you'd get on the command line, and `regal` (optional) surfaces
  idiomatic suggestions.
- **Evaluate against data.** Run a query against a policy and an input
  document. Optional `--explain`, `--profile`, and `--coverage` flags
  surface execution traces, hot rules, and per-line coverage.
- **Debug a deny.** `rego_explain_decision` walks the agent through every
  rule that fired (and every one that didn't), so it can answer "why was
  this rejected" without you reading the trace by hand.
- **Manage policies on a running OPA.** List, get, put, delete policies on
  an OPA server through its REST API. Works against a local
  `opa run --server` or a production deployment with bearer-token auth.
- **Build & sign bundles.** Package a directory of policies into a
  deployable bundle, optionally signing it. Output is a regular `.tar.gz`
  the agent can hand to your delivery system.
- **Lint.** `rego_lint` runs Regal across a directory or a single file
  and returns each finding with its category, level and location.

A walk-through of a typical session lives in [Cookbook](#cookbook).

## Why this MCP

OPA already has a perfectly good CLI and REST API. So why an MCP wrapper?

- **Schema-shaped tool surface.** An agent calling `rego_eval` gets a
  validated input schema, a structured output envelope, and stable error
  codes, instead of parsing free-form CLI text and inventing its own
  failure taxonomy. That alone makes Rego usable to an agent the way a
  language server makes a language usable to an IDE.
- **Higher-level helpers.** `rego_explain_decision`,
  `rego_generate_test_skeleton`, `rego_describe_policy`, and
  `rego_suggest_fix` compose the lower-level primitives into the tasks
  agents are actually asked to do. They don't exist in the OPA CLI.
- **Curated knowledge.** The bundled MCP **resources** expose the OPA
  built-in function catalog, the official Rego style guide (formatted for
  LLMs), and a curated pattern library covering RBAC, ABAC, Kubernetes
  admission, IaC gates, API authz, and rate limiting, so the agent has
  authoritative context without needing to scrape it.
- **Safety boundaries the agent can rely on.** Path allow-list,
  subprocess timeouts, and response-size caps. Defaults are conservative;
  running the server doesn't quietly grant the agent more reach than the
  operator intended.

If you've ever watched an agent fight `opa eval`'s argument order, you'll
recognize the gap this fills.

## Install

The server runs locally over stdio. Pick the install path that matches
your client.

### Claude Desktop

Edit `claude_desktop_config.json` directly (or copy from
[`examples/claude-desktop.json`](./examples/claude-desktop.json)):

```json
{
  "mcpServers": {
    "opa": {
      "command": "npx",
      "args": ["-y", "@orygn/opa-mcp"],
      "env": {
        "OPA_BINARY": "/usr/local/bin/opa",
        "REGAL_BINARY": "/usr/local/bin/regal",
        "OPA_URL": "http://localhost:8181",
        "OPA_MCP_ALLOWED_PATHS": "/path/to/your/policies"
      }
    }
  }
}
```

> Replace the `/usr/local/bin/...` paths with your real ones. See the
> [first-time install gotcha](#-first-time-install-gotcha-read-this-if-you-used-npx-or-the-global-install)
> below. Windows users substitute `C:\\path\\to\\opa.exe`.

Or download `opa-mcp.mcpb` from the
[latest release](https://github.com/OrygnsCode/opa-mcp-server/releases/latest)
and double-click it.

Alternatively, use the Smithery one-liner:

```bash
npx -y @smithery/cli install @orygn/opa-mcp --client claude
```

### Claude Code (CLI)

Register the server for the current project with `claude mcp add`:

```bash
claude mcp add \
  --env OPA_BINARY=/usr/local/bin/opa \
  --env REGAL_BINARY=/usr/local/bin/regal \
  --env OPA_MCP_ALLOWED_PATHS=/path/to/your/policies \
  opa -- npx -y @orygn/opa-mcp
```

This writes the config into `.mcp.json` at your project root and is
picked up automatically on every `claude` session in that directory.
Add `--scope user` to register it globally instead.

> Replace the paths with your real absolute paths (same caveat as
> Claude Desktop above). On Windows use `C:\path\to\opa.exe` syntax.

**Persistent context and auto-checks for policy repos.**
If you work in an OPA policy repo regularly, two extra files remove
repetitive setup from every session:

- [`examples/CLAUDE.md`](./examples/CLAUDE.md) -- copy to your repo
  root or `.claude/CLAUDE.md`. Claude Code loads it every session,
  so the agent always knows which tools to use and what conventions apply.
- [`examples/claude-code-hook.json`](./examples/claude-code-hook.json) --
  merge the `hooks` block into `.claude/settings.json`. Runs `opa check`
  automatically after any `.rego` file is written, so syntax errors
  surface immediately without a manual tool call.

### Cursor

Drop [`examples/cursor.json`](./examples/cursor.json) into either
`.cursor/mcp.json` (project-scoped) or `~/.cursor/mcp.json` (user-scoped).

### VS Code (GitHub Copilot Chat)

Drop [`examples/vscode.json`](./examples/vscode.json) into
`.vscode/mcp.json`, or paste the `servers` block into your user
`settings.json` under `mcp.servers`.

### Windsurf, Zed, and others

See [`examples/`](./examples) for a full set of drop-in configs.

### Manual install (any MCP client)

```bash
npm install -g @orygn/opa-mcp
opa-mcp --version
```

then point your client at the `opa-mcp` binary.

### Docker

```bash
docker pull orygn/opa-mcp:latest
docker run --rm -i \
  -v /path/to/your/policies:/policies:ro \
  -e OPA_MCP_ALLOWED_PATHS=/policies \
  orygn/opa-mcp
```

The image is multi-arch (`linux/amd64`, `linux/arm64`), bundles pinned
versions of `opa` and `regal`, and runs as a non-root user. No host
install of OPA or Regal is required.

### ⚠ If every tool call returns `OPA_BINARY_NOT_FOUND`

The npm package carries its own `opa` for the five platforms it is built
for, so a client `PATH` without `opa` on it does not matter there. The MCPB
has no bundled copy, and on any other platform neither does npm: then the
server boots but every tool call returns `OPA_BINARY_NOT_FOUND`. Neither the
npm package nor the MCPB bundles `regal` or `conftest`, and the Docker image
ships