{
  "markdown": "# agency-mcp-server\n\n[![npm version](https://img.shields.io/npm/v/agency-mcp-server)](https://www.npmjs.com/package/agency-mcp-server)\n[![JSR](https://jsr.io/badges/@npupko/agency-mcp-server)](https://jsr.io/@npupko/agency-mcp-server)\n[![CI](https://github.com/npupko/agency-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/npupko/agency-mcp-server/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n\n> One MCP config entry. 150+ specialist agents on demand. No manual setup.\n\nYour 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.\n\n```\nYou: \"Help me design a balanced game economy\"\nClaude: [searches -> finds Game Economy Designer -> spawns it -> expert response]\n```\n\nTemplates auto-fetch on first run from [agency-agents](https://github.com/msitarzewski/agency-agents) and stay updated. You don't touch a thing.\n\n## Why not just install agents locally?\n\nYou can. The [agency-agents](https://github.com/msitarzewski/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.\n\nWe measured it:\n\n| Approach | Context cost | When |\n|----------|-------------|------|\n| Installed agents (`~/.claude/agents/`) | **~8,300 tokens** | Every conversation, always |\n| MCP server (idle) | **~55 tokens** | Every conversation |\n| MCP server (searching) | **~350 tokens** | Only when you search |\n| MCP server (using an agent) | **~2,700 tokens** | Only when you spawn one (median) |\n\nThat'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.\n\n<details>\n<summary>How we measured this</summary>\n\n**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.\n\n**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.\n\n**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`.\n\n**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).\n\n</details>\n\n## Quick Start\n\n### Claude Code\n\nAs a plugin:\n\n```bash\n/plugin marketplace add npupko/agency-mcp-server\n/plugin install agency@agency-mcp-server\n```\n\nOr via CLI:\n\n```bash\nclaude mcp add agency -- npx -y agency-mcp-server\n```\n\n### Cursor, Windsurf, and other MCP clients\n\nAdd to your MCP config:\n\n```json\n{\n  \"mcpServers\": {\n    \"agency\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"agency-mcp-server\"]\n    }\n  }\n}\n```\n\nThat's it. First launch clones templates to `~/.cache/agency-mcp-server/` and pulls updates every 24 hours.\n\n### Verify it works\n\nAsk your assistant:\n\n> \"Search for a game economy designer agent\"\n\nYou should see results from the `agency_search` tool. If it's the first run, templates will auto-download (~30 seconds).\n\n## How It Works\n\nYour assistant gets four tools:\n\n1. **`agency_search(query, division?)`** -- describe a task, get matching agents with spawn instructions\n2. **`agency_browse(division?)`** -- explore divisions and agents when you want to see what's available\n3. **`agency_status()`** -- check index freshness: agent count, last update time, whether an update is available\n4. **`agency_update()`** -- pull latest templates from git and rebuild the search index without restarting\n\nWhen 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.\n\n### What's available\n\nAgents are organized into divisions:\n\n| Division | Examples |\n|----------|----------|\n| Engineering | Software Architect, DevOps Engineer, Technical Writer |\n| Design | UI Designer, UX Researcher, Design Systems |\n| Game Development | Game Economy Designer, Game Mechanics Designer |\n| Marketing | Content Strategist, SEO Specialist, Email Marketing |\n| Security & Specialized | Security Auditor, Data Scientist, Legal Analyst |\n| ...and more | Academic, Sales, Strategy, Support, Testing, Spatial Computing |\n\n## Configuration\n\nAll configuration is through environment variables in your MCP config:\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `AGENCY_AGENTS_PATH` | `~/.cache/agency-mcp-server/agency-agents` | Path to agent templates. Set this to use your own templates instead of auto-cloning |\n| `AGENCY_REPO_URL` | `https://github.com/msitarzewski/agency-agents.git` | Git repo to clone templates from. Point at your fork |\n| `AGENCY_AUTO_UPDATE` | `true` | Set to `false` to disable automatic pulls |\n| `AGENCY_UPDATE_INTERVAL` | `24` | Hours between update checks |\n\n### Use your own templates\n\nPoint at a local directory:\n\n```json\n{\n  \"mcpServers\": {\n    \"agency\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"agency-mcp-server\"],\n      \"env\": {\n        \"AGENCY_AGENTS_PATH\": \"/path/to/your/agent-templates\"\n      }\n    }\n  }\n}\n```\n\nOr clone from your own repo:\n\n```json\n{\n  \"mcpServers\": {\n    \"agency\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"agency-mcp-server\"],\n      \"env\": {\n        \"AGENCY_REPO_URL\": \"https://github.com/yourorg/custom-agents.git\"\n      }\n    }\n  }\n}\n```\n\n### Template format\n\nEach agent is a Markdown file with YAML front-matter, organized by division:\n\n```\nengineering/\n  software-architect.md\n  devops-engineer.md\ndesign/\n  ui-designer.md\ngame-development/\n  game-economy-designer.md\n```\n\n```yaml\n---\nname: Software Architect\ndescription: Expert software architect specializing in system design...\n---\n\nFull agent system prompt goes here.\n```\n\nThe server indexes the `name` and `description` fields for search. The full Markdown body becomes the agent's system prompt when spawned.\n\n## MCP Interface\n\n### Tools\n\n- **`agency_search(query, division?)`** -- find agents by task description, returns matches with file paths and a ready-to-use spawn template\n- **`agency_browse(division?)`** -- list all divisions, or list agents within a specific division\n- **`agency_status()`** -- check index freshness: agent count, last update time, whether an update is due\n- **`agency_update()`** -- pull latest templates from git and rebuild the search index at runtime\n\n### Resources\n\n- **`agency://agents`** -- full agent index as JSON\n- **`agency://divisions`** -- division list with counts and examples\n\n### Prompts\n\n- **`use-agent`** -- describe a task, get the best-matching agent with spawn instructions\n\n## Development\n\n```bash\nnpm install\nnpm run build\n\n# Run with auto-fetched templates\nnode dist/index.js\n\n# Run with local templates\nAGENCY_AGENTS_PATH=./my-agents node dist/index.js\n\n# Type checking\nnpm run typecheck\n\n# MCP Inspector\nnpm run inspect\n```\n\n## Credits\n\nAgent templates from [agency-agents](https://github.com/msitarzewski/agency-agents) by [@msitarzewski](https://github.com/msitarzewski).\n\n## License\n\nMIT\n",
  "bytes": 7989,
  "sha": "d5d2b9f60da4a6ea917acbb9c32fc3514dde9f224365710340edfbef5049409d",
  "repo_slug": "npupko/agency-mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_npupko_agency_mcp_server_c289f552/readme"
}