Foundry

You install and run the Foundry MCP server to enable spec-driven development for AI assistants. The server provides a single service layer for CLI and MCP tooling, supports a complete spec lifecycle, feature-flagged tool suites, and a standardized response envelope that clients can negotiate and consume reliably.

How to use

You run the MCP server locally and connect your MCP client (such as Claude Code or Gemini CLI) to access spec management, task planning, code and test tooling, and LLM-powered review workflows. The server and CLI share a unified service layer, enabling you to switch between automated MCP clients and terminal workflows without losing capabilities. Use the server to manage specs, execute task flows, run tests, and leverage AI-assisted reviews when an LLM provider is configured.

How to install

Prerequisites are Python 3.10 or higher and a supported operating system (macOS, Linux, or Windows). You also need an MCP-compatible client when you plan to connect from external tools.

Install from source and run the server locally with the following steps.

# Install from source (development mode)
git clone https://github.com/tylerburleigh/foundry-mcp.git
cd foundry-mcp
pip install -e ".[test]"

# Run the MCP server
foundry-mcp

Configuration and usage notes

Configure your environment to point to your specs and enable the desired capabilities. You can adjust logging, workflow behavior, and security settings through environment variables and a TOML file. The server and client will negotiate the response contract version and feature flags during startup.

[workspace]
specs_dir = "/path/to/specs"

[logging]
level = "INFO"
structured = true

[workflow]
mode = "single"
auto_validate = true
journal_enabled = true

[llm]
provider = "openai"
model = "gpt-4"
timeout = 30

[security]
require_api_key = true
allowed_keys = ["tenant-prod", "tenant-dev"]
workspace_roots = ["/repos/specs"]

[feature_flags]
enabled = ["environment_tools", "spec_helpers", "planning_tools", "response_contract_v2"]

Getting started with a local MCP client

Launch the MCP server and then connect with an MCP client that supports the server’s capabilities. The server advertises capabilities, feature flags, and the response contract on startup so clients can adapt automatically.

Security and governance notes

Workspace boundaries, API keys, rate limiting, structured logging, and audit trails are enforced to protect access and data. You’ll configure keys and scopes to ensure that only authorized actors can use specific tools and workspaces.

Troubleshooting tips

If you encounter startup or connection issues, verify that your specs directory is accessible and that the server has permission to read it. Check that your API keys and environment variables are set correctly and that the selected response contract version matches your client capabilities.

Available tools

spec(action)

Discover and validate specs within the specs lifecycle and transition through pending, active, completed, and archived states.

lifecycle(action)

Manage spec state transitions and journal decisions, blockers, and dependency changes.

task(action)

Operate on tasks with actions like next, prepare, start, and complete to reveal and traverse the dependency graph.

plan(action)

Create, list, and review plans for spec work and feature development.

code(action)

Navigate code and trace symbols or call graphs within the spec-driven environment.

test(action)

Run tests with presets and capture structured results for the MCP workflow.

review(action)

Perform AI-assisted review and fidelity checks on specs or outputs when an LLM is configured.

server(action)

Interact with server context and tool availability through the MCP surface.

tools

Access the unified tool surface and capabilities exposed by the MCP server.