MCP Server

intake exposes specs as an MCP (Model Context Protocol) server so that AI agents can consume specs programmatically. This enables direct integration with agents like Claude Code, Cursor, and any compatible MCP client.

intake mcp serve [OPTIONS]

Overview

The intake MCP server (name: intake-spec) provides:

9 tools — operations on specs: query, verify, validate, estimate costs, update tasks, analyze failures
6 resources — direct access to spec files via intake:// URIs
2 prompts — structured templates for implementation and fix flows
2 transports — stdio (local) and SSE (network)

The server allows an AI agent to access the complete spec, query pending tasks, update task status, run verification, and get fix suggestions — all without leaving its workflow.

Installation

The MCP server requires optional dependencies:

pip install "intake-ai-cli[mcp]"

This installs the mcp package needed for the protocol.

For SSE (HTTP) transport, additional dependencies are needed:

pip install "intake-ai-cli[mcp]" starlette uvicorn

Verify installation

intake doctor    # verifies that the mcp package is available

CLI command

intake mcp serve [OPTIONS]

Options

Option	Default	Description
`--specs-dir`	`./specs`	Base directory where specs reside
`--project-dir`	`.`	Project directory for verification
`--transport`	`stdio`	Transport: `stdio` or `sse`
`--port`	`8080`	Port for SSE transport

Examples

# stdio (default, for local agents like Claude Code)
intake mcp serve

# Custom specs directory
intake mcp serve --specs-dir ./output/specs

# SSE (for remote or network agents)
intake mcp serve --transport sse --port 9090

# Combination of options
intake mcp serve --specs-dir ./specs --project-dir /path/to/project --transport sse --port 8080

Tools

The server exposes 9 tools that agents can invoke:

intake_list_specs

Lists all available specs in the specs directory.

Parameter	Required	Description
(none)	—	No input required

Returns the list of spec names found.

intake_show

Shows a spec summary: number of requirements, tasks, acceptance checks, risks and costs.

Parameter	Required	Description
`spec_name`	Yes	Name of the spec

intake_get_context

Gets the content of context.md from a spec.

Parameter	Required	Description
`spec_name`	Yes	Name of the spec

intake_get_tasks

Gets the task list with optional status filtering.

Parameter	Required	Default	Description
`spec_name`	Yes	—	Name of the spec
`status_filter`	No	`"all"`	Status filter: `pending`, `in_progress`, `done`, `blocked`, `all`

Example usage by an agent:

{
  "spec_name": "mi-feature",
  "status_filter": "pending"
}

intake_update_task

Updates the status of a task.

Parameter	Required	Description
`spec_name`	Yes	Name of the spec
`task_id`	Yes	Task ID (e.g.: `"1"`, `"TASK-001"`)
`status`	Yes	New status: `pending`, `in_progress`, `done`, `blocked`
`note`	No	Optional note about the update

intake_verify

Runs the spec verification checks. Returns the pass/fail result for each check.

Parameter	Required	Description
`spec_name`	Yes	Name of the spec
`tags`	No	Array of tags to filter checks (e.g.: `["api", "tests"]`)

intake_feedback

Analyzes verification failures and suggests fixes. Internally runs verification, filters failed checks, and uses the feedback module to generate suggestions.

Parameter	Required	Description
`spec_name`	Yes	Name of the spec

intake_validate

Validates the internal consistency of a spec: cross-references, task dependencies, acceptance check validity and completeness. Works offline.

Parameter	Required	Default	Description
`spec_name`	Yes	—	Name of the spec
`strict`	No	`false`	Strict mode: warnings become errors

Returns a report with errors, warnings, and counts of requirements, tasks and checks found.

intake_estimate

Estimates the LLM cost to generate or regenerate a spec based on existing files.

Parameter	Required	Description
`spec_name`	Yes	Name of the spec

Scans spec files to count words and estimates tokens, number of LLM calls and cost in dollars.

Resources

Resources allow direct access to spec files via URIs with the intake:// scheme. Resources are auto-discovered: the server scans the specs directory and registers all available files.

Available URIs

URI	File
`intake://specs/{name}/requirements`	`requirements.md`
`intake://specs/{name}/tasks`	`tasks.md`
`intake://specs/{name}/context`	`context.md`
`intake://specs/{name}/acceptance`	`acceptance.yaml`
`intake://specs/{name}/design`	`design.md`
`intake://specs/{name}/sources`	`sources.md`

Where {name} is the name of the spec directory within the base specs directory.

Example

If the specs directory is ./specs and contains:

specs/
├── auth-module/
│   ├── requirements.md
│   ├── tasks.md
│   ├── context.md
│   ├── acceptance.yaml
│   ├── design.md
│   └── sources.md
└── payment-api/
    ├── requirements.md
    └── ...

The available resources would be:

intake://specs/auth-module/requirements
intake://specs/auth-module/tasks
intake://specs/auth-module/context
intake://specs/auth-module/acceptance
intake://specs/auth-module/design
intake://specs/auth-module/sources
intake://specs/payment-api/requirements
…

Prompts

The server provides 2 structured prompts that guide the agent through common workflows.

implement_next_task

Structured prompt that loads context.md, requirements.md and tasks.md, and instructs the agent to:

Find the next pending task
Implement it following the spec
Run verification
Update the task status
Repeat until all tasks are completed

Parameter	Required	Description
`spec_name`	Yes	Name of the spec

verify_and_fix

Prompt that instructs the agent to:

Run complete verification
Analyze failed checks
Fix the code
Re-verify until all checks pass

Parameter	Required	Description
`spec_name`	Yes	Name of the spec

Configuration

The MCP server is configured in .intake.yaml:

mcp:
  specs_dir: ./specs        # Base directory for specs
  project_dir: .            # Project directory for verification
  transport: stdio           # stdio | sse
  sse_port: 8080            # Port for SSE transport

Field	Type	Default	Description
`specs_dir`	string	`"./specs"`	Directory where specs generated by intake reside
`project_dir`	string	`"."`	Project directory against which to run verification
`transport`	string	`"stdio"`	Transport protocol: `stdio` for local agents, `sse` for network
`sse_port`	int	`8080`	TCP port for the SSE server

CLI flags (--specs-dir, --project-dir, --transport, --port) override configuration values.

Agent integration

Claude Code

Option 1: .mcp.json in the project (recommended for Claude Code CLI)

{
  "mcpServers": {
    "intake": {
      "command": "intake",
      "args": ["mcp", "serve", "--specs-dir", "./specs"]
    }
  }
}

Commit .mcp.json to the repo so the entire team has access to the MCP server automatically.

Option 2: claude_desktop_config.json (for Claude Desktop)

{
  "mcpServers": {
    "intake": {
      "command": "intake",
      "args": ["mcp", "serve", "--specs-dir", "./specs"]
    }
  }
}

With this configuration, Claude Code can:

List available specs with intake_list_specs
Read context and requirements via intake:// resources
Query pending tasks with intake_get_tasks
Mark tasks as completed with intake_update_task
Verify the implementation with intake_verify
Get fix suggestions with intake_feedback

Other MCP clients

Any MCP-compatible client can connect:

stdio — the client launches the process directly:

intake mcp serve --specs-dir ./specs

SSE — the client connects via HTTP:

# Start the server
intake mcp serve --transport sse --port 9090

# The client connects to http://localhost:9090/sse

Architecture

Modules

File	Responsibility
`mcp/__init__.py`	`MCPError` exception and public exports
`mcp/server.py`	Server creation, stdio and SSE transports
`mcp/tools.py`	Definition and handlers for the 9 tools
`mcp/resources.py`	Resource listing and reading (spec files)
`mcp/prompts.py`	2 structured prompt templates

Dependencies

The mcp/ module uses:

verify/ — to run acceptance checks (intake_verify)
utils/task_state — to read and update task state (intake_get_tasks, intake_update_task)
feedback/ — for failure analysis (intake_feedback)
validate/ — for internal spec validation (intake_validate)
estimate/ — for cost estimation (intake_estimate)

The mcp/ module does not import directly from analyze/ or llm/. The intake_feedback tool delegates to the feedback module, which manages its own LLM interaction.

mcp/
  ├── tools.py → verify/, validate/, estimate/, utils/task_state, feedback/
  ├── resources.py → (direct file reading)
  └── prompts.py → (static templates)

Troubleshooting

The `mcp` package is not installed

Error: MCP dependencies not installed. Run: pip install "intake-ai-cli[mcp]"

Solution: Install the MCP dependencies:

pip install "intake-ai-cli[mcp]"

Verify with intake doctor.

Spec not found

Error: Spec 'mi-feature' not found in ./specs

Solution: Verify that the specs directory exists and contains subdirectories with spec files:

ls ./specs/
# Should show directories like: mi-feature/

ls ./specs/mi-feature/
# Should contain: requirements.md, tasks.md, context.md, etc.

If specs are in a different directory, use --specs-dir:

intake mcp serve --specs-dir /path/to/specs

SSE port in use

Error: Address already in use: port 8080

Solution: Another process is using the port. Options:

Use a different port:

intake mcp serve --transport sse --port 9090

Find and stop the process using the port:
```
lsof -i :8080
kill <PID>
```

Missing SSE dependencies

If using SSE transport without starlette or uvicorn:

Error: SSE transport requires 'starlette' and 'uvicorn'. Install them with: pip install starlette uvicorn

Solution:

pip install starlette uvicorn

Verification fails from MCP

If intake_verify returns errors, verify that --project-dir points to the correct project directory:

intake mcp serve --specs-dir ./specs --project-dir /path/to/project

Acceptance checks are executed relative to the project directory.