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.3.0. Tool surface, error codes, and
> environment variables follow [SemVer](https://semver.org/) from
> v0.1.0 forward.

---

## 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 categorized findings (style, bugs, performance, idioms).

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.

### ⚠ First-time install gotcha (read this if you used `npx` or the global install)

If your client's `PATH` doesn't include the directory where `opa` lives
(this happens with Claude Desktop on Windows and macOS by default), the
server boots fine but every tool call returns `OPA_BINARY_NOT_FOUND`.

**Fix:** add `OPA_BINARY` and `REGAL_BINARY` env entries to your client
config with the absolute path to each binary. The example configs under
[`examples/`](./examples) ship with placeholder paths you replace.
Find the real paths with:

```bash
which opa && which regal                                    # macOS / Linux
```

```powershell
Get-Command opa, regal | Select-Object Source              # Windows
```

This does not affect the **Docker** or **MCPB** install paths; those
ship `opa` and `regal` inside the bundle and bypass `PATH` entirely.
See [Troubleshooting](#troubleshooting) for full detail.

## Configuration

The server reads its configuration from environment variables. Every
variable is optional; defaults are sensible for a local OPA on
`http://localhost:8181`.

| Variable                     | Default                      | Purpose                                                                                                                                                                                                                                                                 |
| ---------------------------- | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |