MCP Policy Server

Give your Claude Code subagents instant, token-efficient access to your team's standards, guidelines, and best practices.

Stop polluting your context by putting all your agent guidelines into CLAUDE.md or each subagent definition. Reference specific rules with compact § notation and let subagents fetch exactly what they need, when they need it.

Why Use This?

The Problem

Teams document standards in markdown files (coding guidelines, architecture principles, deployment procedures). When you want Claude Code subagents to follow these standards, you're stuck with imperfect options:

• Put everything in memory like CLAUDE.md or rules files: Signal loss, high token costs due to implicit context that may not be needed for all tasks

• Reference entire documents: Unreliable, wastes tokens, hits context limits

• Maintain each subagent separately: Unnecessary duplication, hard to keep consistent

The Solution

Reference sections with notation like §PREFIX.1 or §PREFIX.2.3-5. Policies are fetched on demand. Your standards stay in markdown files. Subagents always get current content without token waste.

Key Benefits

• No wasted context: Fetch only needed sections, not entire documents

• Always current: Update files, changes appear automatically

• Automatic resolution: Reference one section, get it plus any sections it references

• Fast lookups: O(1) retrieval via section indexing

• Per-project policies: Same installation, different policy sets per project

Related MCP server: CityJSON Specification MCP Server

Setup Methods

Choose Plugin for Claude Code projects (simplest). Choose Hook if you need custom policy paths or hook behavior. Choose MCP Server when subagents need to dynamically select policies based on prompt criteria, or when using other MCP-compatible clients. Choose CLI for automation scripts or non-MCP integrations.

Quick Start: Create a Policy File

All methods require policy files with § notation. Create a policies directory and sample file:

.claude/policies/policy-example.md (for Plugin method) or ./policies/policy-example.md (for other methods):

## {§DESIGN.1} YAGNI (You Aren't Gonna Need It)

Build what you need now. Add features when needed, not in anticipation.

**Guidelines:**
- No speculative generalization
- No placeholder code for "future features"
- No abstraction without 3+ concrete use cases
- Delete unused code immediately

## {§DESIGN.2} Keep It Simple

See also §DESIGN.1 for related principles.

Method 1: Claude Code Plugin (Recommended)

Install the policies plugin and create policy files. The plugin configures hooks automatically.

Step 1: Install the Plugin

Inside Claude Code, run this once:

/plugin marketplace add rcrsr/claude-plugins

Then install the policies plugin:

/plugin install policies@rcrsr

The policies files should be placed in .claude/policies/ within your project directory.

Step 2: Create Policy Files

Add policy files to .claude/policies/:

.claude/policies/design.md:

## {§DESIGN.1} YAGNI (You Aren't Gonna Need It)

Build what you need now. Add features when needed, not in anticipation.

**Guidelines:**
- No speculative generalization
- No placeholder code for "future features"
- No abstraction without 3+ concrete use cases
- Delete unused code immediately

## {§DESIGN.2} Keep It Simple

See also §DESIGN.1 for related principles.

Step 3: Reference Policies in Subagents

.claude/agents/code-reviewer.md:

---
name: code-reviewer
description: Reviews code for compliance with standards
---

Required policies: §DESIGN.1, §DESIGN.2

You are a code reviewer following our team standards.
Apply the policies above when reviewing code.

Step 4: Run the Subagent

> @agent-code-reviewer review this PR

The plugin intercepts Task tool calls, extracts § references from the agent file, and injects matching policies automatically.

Note: References inside code fences are ignored, allowing you to document examples without triggering extraction.

Method 2: Claude Code Hook

Manual hook configuration for custom policy paths or behavior. Use this when the Plugin method's default .claude/policies/*.md path doesn't fit your project structure, or when building plugins that bundle mcp-policy-server as a dependency.

Plugin authors: The hook auto-discovers $CLAUDE_PROJECT_DIR/.claude/{agents,policies} and $CLAUDE_PLUGIN_ROOT/{agents,policies} when no explicit paths are provided. Your plugin can call policy-hook without arguments and it will find both plugin-bundled and project-level agents/policies automatically.

Step 1: Configure the Hook

Add to your project's .claude/settings.json:

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Task",
      "hooks": [{
        "type": "command",
        "command": "npx -p @rcrsr/mcp-policy-server policy-hook --config \"./policies/*.md\""
      }]
    }]
  }
}

Make sure to restart Claude Code after updating settings.

Step 2: Create a Subagent with Policy References

The actual format does not matter as long as the policy references are not code-fenced. For example:

.claude/agents/code-reviewer.md:

---
name: code-reviewer
description: Reviews code for compliance with standards
---

Required policies: §DESIGN.1, §DESIGN.2

You are a code reviewer following our team standards.
Apply the policies above when reviewing code.

Step 3: Run the Subagent

> @agent-code-reviewer review this PR

What happens:

1. Hook detects Task tool call with agent file

2. policy-hook extracts all § references from agent file (§DESIGN.1, §DESIGN.2)

3. Policies are placed before the task prompt, wrapped in <policies> tags, with the original task wrapped in <task> tags

4. Subagent receives policies automatically—no explicit tool call needed

Note: References inside code fences are ignored, allowing you to document examples without triggering extraction.

Prefix-Only References

Use prefix-only notation to fetch all sections with a given prefix:

Required: §DESIGN, §API

This expands §DESIGN to all §DESIGN.* sections and §API to all §API.* sections.

A prefix-only reference fails when the prefix matches no section, or when any section it covers is defined in more than one file. This applies to prefixes written in an agent file and to prefixes embedded in fetched policy text. Policy prose that mentions an unconfigured prefix (for example §LEGACY) fails resolution until you configure the prefix, remove the reference, or wrap it in backticks so it is not extracted.

Per-Agent Injection Mode

By default the hook injects the full text of every referenced section except [PROFORMA] sections. Add policy-mode to an agent's frontmatter to choose a different mode for that agent:

---
name: cli-engineer
tools: Read, Write, Edit, Bash
policy-mode: digest
---

Required policies: §DESIGN, §API

• Sections tagged [PROFORMA] (and their nested subsections) are skipped in every hook mode; fetch-policies still returns them. Use it for rules a mechanical check already enforces, and for templates; see Proforma Tag.

• The agent's policy-mode overrides the hook's --mode and --digest-minimal flags. Without the key, the flags apply, then full.

• --digest-depth, --digest-line-chars, and --fetch-instructions still apply from the hook command.

• An invalid value denies the Task call with a reason naming the agent file and the value.

• A digest agent fetches the rest through policy-cli in the digest footer, so it needs Bash. When tools: is declared without Bash, the hook falls back to full.

• Run the hook with --debug <file> to log the resolved mode and where it came from.

See Configuration Reference for details.

Method 3: MCP Server

Subagents call fetch_policies tool explicitly. Use this when:

• Subagents need to dynamically select policies based on prompt content

• You're using MCP-compatible clients other than Claude Code

• You need validation tools (validate_references, extract_references)

Step 1: Install the MCP Server

Linux/macOS:

claude mcp add-json policy-server '{
  "type": "stdio",
  "command": "npx",
  "args": ["-y", "@rcrsr/mcp-policy-server"],
  "env": {"MCP_POLICY_CONFIG": "./policies/*.md"}}' \
  --scope project

Windows:

claude mcp add-json policy-server ('{' `
  '"type": "stdio", "command": "cmd",' + `
  '"args": ["/c", "npx", "-y", "@rcrsr/mcp-policy-server"], ' + `
  '"env": {"MCP_POLICY_CONFIG": "./policies/*.md"}}') `
  --scope project

Step 2: Create a Subagent with Explicit Tool Call

.claude/agents/code-reviewer.md:

---
name: code-reviewer
description: Reviews code for compliance with standards
tools: mcp__policy-server__fetch_policies, Read, Glob
---

You are a code reviewer following our team standards.

**Before reviewing code:** call `mcp__policy-server__fetch_policies` with `{"sections": ["§DESIGN.1", "§DESIGN.2"]}`

Step 3: Test and Run

1. Restart Claude Code

2. Accept prompts to enable the MCP server

3. Run /mcp to verify "policy-server" shows "connected"

4. Run @agent-code-reviewer review this file

See Installation Guide for detailed setup.

Method 4: CLI

Use policy-cli for scripts, CI/CD, or non-MCP integrations.

Available Subcommands

policy-cli fetch-policies <ref>...      # Fetch policies for § refs given as arguments
policy-cli fetch-policies <file>        # Fetch policies for § refs in a file
policy-cli validate-references <ref>... # Validate § refs exist (exit 1 if any invalid)
policy-cli extract-references <file>    # Extract § refs from a file as JSON
policy-cli list-sources                 # List available policy files and prefixes
policy-cli list-sections                # List every section as JSON (id, file, bytes, refs, important, proforma)
policy-cli resolve-references <ref>...  # Map § refs to source files
policy-cli check <file>                 # Lint a policy file (exit 1 on format errors)

All subcommands except extract-references and check need --config (or MCP_POLICY_CONFIG).

Fetch Policies by Reference

npx -p @rcrsr/mcp-policy-server policy-cli fetch-policies §CODE.1 §API.2.3-5 --config "./policies/*.md"

Arguments starting with § are references; do not mix references and a file. Exit code 1 when a reference does not resolve.

Extract Policies from a File

npx -p @rcrsr/mcp-policy-server policy-cli fetch-policies document.md --config "./policies/*.md"

Extracts § references from document.md, fetches matching policies, outputs to stdout.

Use in Scripts

# Inject policies into a prompt template
POLICIES=$(npx -p @rcrsr/mcp-policy-server policy-cli fetch-policies agent.md --config "./policies/*.md")
echo "Follow these policies: $POLICIES" | your-llm-tool

# Validate references before use
npx -p @rcrsr/mcp-policy-server policy-cli validate-references §DOC.1 §DOC.2 --config "./policies/*.md"

# Lint a policy file in CI
npx -p @rcrsr/mcp-policy-server policy-cli check ./policies/policy-example.md

MCP Server Tools

These tools are available when using Method 3: MCP Server.

Example usage:

{"sections": ["§PREFIX.1", "§PREFIX.2"]}

Responses larger than roughly 10000 tokens are split at section boundaries. The response then ends with a continuation notice; call fetch_policies again with the same sections and the given continuation token. A string token that is not chunk:<n> (for example "" or "page:2"), or a chunk index past the last chunk, fails with Invalid continuation token. A non-string value (array, number, or object) fails with Invalid arguments.

Use Cases

• Code Review: Reference coding standards, style guides, architecture principles

• Deployment: Reference procedures, security checklists, rollback protocols

• Documentation: Reference standards, templates, review processes

• Testing: Reference coverage requirements, mocking patterns, integration setup

Documentation

• Getting Started - Step-by-step setup for all four methods

• Installation Guide - Detailed installation options

• Configuration Reference - Config options for hooks, MCP, and CLI

• Policy Reference - § notation syntax

• Best Practices - Patterns and strategies

• llms.txt - Condensed operating guide for LLM agents (llmstxt.org format)

License

GPL-3.0-or-later