agent-pattern-mcp

MCP server that provides AI agent pattern expertise: generate, analyze, and evaluate agent system designs against a curated catalog of 61 agent patterns (ReAct, supervisor-worker, reflexion, self-RAG, LLMCompiler, and more).

Table of Contents

• Quickstart
• Connect Your Agent
• Use the Tools
• Tools at a Glance
• Prompts
• Pattern Catalog
• SKILL for AI Agents
• Install Alternatives
• Configuration
• Extending with Custom Patterns
• Troubleshooting
• Building & Development
• Publishing
• systemd Service (Linux)
• License

⚡ Quickstart

# 1. Clone
git clone https://github.com/olk/agent-pattern-mcp.git && cd agent-pattern-mcp

# 2. Add your API key (the dev compose pins GENERATOR_PROVIDER=minimax and
#    loads docker/.env — not the repo-root .env)
echo 'MINIMAXAI_API_KEY=sk-...' > docker/.env

# 3. Build the images once (TEI model weights are baked in at build time,
#    ~5 GB download on the first run), then start the stack
make docker-build-all
make docker-up

# 4. Demo
make client

🔌 Connect Your Agent

Claude Code

# Install (one-time)
npm install -g @anthropic-ai/claude-code

# Run as stdio subprocess — pass API key via env
GENERATOR_API_KEY=sk-... claude mcp add agent-pattern-mcp -- python -m src.main --transport stdio

OpenCode

# Terminal 1: start the server
make docker-up
# or locally:
uv run python -m src.main

# Terminal 2: add to ~/.config/opencode/opencode.json

{
  "mcp": {
    "agent-pattern-mcp": {
      "type": "remote",
      "url": "http://localhost:8061/mcp",
      "enabled": true
    }
  }
}

Codex CLI

# Install (one-time)
brew install codex

# Add to ~/.codex/config.toml

[mcp_servers.agent-pattern-mcp]
url = "http://localhost:8061/mcp"

Use the Tools

Design your first agent system

Ask your agent (or call the tool directly):

Use design_agent_system to design a research assistant that combines web search with sandboxed code execution for multi-hop questions. Domain: tool-use-tasks.

The tool runs the full pipeline — analyze (pattern retrieval + requirements-weighted scoring) → generate (LLM structured output) → evaluate (metric scoring) → refine (bounded retry loop) — and returns a complete AgentSystemDesign with agents, relationships, tool contracts, and quality scores.

Explore the pattern catalog

List all agent patterns in the tool_use category.

Get the full JSON of the react pattern.

Async job pattern: submit_agent_design_job + get_agent_design_status

ONLY for clients with short request timeouts (Cursor, Claude Desktop, TS-SDK). The default is design_agent_system with heartbeat defence. submit_agent_design_job returns a job_id immediately; poll get_agent_design_status until done:

submit_agent_design_job(requirements, domain, override_topology)  → job_id
get_agent_design_status(job_id)                                  → {status, result, error}
cancel_agent_design(job_id)                                    → {cancelled, status}

submit_agent_design_job returns a job_id in milliseconds. The pipeline runs in a background task. Poll get_agent_design_status(job_id) every 10–30 seconds. When status is completed, the full design is in the result field. Cancellation is best-effort — the job exits at the next pipeline stage boundary.

This is the only fix that works for TS-SDK clients (Claude Desktop, Cursor).

The job store is SQLite at ~/.config/agent-pattern-mcp/jobs.db (configurable via AGENT_PATTERN_JOBS_DB).

🛠️ Tools at a Glance

💬 Prompts

The server also exposes four user-invoked workflow prompts (slash commands in clients that support them):

* = required argument

Tool-only clients

In tool-only clients, the prompts are also exposed as tools via FastMCP's PromptsAsTools transform — you can call them like any other tool.

🧑‍🏫 SKILL for AI Agents

AI coding agents (Claude Code, OpenCode, Codex CLI) can load a SKILL that teaches them how and when to use this server's tools — including timeout-aware entry-point selection, output interpretation, and the full workflow recipe.

The SKILL lives in skills/agent-pattern-mcp/:

skills/agent-pattern-mcp/
├── SKILL.md                 # Discovery, critical rules, decision guide
└── references/
    ├── tools.md             # All 9 tool signatures and output schemas
    └── workflows.md         # 4 worked examples, 4 prompts, best practices

For agents that support file-based skills (OpenCode, Claude Code): point the agent's skill loader at skills/agent-pattern-mcp/SKILL.md. The skill tells the agent:

• Which tool to use based on client type and timeout budget
• How to phrase requirements, domain, and topology as separate structured arguments
• How to interpret final_quality_score, attempts > 1, and evaluation.recommendations
• When to use the async job trio vs design_agent_system directly

📖 Pattern Catalog

61 agent patterns across 10 categories (reasoning, tool_use, planning, reflection, research_synthesis, multi_agent, memory, retrieval, safety_control, observability) and 8 topologies (single-agent-loop, hierarchical, pipeline, plan-execute, parallel-fan-out, evaluator-loop, graph-orchestrated, swarm).

Via MCP tools (recommended — works in all clients)

list_agent_patterns(category="multi_agent")
get_agent_pattern(name="supervisor-worker")

Via MCP resources

pattern://                    → list of all patterns
pattern://{name}              → full pattern JSON
template://{name}             → curated design templates (react, supervisor-worker, multi-agent-debate, agentic-rag)
component://{type}            → component blueprints derived from pattern data

Pattern JSON structure

Each pattern/*-pattern.json file contains: name, category, topology, context, benefits, tradeoffs, quality_attributes (7 dims, 1-10), suitable_domains, unsuitable_domains, use_cases, avoid_when, component_types, technology_stack, anti_patterns, migration_from, migration_to, design_principles, best_practices, references.

Install Alternatives

Docker (manual)

# Build the image
docker build --target production -f Dockerfile -t agent-pattern-mcp:latest .

# Run with your API key
docker run -p 8061:8051 --env-file .env agent-pattern-mcp:latest

Docker Hub image (compose)

Pull olkowa/agent-pattern-mcp without building. The hub compose starts the MCP server only; start the TEI sidecars (olkowa/pattern-tei-embed, olkowa/pattern-tei-rerank) separately and wire them via EMBEDDER_BASE_URL / RERANKER_BASE_URL:

TAG=latest docker compose -f docker/docker-compose.hub.yml up -d

Local Development (uv)

# Install
uv sync

# Configure
mkdir -p ~/.config/agent-pattern-mcp
cp config/config.json ~/.config/agent-pattern-mcp/
# Edit ~/.config/agent-pattern-mcp/config.json and set your GENERATOR_API_KEY

# Run the server
uv run python -m src.main

Configuration

config.json

See config/config.json for the full annotated example. Key sections: