Agent Pattern MCP

agent-pattern-mcp

An MCP (Model Context Protocol) server that provides agent system design expertise to AI coding agents. Given a requirements string and a domain, it analyses the problem, selects matching agent patterns (from 68 built-in patterns), generates a concrete agent system design with agents, relationships, tool contracts, state models, and message contracts, and evaluates it against quality attributes (reliability, cost efficiency, latency, output quality, observability, safety, simplicity). Coding agents that write the implementation themselves can call analyze_agent_system for topology and scored-pattern guidance without generating a design.

---

Table of Contents

• ⚡ Quickstart
• Install via AI Agent
• 🔌 Connect Your Agent
• Claude Code
• OpenCode
• Codex CLI
• 🧑🏫 SKILL for AI Agents
• 🧪 Use the Tools
• Design your first agent system
• Explore the pattern catalog
• 🛠️ Tools at a Glance
• 📖 Pattern Catalog
• Install Alternatives
• Docker (manual)
• Local Development (uv)
• Configuration
• Structured Reasoning (shannonthinking / code-reasoning)
• Extending with Custom Patterns
• Long-running tools & timeouts
• 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 reads MINIMAXAI_API_KEY and pins

GENERATOR_PROVIDER=minimax)

export MINIMAXAI_API_KEY=sk-...

3. Start (needs images: make docker-build-all once, or prebuilt pulls

per INSTALL.md Path A)

docker compose -f docker/docker-compose.yml up -d

4. Demo (analyze-only: fast. For the full design: make client-design)

make client-analyze

Server starts on streamable-http at http://localhost:8821/mcp (dev compose host port; systemd uses 8811). Then connect your agent below.

---

Install via AI Agent

To have an AI coding agent install the Docker stack from prebuilt images (no local build), point it at [INSTALL.md](INSTALL.md) — the non-interactive agent runbook (copy-paste commands, expected outputs, verification probes).

Clone this repo, then follow INSTALL.md Path A (compose stack, port 8821).

My generator API key is: sk-...

Pick one path in INSTALL.md:

• Path A — Compose stack (:8821): evaluating / developing, no sudo needed. Own TEI sidecar copies.
• Path B — systemd stack (:8811): persistent host service, starts at boot, needs sudo. Uses the shared pattern-tei-infra TEI stack.

The agent needs a repo clone, Docker ≥ v2.20 with group membership, ~5 GB free, a MINIMAXAI_API_KEY (or another provider per INSTALL.md#switching-the-generator-llm), and linux/amd64 (on arm64 it builds locally via make docker-build-all). After install, continue with Connect Your Agent below.

---

🔌 Connect Your Agent

Claude Code

# Install (one-time)

uv pip install -e .

Run as stdio subprocess — pass API key via env

claude mcp add agent-pattern \ -e GENERATOR_API_KEY=your_key \ -e GENERATOR_PROVIDER=openai \ -- agent-pattern-mcp --transport stdio

Or add to your project for the whole team:

claude mcp add --scope project agent-pattern \

-e GENERATOR_API_KEY=your_key \ -- agent-pattern-mcp --transport stdio

OpenCode

OpenCode uses HTTP transport. Start the server first, then configure opencode:

# Terminal 1: start the server

docker compose -f docker/docker-compose.yml up --build # serves :8821

or locally on the same port:

uv run python -m src.main --port 8821

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

{

"$schema": "https://opencode.ai/config.json", "mcp": { "agent-pattern": { "type": "remote", "url": "http://localhost:8821/mcp" } } }

Note: GENERATOR_API_KEY is read from the server's config file (~/.config/agent-pattern-mcp/config.json), not from opencode's environment.

Codex CLI

# Install (one-time)

uv pip install -e .

Add to ~/.codex/config.toml:

[mcp_servers.agent-pattern]

command = "agent-pattern-mcp" args = ["--transport", "stdio"]

[mcp_servers.agent-pattern.env] GENERATOR_API_KEY = "your_key" GENERATOR_PROVIDER = "openai"

Or via CLI:

codex mcp add agent-pattern \

-e GENERATOR_API_KEY=your_key \ -- agent-pattern-mcp --transport stdio

---

🧑🏫 SKILL for AI Agents

The SKILL in skills/agent-pattern-mcp/ is written for Oh My Pi (OMP), where this server's tools are reached as xd://mcp__agent_pattern_* devices and every MCP request is bounded by a deadline (OMP_MCP_TIMEOUT_MS → per-server timeout → 30 s). It teaches the agent which entry point fits that deadline, how to read the results, and the full workflow recipes.

skills/agent-pattern-mcp/

├── SKILL.md # OMP constraints, entry-point decision guide, device quick reference └── references/ ├── tools.md # 9 tool signatures, output schemas, error codes, design-dict shape └── workflows.md # recipes, result interpretation, OMP troubleshooting

Install for OMP — copy the skill directory into the user skills root, or point skills.customDirectories at this repository's skills/ directory in OMP's config:

cp -r skills/agent-pattern-mcp ~/.omp/agent/skills/

The skill then tells the agent:

• Which entry point fits OMP's deadline: the async job trio by default, one-shot design_agent_system only after raising the server's timeout (every LLM tool aborts under the 30 s default — submit_agent_design_job answers in ~0.05 s)
• That analyze_agent_system is the analysis-only path for coding agents that write the code themselves — topology, scored patterns, quality metrics, no design generated — while design_agent_system is for callers that want the design artifact
• How to phrase requirements, domain, and topology as separate structured arguments
• How to interpret final_quality_score, attempts > 1, and evaluation.recommendations
• That read mcp://pattern://… is ambiguous while the sibling architecture-pattern server is connected, so the tool route (get_agent_pattern) is authoritative

The tool schemas, error codes and design-dict shape in references/ are client-agnostic; only the deadline/device guidance is OMP-specific.

---

🧪 Use the Tools

All tools accept requirements (free text) and domain (e.g. tool-use-tasks, data-processing, customer-support) as arguments. The examples below show the exact tool call shape so you can use them in any MCP client or API consumer.

Design your first agent system

In Claude Code (or any MCP client), paste the natural-language instruction:

Build a research assistant agent that answers multi-hop questions by combining

web search results with sandboxed Python computation, iterating until it can synthesise a final cited answer.

Your agent calls design_agent_system internally. The server returns a full agent system design: agents (planner, searcher, coder, synthesizer), quality attribute scores (reliability: 8.0, output_quality: 8.5, …), and specific recommendations.

That is the design path: the server's LLM generates the design artifact for you, which is why a call takes minutes. If your agent writes the implementation itself and only needs the pattern expertise, call analyze_agent_system instead — it returns the recommended topology, the selected patterns with scores, quality_metrics (per-attribute 0–10), and matched domains without generating a design, so the generate and evaluate phases never run. Measured basis: a single live analyze_agent_system call on this host returned in 23.3 s, while the committed full-pipeline corpus measured p50 ≈ 304 s and p95 ≈ 375 s over 20 scenarios (benchmarks/base/summary.json).

Or call tools directly from your agent:

Call analyze_agent_system with:

requirements: "Research assistant combining web search with sandboxed code execution for multi-hop questions" domain: "tool-use-tasks"

Call generate_agent_system with: requirements: "Research assistant: decompose into sub-questions, search or code per sub-question, synthesise cited answer" domain: "tool-use-tasks" selected_patterns: ["react"]

Call evaluate_agent_system with: agent_system: { ... paste a design dict here ... } criteria: "reliability, safety"

Call list_agent_patterns() # all 68 patterns Call list_agent_patterns(category="multi_agent") # filter by category Call get_agent_pattern(name="supervisor-worker") # full pattern JSON

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 design path is design_agent_system with heartbeat defence. submit_agent_design_job returns a job_id immediately; poll get_agent_design_status until done:

# Step 1: start the job

Call submit_agent_design_job with: requirements: "Research assistant combining web search with sandboxed code execution for multi-hop questions" domain: "tool-use-tasks"

Step 2: poll every 10-30 seconds

Call get_agent_design_status with: job_id: " "

→ status is "pending" | "running" | "completed" | "failed" | "cancelled"

When status is "completed", the full design is in result.design

When status is "failed", the error is in result.error

In Python (via the MCP HTTP API directly — see examples/agent_client_async.py):

import asyncio

from fastmcp import Client

SERVER = "http://localhost:8821/mcp" POLL_EVERY = 15 # seconds

async def main(): async with Client(SERVER) as client:

Start

started = await client.call_tool("submit_agent_design_job", { "requirements": "Research assistant: web search + sandboxed code for multi-hop questions", "domain": "tool-use-tasks", }) job_id = started.data["job_id"] print(f"Job started: {job_id}")

Poll

while True: await asyncio.sleep(POLL_EVERY) status = await client.call_tool("get_agent_design_status", {"job_id": job_id}) data = status.data print(f" status={data['status']} message={data['message']}") if data["status"] in ("completed", "failed", "cancelled"): break

print(data.get("result", data)) # full design when completed

See examples/agent_client_async.py for the complete runnable example. Run it with:

docker compose -f docker/docker-compose.yml up --build   # Terminal 1

make client-async # Terminal 2

Explore the pattern catalog

Call list_agent_patterns() with no filters to see all patterns.

Or get details on a specific pa