foundationworks-mcp

Connect your AI coding agent to your product specs.

Design in Foundation → Connect via MCP → Vibe code your product

What is this?

MCP server that gives Claude, Cursor, Windsurf, and other AI agents access to your PRDs and TDDs in Foundation.

Foundation is a design workspace for creating product requirements (PRDs) and technical design documents (TDDs). This MCP server lets your AI coding agent read those specs directly, so it builds what you actually designed.

Quick Start

1. Get your token

Existing user: Settings → Agent Tokens → Create Token

New here? Sign up at foundationworks.io

2. Install the package

npm install -g foundationworks-mcp

3. Configure your AI tool

Claude Desktop (~/.claude/config.json):

{
  "mcpServers": {
    "foundation": {
      "command": "foundationworks-mcp",
      "env": {
        "FOUNDATION_TOKEN": "mcp_your_token_here"
      }
    }
  }
}

Claude Code (~/.claude/settings.json):

{
  "mcpServers": {
    "foundation": {
      "command": "foundationworks-mcp",
      "env": {
        "FOUNDATION_TOKEN": "mcp_your_token_here"
      }
    }
  }
}

Cursor (MCP settings):

{
  "foundation": {
    "command": "foundationworks-mcp",
    "env": {
      "FOUNDATION_TOKEN": "mcp_your_token_here"
    }
  }
}

Zed (~/.config/zed/settings.json):

{
  "context_servers": {
    "foundation": {
      "command": "foundationworks-mcp",
      "env": {
        "FOUNDATION_TOKEN": "mcp_your_token_here"
      }
    }
  }
}

Note: You can also use npx -y foundationworks-mcp instead of installing globally, but this may cause connection timeouts in some editors due to slower startup.

3. Start building

Ask your AI: "Check my PRD for the authentication requirements"

Tools

| Tool | Description | |------|-------------| | foundation_menu | List available sections with summaries, keywords, and token counts | | foundation_fetch | Get full content for specific sections | | foundation_search | Semantic search across your specs | | foundation_comment | Post deviation reports or suggestions back to your docs | | foundation_comments | Read your comments and human replies | | foundation_fetch_work | Fetch available agent tasks from the task queue | | foundation_claim_task | Atomically claim a task for execution | | foundation_report_progress | Report progress on an assigned task | | foundation_submit_result | Submit task results for approval |

Example Workflow

You: "What does the PRD say about user authentication?"

AI: [calls foundation_menu to see available sections]
AI: [calls foundation_search with "user authentication"]
AI: [calls foundation_fetch to get the relevant sections]
AI: "Based on your PRD, authentication should use..."

When implementation differs from spec:

AI: [calls foundation_comment with a deviation_report]
AI: "I've noted that we're using JWT instead of sessions as specified.
     Posted a deviation report to the PRD for your team to review."

Checking for feedback before continuing:

AI: [calls foundation_comments to read previous comments and replies]
AI: "The team resolved your deviation report about JWT — they confirmed
     JWT is the correct approach. Continuing with Epic 2."

Fetching and executing agent tasks:

AI: [calls foundation_fetch_work to find available tasks]
AI: [calls foundation_claim_task to claim a code_gen task]
AI: "Claimed task: Generate API endpoints for user authentication"

AI: [works on task, calling foundation_report_progress periodically]
AI: [calls foundation_submit_result with the generated code]
AI: "Task complete! Result submitted for approval."

Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | FOUNDATION_TOKEN | Yes | — | Your agent token from Foundation | | FOUNDATION_API_URL | No | https://api.foundationworks.io/api/v1/mcp | API base URL |

Why use this?

Without Foundation MCP:

• Copy-paste specs into chat
• AI forgets context between sessions
• No record of what the AI actually built vs. what was designed

With Foundation MCP:

• AI reads your specs directly
• Specs stay up-to-date in one place
• Deviation reports track where implementation differs from design

License

MIT