foundry-mcp
Turn AI coding assistants into reliable software engineers with structured specs, progress tracking, and automated review.
Table of Contents
- Why foundry-mcp?
- Key Features
- Installation
- Quick Start
- How It Works
- Configuration
- Advanced Usage
- Documentation
- Scope and Limitations
- Testing
- Contributing
- License
Why foundry-mcp?
The problem: AI coding assistants are powerful but unreliable on complex tasks. They lose context mid-feature, skip steps without warning, and deliver inconsistent results across sessions.
The solution: foundry-mcp provides the scaffolding to break work into specs, track progress, and verify outputs—so your AI assistant delivers like a professional engineer.
- No more lost context — Specs persist state across sessions so the AI picks up where it left off.
- No more skipped steps — Task dependencies and blockers ensure nothing gets missed.
- No more guessing progress — See exactly what's done, what's blocked, and what's next.
- No more manual review — AI review validates implementation against spec requirements.
Key Features
- Specs keep AI on track — Break complex work into phases and tasks the AI can complete without losing context.
- Progress you can see — Track what's done, what's blocked, and what's next across multi-session work.
- AI-powered review — LLM integration reviews specs, generates PR descriptions, and validates implementation.
- Works with your tools — Runs as MCP server (Claude Code, Gemini CLI) or standalone CLI with JSON output.
- Security built in — Workspace scoping, API key auth, rate limits, and audit logging ship by default.
- Discovery-first — Capabilities declared in a manifest so clients negotiate features automatically.
Installation
Prerequisites
- Python 3.10 or higher
- macOS, Linux, or Windows
- MCP-compatible client (e.g., Claude Code)
Install with uvx (recommended)
uvx foundry-mcp
Install with pip
pip install foundry-mcp
Install from source (development)
git clone https://github.com/tylerburleigh/foundry-mcp.git
cd foundry-mcp
pip install -e ".[test]"
Quick Start
1. Install the claude-foundry plugin (from within Claude Code):
/plugin marketplace add foundry-works/claude-foundry
/plugin install foundry@claude-foundry
Restart Claude Code and trust the repository when prompted.
Note: The plugin automatically registers the MCP server using
uvx— no separate installation needed.
2. Run setup:
Please run foundry-setup to configure the workspace.
3. Start building:
I want to add user authentication with JWT tokens.
Claude creates a spec with phases, tasks, and verification steps. Ask to implement and it works through tasks in dependency order.
How It Works
foundry-mcp is the MCP server that provides the underlying tools and APIs. The claude-foundry plugin provides the user-facing skills that orchestrate workflows.
You → Claude Code → claude-foundry plugin → foundry-mcp server
│ │ │
▼ ▼ ▼
Natural Skills like MCP tools for
language foundry-spec, specs, tasks,
requests foundry-implement reviews, etc.
| Component | Role |
|---|---|
| foundry-mcp | MCP server + CLI providing spec/task/review tools |
| claude-foundry | Claude Code plugin providing skills and workflow |
For most users, install both and interact through natural language. The plugin handles tool orchestration automatically.
Configuration
API Keys
foundry-mcp uses LLM providers for AI-powered features like spec review, consensus, and deep research. Set the API keys for providers you want to use:
# AI CLI tools (for AI review, consensus)
export CLAUDE_CODE_OAUTH_TOKEN="..." # Get via: claude setup-token
export GEMINI_API_KEY="..."
export OPENAI_API_KEY="sk-..."
export CURSOR_API_KEY="key-..."
# Deep research providers (for /foundry-research deep workflow)
export TAVILY_API_KEY="..."
export PERPLEXITY_API_KEY="..."
TOML Configuration (Optional)
Configuration loads in layers (later layers override earlier):
- User config (
~/.foundry-mcp.toml) - User-wide defaults for API keys, preferred providers - Project config (
./foundry-mcp.toml) - Project-specific settings
# For user-wide settings (API keys, provider preferences)
cp samples/home-foundry-mcp.toml ~/.foundry-mcp.toml
# For project-specific settings
cp samples/foundry-mcp.toml ./foundry-mcp.toml
Advanced Usage
Direct MCP Configuration (without plugin)
For MCP clients other than Claude Code, or if you prefer manual configuration:
{
"mcpServers": {
"foundry-mcp": {
"command": "uvx",
"args": ["foundry-mcp"],
"env": {
"FOUNDRY_MCP_SPECS_DIR": "/path/to/specs"
}
}
}
}
Using a pip installation instead?
{
"mcpServers": {
"foundry-mcp": {
"command": "foundry-mcp",
"env": {
"FOUNDRY_MCP_SPECS_DIR": "/path/to/specs"
}
}
}
}
CLI Usage
All MCP tools are also available via CLI with JSON output:
# Get next task to work on
python -m foundry_mcp.cli task next --specs-dir ./specs
# Validate a spec
python -m foundry_mcp.cli spec validate my-feature-001
# Create a new spec
python -m foundry_mcp.cli authoring create --name "my-feature" --template detailed
Launch as Standalone MCP Server
foundry-mcp
The server advertises its capabilities, feature flags, and response contract so MCP clients (Claude Code, Gemini CLI, etc.) can connect automatically.
Documentation
User guides
| Guide | Description |
|---|---|
| Quick Start | Get up and running in 5 minutes |
| Core Concepts | Understand specs, phases, and tasks |
| Workflow Guide | End-to-end development workflows |
| CLI Reference | Complete CLI command documentation |
| MCP Tool Reference | All MCP tools and their parameters |
| Configuration | Environment variables and TOML setup |
| Troubleshooting | Common issues and solutions |
Concepts
| Guide | Description |
|---|---|
| Foundry Philosophy | Why spec-driven development matters |
| Response Envelope | Standardized response format |
| Spec Schema | Spec file structure and fields |
| LLM Configuration | Provider setup and fallbacks |
Developer docs
| Guide | Description |
|---|---|
| Dev Docs Index | Entry point for developer documentation |
| MCP Best Practices | Canonical implementation checklist |
| Response Schema | Standardized envelope reference |
| CLI Output Contract | JSON-first CLI expectations |
Scope and Limitations
Best for:
- Multi-step feature development with AI assistants
- Teams wanting structured handoff between AI and human reviewers
- Projects requiring audit trails and progress visibility
Not suited for:
- Quick one-off code changes (use your AI assistant directly)
- Non-software tasks (specs are code-focused)
- Fully autonomous AI agents (foundry assumes human oversight)
Testing
pytest # Full suite
pytest tests/integration/test_mcp_smoke.py # MCP smoke tests
pytest tests/integration/test_mcp_tools.py # Tool contract coverage
- Regression tests keep MCP/CLI adapters aligned across surfaces.
- Golden fixtures (
tests/fixtures/golden) ensure response envelopes, error semantics, and pagination never regress. - Freshness checks run alongside core unit and integration suites.
Contributing
Contributions are welcome! Please read the MCP Best Practices before submitting PRs. All changes should keep specs, docs, code, and fixtures in sync.
License
MIT License — see LICENSE for details.
Built by Tyler Burleigh · Report an Issue · View on GitHub
1 maintainer
Metadata
1 maintainer
Release files for foundry-mcp 0.16.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| foundry_mcp-0.16.0.tar.gz | 2.4 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| foundry_mcp-0.16.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 3.4 MB
Release files / foundry_mcp-0.16.0.tar.gz
| Download URL | foundry_mcp-0.16.0.tar.gz |
|---|---|
| Size | 2.4 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e9e6b10f5a01b9071ae210275b7dd2ca7380c69816b6751582fbb5956fdaecc7
|
|
BLAKE2b-256 checksum How to use checksums |
0bcadb2408a051ad43b8f473073a2cc3e3bdf2ae6bc7d7a1919158a9f689858e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Feb 23, 2026.
Transparency logRelease files / foundry_mcp-0.16.0-py3-none-any.whl
| Download URL | foundry_mcp-0.16.0-py3-none-any.whl |
|---|---|
| Size | 1.0 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
099a6eb6e4fdcf010dbe984decc92e4098c6992a141e21f019290d567905c7d3
|
|
BLAKE2b-256 checksum How to use checksums |
5631e537560b46d6249d3d49f7262a1fec984afe93ce3e1bc276e7884a33c572
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Feb 23, 2026.
Transparency log
