Agency MCP Server

agency-mcp-server

One MCP config entry. 150+ specialist agents on demand. No manual setup.

Your AI assistant is a generalist. Sometimes you need a specialist -- a game economy designer, a security auditor, a technical writer. This MCP server gives your assistant instant access to 150+ expert agent templates. Describe what you need, it finds the right agent and spawns it.

You: "Help me design a balanced game economy"

Claude: [searches -> finds Game Economy Designer -> spawns it -> expert response]

Templates auto-fetch on first run from agency-agents and stay updated. You don't touch a thing.

Why not just install agents locally?

You can. The agency-agents install script copies all 160+ agent files directly into your tool's config directory (e.g. ~/.claude/agents/). It works -- but every agent's name and description is loaded into the context window of every conversation, whether you use them or not.

We measured it:

That's a 150x reduction in baseline context usage. You get the same 160+ agents, but you only pay for the one you're actually using.

How we measured this

Installed agents (8,300 tokens): We ran the agency-agents install script (install.sh --tool claude-code), which copied 162 agent files to ~/.claude/agents/. Then opened a fresh Claude Code session and ran /context. Claude Code reported "Custom agents: 8.3k tokens" -- loaded into every conversation regardless of whether any agent is used.

MCP idle (55 tokens): With the MCP server configured instead, /context shows only the two deferred tool names (agency_search, agency_browse) and a brief server description in the system prompt. No agent data is loaded.

MCP searching (350 tokens): Measured by tokenizing the full JSON tool schemas that get loaded when the assistant calls ToolSearch to resolve the agency_search and agency_browse tools. Counted with @anthropic-ai/tokenizer.

MCP using an agent (2,700 tokens): The median token count across all 145 agent files, measured with @anthropic-ai/tokenizer. Only the single agent file you're actually using gets loaded into context. The range is 383–12,724 tokens depending on the agent (p25: 1,549, p75: 3,584).

Quick Start

Claude Code

As a plugin:

/plugin marketplace add npupko/agency-mcp-server

/plugin install agency@agency-mcp-server

Or via CLI:

claude mcp add agency -- npx -y agency-mcp-server

Cursor, Windsurf, and other MCP clients

Add to your MCP config:

{

"mcpServers": { "agency": { "command": "npx", "args": ["-y", "agency-mcp-server"] } } }

That's it. First launch clones templates to ~/.cache/agency-mcp-server/ and pulls updates every 24 hours.

Verify it works

Ask your assistant:

"Search for a game economy designer agent"

You should see results from the agency_search tool. If it's the first run, templates will auto-download (~30 seconds).

How It Works

Your assistant gets four tools:

1. `agency_search(query, division?)` -- describe a task, get matching agents with spawn instructions
2. `agency_browse(division?)` -- explore divisions and agents when you want to see what's available
3. `agency_status()` -- check index freshness: agent count, last update time, whether an update is available
4. `agency_update()` -- pull latest templates from git and rebuild the search index without restarting

When you ask for help with something specific, your assistant calls agency_search, picks the best match, and spawns a subagent with that specialist's full system prompt. You get an expert response without ever touching a config file.

What's available

Agents are organized into divisions:

Configuration

All configuration is through environment variables in your MCP config:

Use your own templates

Point at a local directory:

{

"mcpServers": { "agency": { "command": "npx", "args": ["-y", "agency-mcp-server"], "env": { "AGENCY_AGENTS_PATH": "/path/to/your/agent-templates" } } } }

Or clone from your own repo:

{

"mcpServers": { "agency": { "command": "npx", "args": ["-y", "agency-mcp-server"], "env": { "AGENCY_REPO_URL": "https://github.com/yourorg/custom-agents.git" } } } }

Template format

Each agent is a Markdown file with YAML front-matter, organized by division:

engineering/

software-architect.md devops-engineer.md design/ ui-designer.md game-development/ game-economy-designer.md

---

name: Software Architect description: Expert software architect specializing in system design...

---

Full agent system prompt goes here.

The server indexes the name and description fields for search. The full Markdown body becomes the agent's system prompt when spawned.

MCP Interface

Tools

• `agency_search(query, division?)` -- find agents by task description, returns matches with file paths and a ready-to-use spawn template
• `agency_browse(division?)` -- list all divisions, or list agents within a specific division
• `agency_status()` -- check index freshness: agent count, last update time, whether an update is due
• `agency_update()` -- pull latest templates from git and rebuild the search index at runtime

Resources

• `agency://agents` -- full agent index as JSON
• `agency://divisions` -- division list with counts and examples

Prompts

• `use-agent` -- describe a task, get the best-matching agent with spawn instructions

Development

npm install

npm run build

Run with auto-fetched templates

node dist/index.js

Run with local templates

AGENCY_AGENTS_PATH=./my-agents node dist/index.js

Type checking

npm run typecheck

MCP Inspector

npm run inspect

Credits

Agent templates from agency-agents by @msitarzewski.

License

MIT