PolyAgent MCP Server

PolyAgent is an MCP (Model Context Protocol) server that bridges AI coding assistants with the OPA (Open Policy Agent) ecosystem. It augments AI tools with domain-specific capabilities for policy-as-code development.

Features

• Interactive Policy Debugging: Conversational OPA policy evaluation and trace explanation
• Policy Example Search: RAG-powered semantic search over curated policy repositories
• Framework Requirements Lookup: Instant access to security framework requirements (OpenSSF SLSA, CIS, NIST)
• Zero-Config Setup: Interactive wizard configures your environment automatically

Quick Start

Installation

Install PolyAgent globally via npm:

npm install -g @polyagent/mcp-server

Setup

Run the setup wizard to configure PolyAgent and connect it to your AI tools:

polyagent-mcp setup

The wizard will:

1. Detect installed AI tools (Claude Code, Cursor).
2. Ask for your OpenAI API key (optional, for RAG search features).
3. Automatically configure Claude Code (if installed).
4. Provide configuration instructions for Cursor.

Verification

Verify that everything is working correctly:

polyagent-mcp verify

Health Check

Check the status of the MCP server components:

polyagent-mcp health

MCP Tools Reference

explain_policy_decision

Evaluates an OPA policy with input data and returns a detailed trace showing which rules fired. Use this to debug policy decisions and understand why a request was allowed or denied.

Input Parameters:

Parameter	Type	Required	Description
policyPath	string	Yes	Path to the Rego policy file (.rego)
inputData	string	Yes	JSON string containing the input data for evaluation
packageName	string	No	Package name to target (auto-detected if not provided)
ruleName	string	No	Rule name to evaluate (defaults to allow)

Example Input:

{
  "policyPath": "examples/policies/rbac-simple.rego",
  "inputData": "{\"user\": {\"role\": \"viewer\"}, \"action\": \"write\", \"resource\": {\"type\": \"document\"}}"
}

Output Format:

{
  "result": false,
  "trace": [
    { "rule": "allow", "line": 21, "result": "false" },
    { "rule": "allow", "line": 27, "result": "false" }
  ],
  "error": null
}

Field	Type	Description
result	boolean/object/null	The evaluation result (true = allowed, false = denied)
trace	array	Array of rule evaluations showing which rules were checked
error	object/null	Error details if evaluation failed

Common Use Cases:

• Debug why a policy denied a request
• Understand which rules were evaluated
• Verify policy behavior before deployment
• Learn OPA by seeing evaluation traces

See examples/debug-why-deny.md for a complete tutorial.

search_policy_examples

Semantic search over curated OPA policy repositories. Use this to discover proven implementation patterns for RBAC, Kubernetes admission control, supply chain security, and more.

Input Parameters:

Parameter	Type	Required	Description
query	string	Yes	Natural language search query for policy examples
limit	number	No	Maximum results to return (1-10, default: 3)
filterRepo	string	No	Filter results to a specific repository

Example Input:

{
  "query": "Kubernetes RBAC authorization policy",
  "limit": 5
}

Output Format:

{
  "results": [
    {
      "repo": "opa-library",
      "path": "authz/rbac.rego",
      "snippet": "package authz.rbac\n\ndefault allow = false\n...",
      "description": "Role-based access control for API authorization",
      "tags": ["rbac", "authorization", "kubernetes"],
      "similarityScore": 0.89
    }
  ],
  "totalFound": 1
}

Field	Type	Description
results	array	Array of matching policy examples
results[].repo	string	Source repository name
results[].path	string	File path within the repository
results[].snippet	string	Policy code snippet (max 200 lines)
results[].description	string	Description of the policy
results[].tags	array	Categorization tags
results[].similarityScore	number	Relevance score (0-1)
totalFound	number	Number of results returned
suggestions	array	Alternative query suggestions (when no results)

Query Tips:

• Be specific - "Kubernetes pod security" works better than just "security"
• Include context - Mention the domain (AWS, Kubernetes, Terraform)
• Use policy terms - "deny", "allow", "admission", "authorization"
• Filter by repo - Use filterRepo for examples from trusted sources

Tutorials:

• examples/search-sigstore-examples.md - Container signature verification
• examples/search-rbac-examples.md - Role-based access control
• examples/search-slsa-examples.md - Supply chain security (SLSA)

Development

Build:

npm run build

Test:

npm test

Lint:

npm run lint

Watch mode:

npm run dev

License

Apache 2.0 - See LICENSE file for details.

Project Status

This project is under active development. Current implementation focuses on the MVP delivering three core MCP tools for policy development workflows.