Provides AI agent system design expertise by analyzing requirements to select patterns, generate architectures, and evaluate quality attributes.
Also known as olk/agent-pattern-mcp, agent-pattern-mcp
- Stars
- 0
- Tools
- 9
- Downloads, 30 days
- —
- Latest version
- 1.0.4
- Last commit
- Oct 26, 2026
- License
- MIT
What is Agent Pattern MCP?
Agent Pattern provides AI agent system design expertise by analyzing requirements to select patterns, generate architectures, and evaluate quality attributes. It exposes 9 tools, such as analyze_agent_system, generate_agent_system, evaluate_agent_system.
Summary generated from the project's README
About Agent Pattern MCP server
Agent Pattern MCP provides specialized system design expertise to AI coding agents. It helps developers architect complex agentic workflows by analyzing natural language requirements and specific domains. The server can select from 68 built-in patterns to suggest optimal topologies, including agents, relationships, tool contracts, and state models.
Users can choose between two primary workflows. The design path generates a complete architecture artifact, while the analysis path provides scored pattern guidance and quality metrics without creating a full design. This makes it useful for both high-level architects and coding agents that prefer to write their own implementation based on expert topological advice.
The server can be deployed via Docker Compose or as a persistent systemd service. It connects to clients like Claude Code, OpenCode, and Codex CLI using either stdio or HTTP transport. To function, it requires a generator API key from providers such as OpenAI or MinimaxAI.
What you can do with it
- 1Generate complete agent architecturesAn AI agent can create a full system design including agents, relationships, and message contracts based on a requirements string.
- 2Obtain pattern guidance for manual codingCoding agents that implement their own logic can request topology and scored patterns without generating a full design artifact.
- 3Evaluate system quality attributesDevelopers can assess a proposed design against specific metrics like reliability, cost efficiency, and safety.
- 4Manage long-running design tasksFor clients with short timeouts, the server supports an asynchronous job pattern to prevent connection drops during complex generations.
Written from the project's README. Every use case is checked against a quote from it.
How to install Agent Pattern MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Agent Pattern MCP in Claude Code
$ claude mcp add --env 'GENERATOR_API_KEY=<YOUR_GENERATOR_API_KEY>' --env 'EMBEDDER_API_KEY=<YOUR_EMBEDDER_API_KEY>' agent-pattern-mcp -- docker run -i --rm docker.io/olkowa/agent-pattern-mcp:1.0.4Install Agent Pattern MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"agent-pattern-mcp": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"docker.io/olkowa/agent-pattern-mcp:1.0.4"
],
"env": {
"GENERATOR_API_KEY": "<YOUR_GENERATOR_API_KEY>",
"EMBEDDER_API_KEY": "<YOUR_EMBEDDER_API_KEY>"
}
}
}
}Install Agent Pattern MCP in VS Code
.vscode/mcp.json
{
"servers": {
"agent-pattern-mcp": {
"type": "stdio",
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"docker.io/olkowa/agent-pattern-mcp:1.0.4"
],
"env": {
"GENERATOR_API_KEY": "<YOUR_GENERATOR_API_KEY>",
"EMBEDDER_API_KEY": "<YOUR_EMBEDDER_API_KEY>"
}
}
}
}Install Agent Pattern MCP in VS Code CLI
$ code --add-mcp '{"name":"agent-pattern-mcp","type":"stdio","command":"docker","args":["run","-i","--rm","docker.io/olkowa/agent-pattern-mcp:1.0.4"],"env":{"GENERATOR_API_KEY":"<YOUR_GENERATOR_API_KEY>","EMBEDDER_API_KEY":"<YOUR_EMBEDDER_API_KEY>"}}'Install Agent Pattern MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"agent-pattern-mcp": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"docker.io/olkowa/agent-pattern-mcp:1.0.4"
],
"env": {
"GENERATOR_API_KEY": "<YOUR_GENERATOR_API_KEY>",
"EMBEDDER_API_KEY": "<YOUR_EMBEDDER_API_KEY>"
}
}
}
}Install Agent Pattern MCP in Codex
$ codex mcp add agent-pattern-mcp --env 'GENERATOR_API_KEY=<YOUR_GENERATOR_API_KEY>' --env 'EMBEDDER_API_KEY=<YOUR_EMBEDDER_API_KEY>' -- docker run -i --rm docker.io/olkowa/agent-pattern-mcp:1.0.4Install Agent Pattern MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.agent-pattern-mcp] command = "docker" args = ["run", "-i", "--rm", "docker.io/olkowa/agent-pattern-mcp:1.0.4"] [mcp_servers.agent-pattern-mcp.env] GENERATOR_API_KEY = "<YOUR_GENERATOR_API_KEY>" EMBEDDER_API_KEY = "<YOUR_EMBEDDER_API_KEY>"
Install Agent Pattern MCP in Gemini CLI
$ gemini mcp add -s user -e 'GENERATOR_API_KEY=<YOUR_GENERATOR_API_KEY>' -e 'EMBEDDER_API_KEY=<YOUR_EMBEDDER_API_KEY>' agent-pattern-mcp docker -- run -i --rm docker.io/olkowa/agent-pattern-mcp:1.0.4Install Agent Pattern MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"agent-pattern-mcp": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"docker.io/olkowa/agent-pattern-mcp:1.0.4"
],
"env": {
"GENERATOR_API_KEY": "<YOUR_GENERATOR_API_KEY>",
"EMBEDDER_API_KEY": "<YOUR_EMBEDDER_API_KEY>"
}
}
}
}Agent Pattern MCP tools 9
Detected from the READMEanalyze_agent_systemgenerate_agent_systemevaluate_agent_systemdesign_agent_systemsubmit_agent_design_jobget_agent_design_statuscancel_agent_designlist_agent_patternsget_agent_pattern
| analyze_agent_system | — | |
| generate_agent_system | — | |
| evaluate_agent_system | — | |
| design_agent_system | — | |
| submit_agent_design_job | — | |
| get_agent_design_status | — | |
| cancel_agent_design | — | |
| list_agent_patterns | — | |
| get_agent_pattern | — |
Configuration
GENERATOR_API_KEYRequiredSecretAPI key for the generator LLM (LiteLLM provider).
EMBEDDER_API_KEYSecretAPI key for the embedder. Required for startup even with keyless TEI; use 'not-needed' there.
EMBEDDER_BASE_URLEmbedder endpoint. For TEI sidecars on the host use http://host.docker.internal:8080/v1 (add --add-host=host.docker.internal:host-gateway on Linux).
EMBEDDER_PROVIDEREmbedding backend for pattern retrieval: tei, openai, ollama, vllm or hosted_vllm.
GENERATOR_BASE_URLOpenAI-compatible base URL (LiteLLM api_base).
GENERATOR_MODELModel name, combined as <provider>/<model> via LiteLLM.
GENERATOR_PROVIDERLiteLLM provider prefix, e.g. openai, anthropic, openrouter, minimax.
MINIMAXAI_API_KEYPATTERN_DIRECTORYDirectory with *-pattern.json files. The image bakes the 61-pattern catalog at /app/pattern.
REASONING_ENABLEDREASONING_FAIL_FASTRERANKER_BASE_URLTEI cross-encoder reranker endpoint used during pattern retrieval.
| Name | Description | |
|---|---|---|
| GENERATOR_API_KEY | API key for the generator LLM (LiteLLM provider). | RequiredSecret |
| EMBEDDER_API_KEY | API key for the embedder. Required for startup even with keyless TEI; use 'not-needed' there. | Secret |
| EMBEDDER_BASE_URL | Embedder endpoint. For TEI sidecars on the host use http://host.docker.internal:8080/v1 (add --add-host=host.docker.internal:host-gateway on Linux). | |
| EMBEDDER_PROVIDER | Embedding backend for pattern retrieval: tei, openai, ollama, vllm or hosted_vllm. | |
| GENERATOR_BASE_URL | OpenAI-compatible base URL (LiteLLM api_base). | |
| GENERATOR_MODEL | Model name, combined as <provider>/<model> via LiteLLM. | |
| GENERATOR_PROVIDER | LiteLLM provider prefix, e.g. openai, anthropic, openrouter, minimax. | |
| MINIMAXAI_API_KEY | — | |
| PATTERN_DIRECTORY | Directory with *-pattern.json files. The image bakes the 61-pattern catalog at /app/pattern. | |
| REASONING_ENABLED | — | |
| REASONING_FAIL_FAST | — | |
| RERANKER_BASE_URL | TEI cross-encoder reranker endpoint used during pattern retrieval. |
Automated checks
Ran Nov 13, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packageNot checked
- Remote endpoint uses HTTPSNot checked
- Destructive tools are labelledPass
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesNot checked
README
View on GitHubagent-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
- 🧑🏫 SKILL for AI Agents
- 🧪 Use the Tools
- 🛠️ Tools at a Glance
- 📖 Pattern Catalog
- Install Alternatives
- 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 — 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, needssudo. Uses the sharedpattern-tei-infraTEI 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_KEYis 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_systemonly after raising the server'stimeout(every LLM tool aborts under the 30 s default —submit_agent_design_jobanswers in ~0.05 s) - That
analyze_agent_systemis the analysis-only path for coding agents that write the code themselves — topology, scored patterns, quality metrics, no design generated — whiledesign_agent_systemis for callers that want the design artifact - How to phrase
requirements,domain, andtopologyas separate structured arguments - How to interpret
final_quality_score,attempts > 1, andevaluation.recommendations - That
read mcp://pattern://…is ambiguous while the siblingarchitecture-patternserver 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: "<job_id from step 1>"
# → 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 pattern:
Show me details about the react agent pattern.
🛠️ Tools at a Glance
| Tool | Description |
|---|---|
analyze_agent_system |
Analysis-only path for agents that write the code themselves: requirements + domain → recommended topology, selected patterns with scores, quality metrics (per-attribute 0–10), matched domains. Generates no design. One LLM call (23 s measured). Not idempotent. |
generate_agent_system |
Generate an agent system design from requirements and selected patterns. Long-running (LLM call). Not idempotent. |
evaluate_agent_system |
Score an existing design against quality attributes. Long-running (LLM call). Not idempotent. |
design_agent_system |
Design path: full pipeline (analyse → generate → evaluate → refine, up to 3 attempts) → agents, relationships, tool contracts, state models, plus evaluation. Long-running (5–10 min); use this when the caller wants the design artifact, or the job trio if the client has a short request timeout. |
submit_agent_design_job |
Start a background design job and return a job_id immediately. ONLY for clients with short request timeouts (Cursor, Claude Desktop, TS-SDK). For other clients use design_agent_system. Poll get_agent_design_status every 10–30 s. |
get_agent_design_status |
Poll job status. Returns the current status, progress message, and the full design output when completed. |
cancel_agent_design |
Cancel a running job (best-effort; takes effect at the next pipeline stage boundary; may take up to one LLM call). |
list_agent_patterns |
List all 68 patterns; filter by category and/or domain |
get_agent_pattern |
Get full JSON for a specific pattern by name |
Domain and Topology are structured parameters — pass them as separate tool arguments, not embedded in the requirements text.
Example prompts:
Build a research assistant that answers multi-hop questions by combining
web search with sandboxed code execution, with full audit logging.
Design an agent system for customer-support automation handling 1M
conversations/day. Domain: customer-support. Topology: hierarchical.
Show me details about the reflexion pattern.
Call design_agent_system with:
requirements: "Research assistant combining web search with sandboxed code execution for multi-hop questions"
domain: "tool-use-tasks"
💬 Prompts
This server also exposes four user-invoked workflow prompts (slash commands in MCP clients). Unlike tools, the LLM does not autonomously invoke prompts — the user selects one and fills in its arguments. Each prompt encodes a tested tool-orchestration recipe.
| Prompt | Args | What it does |
|---|---|---|
/design_agent_system_workflow |
requirements* | Full analyze → generate → evaluate pipeline |
/explore_pattern_catalog |
domain, category |
Live catalog discovery with embedded pattern names |
/evaluate_my_agent_system |
focus |
Guide evaluation criteria + finding prioritisation |
/compare_agent_topologies |
topology_a*, topology_b*, requirements* | Two designs side-by-side; ~2× token cost |
* = required argument
Tool-only clients
Clients that only support the tools protocol (no native prompts/list or prompts/get) can access all four workflow prompts via the generated list_prompts and get_prompt tools, which route through the server's middleware chain exactly as native prompt calls do.
📖 Pattern Catalog
Via MCP tools (recommended — works in all clients)
list_agent_patterns() # all 68 patterns
list_agent_patterns(category="multi_agent") # filter by category
list_agent_patterns(domain="tool-use-tasks") # filter by domain
get_agent_pattern(name="supervisor-worker") # full pattern JSON
Valid category values: reasoning, tool_use, planning, reflection, research_synthesis, multi_agent, memory, retrieval, safety_control, observability.
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
Note: on hosts where the sibling
architecture-pattern-mcpserver is also connected,pattern://{name}is ambiguous (both servers register the scheme) — the tool route (get_agent_pattern) is authoritative.
Pattern JSON structure
Each pattern includes: name, category, topology, context, benefits, tradeoffs, quality_attributes (reliability/cost_efficiency/latency/output_quality/observability/safety/simplicity, numeric scores), suitable_domains, component_types, technology_stack, design_principles, best_practices.
Required fields: name, context, category, topology, suitable_domains, quality_attributes (all 7 keys).
Install Alternatives
Docker (manual)
# Build the image
make docker-build
# Run with your API key
MINIMAXAI_API_KEY=your_key docker compose -f docker/docker-compose.yml up -d
Local Development (uv)
Prerequisites: Python 3.12+, uv
# Install
make install
# Configure
cp config/config.json ~/.config/agent-pattern-mcp/config.json
# Edit ~/.config/agent-pattern-mcp/config.json and set your GENERATOR_API_KEY
# Run the server
uv run python -m src.main --transport stdio # for Claude Code / Codex
uv run python -m src.main --port 8050 # for OpenCode (HTTP, default)
Or use the installed console script (after make install):
agent-pattern-mcp --transport stdio
The TEI embedder (Qwen3-Embedding-0.6B) is required for domain-scoped pattern retrieval. Without it, the server falls back to the default pattern. Docker compose starts it automatically; local users must run it separately on port 8080.
The retrieval legs are built at server startup: BM25 always, the FAISS dense leg from the embedding-index cache when a valid snapshot exists (otherwise embedded from scratch). Startup stays fail-fast — every start makes one probe embedding call, so a misconfigured or unreachable TEI sidecar aborts warmup rather than breaking the user's first design request. Docker compose's service_healthy dependency ordering guarantees TEI is ready before the app starts.
TEI startup: both sidecar images (
docker/Dockerfile.tei-embed,docker/Dockerfile.tei-rerank) ship a self-built TEI router (v1.9.4 + unmerged PR #884) withWARMUP_TOKENS=0by default — this skips the synthetic warmup pass (measured ~131 s embed / ~78 s rerank) so containers become ready after weight load only. Override per sidecar viaTEI_WARMUP_TOKENS/TEI_RERANK_WARMUP_TOKENS(positive N warms with N tokens instead; values >MAX_BATCH_TOKENSare rejected at startup).
GPU TEI: the shipped sidecars are CPU images (FROM ghcr.io/huggingface/text-embeddings-inference:cpu-1.9, ORT backend — batch cap 8 for this model) and the Stage-0 router is built CPU-only (--features ort,http). This repo ships no GPU build path — running on CUDA would require changing the runtime base image to :cuda-1.9 and rebuilding the router with the CUDA feature set, which is not a supported recipe here (only design-pattern-mcp-local ships one: make docker-build-tei-embed-gpu). A stock upstream TEI image without PR #884 silently ignores WARMUP_TOKENS.
Already-running embedder/reranker: when embedding and reranking endpoints already run on other servers, point the MCP server at them and skip the sidecars (docker/docker-compose.hub.yml starts the MCP server only and wires exactly this). The remote embedder must be TEI serving the same model — keep EMBEDDER_PROVIDER=tei and set EMBEDDER_BASE_URL to its OpenAI-compatible route (http://<host>:8080/v1, the config.json default). This server's embedder config has no model field (src/patterns/embedder.py::build_embedder sends an empty model name for the non-tei providers), so openai / ollama / vllm / hosted_vllm cannot address an arbitrary remote model without a code change. The reranker is not a LiteLLM client — it POSTs {RERANKER_BASE_URL}/rerank directly (default http://pattern-tei-rerank:8080, no /v1); provider/model syntax in the LiteLLM embedding docs applies to the embedder only. EMBEDDER_API_KEY is forwarded as the LiteLLM api_key (any non-empty string satisfies a no-auth TEI).
Configuration
config.json
The server reads ~/.config/agent-pattern-mcp/config.json (override with --config-path):
{
"generator": {
"provider": "openai",
"config": {
"model": "gpt-4o-mini",
"base_url": "https://api.openai.com/v1",
"api_key": "{env:GENERATOR_API_KEY}",
"temperature": 0.1,
"top_p": 1.0,
"top_k": 20
}
},
"embedder": {
"provider": "tei",
"config": {
"base_url": "http://pattern-tei-embed:8080/v1"
}
},
"retrieval": {
"bm25_top_k": 0,
"dense_top_k": 0,
"top_k_patterns": 5,
"min_quality_score": 50.0
},
"pattern_directory": "~/.config/agent-pattern-mcp/pattern",
"transport": "streamable-http",
"host": "0.0.0.0",
"port": 8050,
"logging_level": "INFO",
"logging_format": "json"
}
{env:VAR:-default} syntax expands environment variables at load time.
Generator LLM (LlamaIndex LiteLLM)
The generator LLM is accessed through the LlamaIndex LiteLLM integration (llama-index-llms-litellm). All provider settings therefore follow LiteLLM's model syntax: <provider>/<model> (e.g. openai/gpt-4o-mini, anthropic/claude-sonnet-4-5, openrouter/minimax/minimax-m2).
The server composes the LiteLLM model string from your configuration as generator.provider + generator.config.model:
| Config / env | Example | Resulting LiteLLM model string |
|---|---|---|
provider: "openai", model: "gpt-4o-mini" |
GENERATOR_PROVIDER=openai, GENERATOR_MODEL=gpt-4o-mini |
openai/gpt-4o-mini |
provider: "anthropic", model: "claude-sonnet-4-5" |
GENERATOR_PROVIDER=anthropic, GENERATOR_MODEL=claude-sonnet-4-5 |
anthropic/claude-sonnet-4-5 |
provider: "openrouter", model: "minimax/minimax-m2" |
GENERATOR_PROVIDER=openrouter, GENERATOR_MODEL=minimax/minimax-m2 |
openrouter/minimax/minimax-m2 |
If the configured model already contains a provider prefix (e.g. openai/gpt-4o-mini), that prefix is stripped and replaced by the configured provider.
- Provider list, model names, and the exact
<provider>/<model>syntax: LiteLLM Providers documentation - Custom/OpenAI-compatible endpoints (proxies, vLLM, Ollama, …): set
GENERATOR_BASE_URL(generator.config.base_url) — it is passed as the LiteLLMapi_base GENERATOR_API_KEYis passed as the LiteLLMapi_key;temperature,top_p,top_k, andstreammap to the corresponding LiteLLM parameters
Agent Pattern MCP questions
How do I add Agent Pattern MCP to Claude Code?
Run claude mcp add --env 'GENERATOR_API_KEY=<YOUR_GENERATOR_API_KEY>' --env 'EMBEDDER_API_KEY=<YOUR_EMBEDDER_API_KEY>' agent-pattern-mcp -- docker run -i --rm docker.io/olkowa/agent-pattern-mcp:1.0.4 in your terminal. Add --scope user to make it available in every project.
How do I add Agent Pattern MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does Agent Pattern MCP provide?
It exposes 9 tools, including analyze_agent_system, generate_agent_system, evaluate_agent_system, design_agent_system, submit_agent_design_job.
What can the server do for coding agents?
Coding agents can call analyze_agent_system to receive topology and scored-pattern guidance without having to generate a full design themselves.
How many agent patterns are available?
The server includes 68 built-in agent patterns.
How do I handle long-running design tasks in clients with short timeouts?
Use the async job pattern by calling submit_agent_design_job to get a job_id, then poll get_agent_design_status until the status is completed.
What quality attributes does the server evaluate?
The server evaluates designs against reliability, cost efficiency, latency, output quality, observability, safety, and simplicity.