mcp-server-alexandria

171 expert AI agents as native tools in Claude Code, Claude Desktop, and any MCP client.

Alexandria's specialist agents — engineers, marketers, product managers, financial analysts, lawyers, and more — accessible directly from your conversations via the Model Context Protocol. All responses use structured output with extractable code files. LLM-agnostic (Anthropic, OpenAI, Gemini).

Quick Start

1. Authenticate

# Install the CLI and log in with GitHub (one-time setup)
pip install alexandria-cli
alexandria login

This creates ~/.alexandria/credentials.json — the MCP server picks it up automatically.

Alternatively, set an API key directly:

export ALEXANDRIA_API_KEY=your-key

2. Add to your editor

Claude Code:

# If you used `alexandria login` (no env var needed):
claude mcp add alexandria -- npx mcp-server-alexandria

# Or with an explicit API key:
claude mcp add alexandria -e ALEXANDRIA_API_KEY=your-key -- npx mcp-server-alexandria

Claude Desktop — edit ~/Library/Application Support/Claude/claude_desktop_config.json:

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

Restart Claude Desktop. Alexandria tools appear in your conversation.

Alternative package name

# Same server, shorter name:
npx alexandria-mcp

Tools

alexandria_ask — Auto-route to best agent

Describe any task. Alexandria selects the best specialist, executes, and returns structured output.

Parameters: | Parameter | Required | Description | |-----------|----------|-------------| | task | yes | What you need done | | project | no | Project name for memory scoping | | max_agents | no | Max agents to use (default: 10) | | context_tags | no | Tags for context (e.g., ["b2b", "saas"]) |

Example — generate a React hook:

Prompt: "Use alexandria_ask to generate a type-safe React hook for form validation with tests"

Response:

{
  "result": "Here's a type-safe useFormValidation hook with full test coverage...",
  "files": [
    {
      "path": "src/hooks/useFormValidation.ts",
      "language": "typescript",
      "content": "import { useState, useCallback } from 'react';\n\nexport interface ValidationRule {\n  validate: (value: string) => boolean;\n  message: string;\n}\n\nexport function useFormValidation(rules: Record<string, ValidationRule[]>) {\n  // ... full implementation\n}"
    },
    {
      "path": "src/hooks/__tests__/useFormValidation.test.ts",
      "language": "typescript",
      "content": "import { renderHook, act } from '@testing-library/react-hooks';\nimport { useFormValidation } from '../useFormValidation';\n\ndescribe('useFormValidation', () => {\n  // ... full test suite\n});"
    },
    {
      "path": "src/hooks/index.ts",
      "language": "typescript",
      "content": "export { useFormValidation } from './useFormValidation';\nexport type { ValidationRule } from './useFormValidation';"
    }
  ],
  "commands": ["npm install"],
  "confidence": 0.92,
  "agent_used": "frontend-developer"
}

alexandria_run_agent — Run a specific agent

Run a named agent directly. Supports file context injection — pass existing code files and the agent sees their full content.

Parameters: | Parameter | Required | Description | |-----------|----------|-------------| | agent | yes | Agent slug (e.g., code-reviewer, frontend-developer) | | task | yes | The task | | provider | no | anthropic, openai, or gemini | | files | no | Array of {path, content} objects for file context |

Example — code review with file context:

Prompt: "Use alexandria_run_agent with code-reviewer to review my trading bot"

Pass the file content in the files parameter:

{
  "agent": "code-reviewer",
  "task": "Review this trading bot for bugs and improvements",
  "files": [
    {
      "path": "src/TradingBot.ts",
      "content": "class TradingBot {\n  private bankroll: number = 1000;\n  setBankroll(amount: number) { this.bankroll = amount; }\n  // ...\n}"
    }
  ]
}

Response:

{
  "result": "## Code Review: TradingBot\n\n### Issues Found\n1. **Missing input validation** — `setBankroll(amount)` accepts negative values. Add guard: `if (amount < 0) throw new Error('...')`\n2. **No bankroll bounds checking** — the bankroll field (currently 1000) has no max limit\n3. **Race condition risk** — concurrent `setBankroll` calls could corrupt state\n\n### Recommendations\n- Add input validation on all public methods\n- Consider using immutable state pattern\n- Add unit tests for edge cases",
  "files": [],
  "commands": [],
  "confidence": 0.95,
  "agent_used": "code-reviewer"
}

The agent referenced the TradingBot class, setBankroll method, and bankroll value by name — it received the full file content.

alexandria_list_agents — Discover agents

Browse and search the agent library by team or keyword.

Parameters: | Parameter | Required | Description | |-----------|----------|-------------| | team | no | Filter by team (e.g., engineering, marketing) | | search | no | Search by name or description |

Example — list engineering agents:

{
  "team": "engineering"
}

Response:

{
  "agents": [
    { "name": "ai-engineer", "team": "engineering", "description": "AI/ML engineering specialist" },
    { "name": "backend-architect", "team": "engineering", "description": "Backend architecture and API design" },
    { "name": "devops-automator", "team": "engineering", "description": "CI/CD, infrastructure, deployment" },
    { "name": "frontend-developer", "team": "engineering", "description": "Frontend development, React, TypeScript" }
  ],
  "count": 4
}

alexandria_get_tools — Export as OpenAI function-calling schema

Export Alexandria agents as OpenAI-compatible function-calling tool definitions. Useful for integrating agents into your own tool-using LLM pipelines.

Parameters: | Parameter | Required | Description | |-----------|----------|-------------| | team | no | Filter by team | | agents | no | Specific agent slugs to export |

alexandria_learn — Store learnings

Store insights into Alexandria's memory for retrieval in future sessions.

Parameters: | Parameter | Required | Description | |-----------|----------|-------------| | text | yes | The learning/insight to store | | agent_name | no | The agent that produced this learning | | project | no | Project scope |

Example:

{
  "text": "B2B cold outreach converts 3x better on Tuesday mornings vs Friday afternoons",
  "agent_name": "sales-strategist",
  "project": "growth-experiments"
}

alexandria_generate_image — Generate images

Generate images using multiple AI providers. Supports Gemini Nano Banana (default), OpenAI DALL-E 3, xAI Aurora, Stability AI SD3.5, and FAL.ai Flux Pro.

Parameters: | Parameter | Required | Description | |-----------|----------|-------------| | prompt | yes | Text description of the image to generate | | provider | no | gemini (default), openai, xai, stability, fal | | style_guide | no | Detailed style instructions (e.g., "flat vector, minimalist") | | resolution | no | Output resolution (default: 1024x1024) | | api_key | no | Provider API key (falls back to server env vars) |

Example:

{
  "prompt": "minimalist logo for a tech startup",
  "provider": "gemini",
  "style_guide": "flat vector, clean lines, modern"
}

Response includes base64 image data, file save path, and revised prompt.

alexandria_health — Status check

No parameters. Returns API health status.

alexandria_doctor — Self-diagnostic

No parameters. Runs 8 checks: MCP mode, LLM provider, auth type, Data API auth, API connectivity (vector DB / embeddings / database), .alexandria/ project detection, agent catalog, routing, and trust data. Prints a green/yellow/red dashboard with action recommendations. Use this first when something feels off.

Structured Output

All agent executions return a consistent schema:

{
  result: string;          // The agent's main response
  files: Array<{           // Extractable code files (empty if not a coding task)
    path: string;          // Suggested file path
    language: string;      // Language identifier
    content: string;       // Full file content, ready to write
  }>;
  commands: string[];      // Shell commands to run (e.g., "npm install")
  confidence: number;      // 0-1 confidence score
  agent_used: string;      // Which agent handled the task
}

The files array is the key addition — when an agent generates code, each file is separated out with its path, language, and content. Your workflow can extract and write these files directly.

/gm/ask/stream Endpoint

For programmatic use outside MCP, the streaming endpoint auto-routes to the best agent and streams the response:

curl -N -X POST https://agenticteam-production.up.railway.app/gm/ask/stream \
  -H "Authorization: Bearer $ALEXANDRIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "task": "Create a React hook for debounced search"
  }'

Returns SSE events. Specify "agent": "agent-name" to target a specific agent.

LLM Execution (BYOT)

Alexandria never bills the server's LLM keys. The MCP runs in one of two modes:

Delegate mode (default when no provider key is set)

The MCP assembles the agent prompt + routing + memory context and returns it to the host LLM (e.g., Claude Code), which produces the agent's output using its own credentials. Zero API keys needed, zero Alexandria cost, fully within Anthropic TOS.

This is the recommended mode for Claude Code and Claude Desktop users.

Execute mode (BYOT — when a provider key IS set)

Set one of the following environment variables and the MCP will call the provider directly:

| Provider | Env var | Default model | |---|---|---| | Anthropic | ANTHROPIC_API_KEY | claude-sonnet-4-6 | | OpenAI | OPENAI_API_KEY | gpt-5 | | Gemini | GEMINI_API_KEY / GOOGLE_API_KEY | gemini-2.5-flash | | Groq | GROQ_API_KEY | llama-3.3-70b-versatile | | Mistral | MISTRAL_API_KEY | mistral-large-latest | | OpenRouter | OPENROUTER_API_KEY | anthropic/claude-sonnet-4-6 |

Override provider selection with LLM_PROVIDER=anthropic|openai|gemini|groq|mistral|openrouter. Override the default mode with ALEXANDRIA_MODE=delegate|execute|auto (default is auto).

Claude Code subscription tokens

ANTHROPIC_API_KEY also accepts Claude Code OAuth / subscription tokens (the sk-ant-oat-* kind issued by claude login). The MCP detects the token prefix and switches from x-api-key auth to Authorization: Bearer + the required anthropic-beta headers automatically. No extra configuration.

Limitations with subscription tokens:

• Streaming is not supported — the MCP will throw a clear error if stream: true is requested with an OAuth token. Use a raw API key from console.anthropic.com if you need streaming.

Tips

• Discover first: Use alexandria_list_agents to browse available specialists before running tasks.
• Be specific with alexandria_run_agent: When you know which agent you want, call it directly — faster than auto-routing.
• Use alexandria_ask for ambiguous tasks: Let the GM pick the right specialist when you're not sure which agent fits.
• Pass file context: The files parameter lets agents see your actual code. Reviews and refactors are dramatically better with real context.
• Check files[] in responses: Code generation tasks return extractable files — use them directly instead of copying from the result text.

Authentication

The MCP server resolves credentials in this order:

1. ALEXANDRIA_API_KEY env var → sent as X-API-Key header
2. API_SECRET_KEY env var → sent as X-API-Key header
3. ~/.alexandria/credentials.json from alexandria login → sent as Bearer token

Most users should run alexandria login once. The credentials file is created with restricted permissions (0600).

License

MIT — Alexandria agents are yours to use with your own API keys.