OpenSpec MCP Server Integration

The OpenSpec MCP Server provides Model Context Protocol (MCP) integration, enabling any MCP-compatible AI assistant to directly interact with OpenSpec's change proposals, specifications, and project context. This optional implementation includes a web dashboard and approval workflow.

What is Model Context Protocol (MCP)?

Model Context Protocol (MCP) is a standard protocol that enables AI assistants to securely access external data sources and tools. By implementing OpenSpec as an MCP server, you can use OpenSpec workflows with any MCP-compatible AI assistant, including:

  • Claude (Anthropic)
  • GitHub Copilot
  • Amazon Q Developer
  • And other MCP-compatible tools

OpenSpec MCP Server Overview

The openspec-mcp project provides a complete MCP server implementation for OpenSpec with additional features:

🔌

MCP Protocol Support

Full Model Context Protocol implementation for universal AI assistant compatibility.

📊

Web Dashboard

Visual interface for managing changes, tracking tasks, and monitoring progress.

✅

Approval Workflow

Built-in approval system with status tracking and review management.

📋

Kanban Board

Drag-and-drop Kanban board with 6-column workflow visualization.

🔍

QA Dashboard

Monitor and trigger quality checks directly from the web interface.

📚

Context Analysis

Auto-detect tech stack and visualize project directory structure.

Installation

The OpenSpec MCP Server is available as a separate package. Install it using npm:

npm install -g openspec-mcp

Requirements:

  • Node.js >= 20.0.0
  • OpenSpec CLI installed (npm install -g @fission-ai/openspec)
  • An MCP-compatible AI assistant

Usage

MCP Server Only

Start the MCP server for your project:

# Uses current directory
openspec-mcp

# Or specify a project path
openspec-mcp /path/to/project

Web Dashboard Only

Start just the web dashboard:

openspec-mcp --dashboard

# Custom port
openspec-mcp --dashboard --port 8080

MCP Server with Dashboard

Run both MCP server and web dashboard together:

openspec-mcp --with-dashboard

Web Dashboard Features

Overview Dashboard

Statistics and recent changes at a glance. Monitor project health and progress.

Kanban Board

6-column workflow visualization: Backlog → Draft → Pending Approval → Approved → Implementing → Completed → Released. Drag-and-drop task management.

Change Management

List all changes with progress tracking. View detailed change pages with specs and tasks.

QA Dashboard

Monitor and trigger quality checks. View test results and validation status.

Context Analysis

Auto-detect tech stack and visualize directory structure. Understand project architecture.

Approval Queue

Manage approval requests. Approve or reject changes with comments.

Review Management

View, resolve, and track reviews. Open/Resolved tabs for review organization.

Cross-Service Documentation

View cross-service design documents. Visual services.yaml display for multi-service projects.

Available MCP Tools

The OpenSpec MCP server provides a comprehensive set of tools for managing OpenSpec workflows:

Changes

  • openspec_list_changes - List all changes
  • openspec_get_change - Get change details
  • openspec_create_change - Create new change
  • openspec_update_change - Update change
  • openspec_delete_change - Delete change

Proposals

  • openspec_get_proposal - Get proposal
  • openspec_update_proposal - Update proposal
  • openspec_validate_proposal - Validate proposal

Specs

  • openspec_list_specs - List specifications
  • openspec_get_spec - Get spec details
  • openspec_update_spec - Update spec

Tasks

  • openspec_get_tasks - Get tasks and progress
  • openspec_update_task - Update task status
  • openspec_get_progress_summary - Get progress summary

Approval

  • openspec_request_approval - Request approval
  • openspec_approve_change - Approve change
  • openspec_reject_change - Reject change
  • openspec_list_pending_approvals - List pending approvals

Reviews

  • openspec_add_review - Add review comment
  • openspec_list_reviews - List reviews
  • openspec_resolve_review - Mark review as resolved

Approval Workflow

The MCP server includes a built-in approval workflow system:

1

Draft

→
2

Pending Approval

→
3

Approved

→
4

Implementing

→
5

Completed

→
6

Archived

If a change is rejected, it returns to Draft status for revision and resubmission.

Cross-Service Documentation

For multi-service projects sharing a common .cross-service/ directory, the dashboard supports cross-service documentation:

---
crossService:
  rootPath: "../../../../.cross-service"
  documents:
    - design.md
    - flows.md
    - services.yaml
  archivePolicy: snapshot
---
# Your proposal content...

The dashboard displays:

  • design.md / flows.md: Rendered as Markdown
  • services.yaml: Visual card view with service status, changes, and deployment order

When to Use the MCP Server

Use MCP Server If:

  • ✓ You use MCP-compatible AI assistants
  • ✓ You want a visual dashboard for change management
  • ✓ You need an approval workflow system
  • ✓ You work with multiple team members
  • ✓ You want Kanban-style task visualization
  • ✓ You need QA monitoring and reporting

Use CLI Only If:

  • ✓ You prefer command-line workflows
  • ✓ You don't need visual dashboards
  • ✓ You work solo or in small teams
  • ✓ You want minimal setup overhead
  • ✓ You use tools with native slash commands

Resources

Note: The OpenSpec MCP Server is a community implementation and is separate from the core OpenSpec CLI. The core OpenSpec CLI does not require MCP integration and works with slash commands or AGENTS.md files.