npm package: @getdisko/mcp-server
Description: DISKO MCP Server — connect Claude Code to your DISKO project
Latest version: 0.2.0

# DISKO MCP Server

Connect Claude Code (or any MCP-compatible AI tool) to your DISKO project. Read tasks, specs, prototypes, and product DNA — write implementation plans, record decisions, and ask your PM clarifying questions — all without leaving your IDE.

## Quick Start

### 1. Generate an API key

Open DISKO → **Settings** (gear icon) → **MCP Keys** tab → name your key → **Create Key** → copy it.

> The key is shown once. If you lose it, revoke and create a new one.

### 2. Find your Project ID

Your Project ID is in the URL when you open any project in DISKO:

```
https://app.getdisko.io/project/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
                                 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
                                 this is your project ID
```

### 3. Add to your project

Create a `.mcp.json` file in your project root:

```json
{
  "mcpServers": {
    "disko": {
      "command": "npx",
      "args": ["@getdisko/mcp-server"],
      "env": {
        "DISKO_API_KEY": "dk_live_your_key_here",
        "DISKO_PROJECT_ID": "your-project-uuid"
      }
    }
  }
}
```

### 4. Restart Claude Code

After saving `.mcp.json`, restart Claude Code. You should see `disko` listed as a connected MCP server.

Verify by asking: *"What tasks are in the Plan column?"*

---

## What You Can Do

### Read your board

| Ask Claude... | What happens |
|---|---|
| "What tasks are in Plan?" | Lists all tasks filtered by column |
| "Get me the details on DISKO-42" | Returns full task with spec, prototype, impl plan |
| "Search for tasks about authentication" | Full-text search across titles and descriptions |

### Read specs & prototypes

| Ask Claude... | What happens |
|---|---|
| "Show me the spec for DISKO-42" | Returns the PM's spec document (markdown) |
| "What changed in the spec?" | Returns spec version history with change summaries |
| "Get the prototype for DISKO-42" | Returns the prototype HTML |
| "What's the implementation plan?" | Returns the dev's implementation plan |

### Query product DNA

| Ask Claude... | What happens |
|---|---|
| "What decisions have we made about auth?" | Searches decisions by keyword |
| "List all active technical decisions" | Filters by status and category |
| "What features are specced?" | Lists features by status |

### Get project context

| Ask Claude... | What happens |
|---|---|
| "What's the project context?" | Returns domain, tech stack, goals, terminology, DNA summary |
| "What happened since yesterday?" | Returns recent activity across the project |

### Write back to DISKO

| Ask Claude... | What happens |
|---|---|
| "Create a task for fixing the auth bug" | Creates a task on the board |
| "Move DISKO-42 to Ready" | Updates the task's column |
| "Write an implementation plan for DISKO-42" | Saves the plan (separate from PM's spec) |
| "Add a comment on DISKO-42" | Posts a dev comment to the activity feed |
| "Record a decision: we chose Postgres over Mongo" | Saves to product DNA, tagged as from dev |
| "Ask the PM: should login support SSO?" | Posts a clarification question the PM sees in DISKO |

---

## Tool Reference

### Board & Tasks

| Tool | R/W | Description |
|---|---|---|
| `list_tasks` | R | List tasks with optional filters (column, priority, search) |
| `get_task` | R | Full task details by display ID (`DISKO-42`) or UUID |
| `search_tasks` | R | Full-text search across task titles and descriptions |
| `create_task` | W | Create a new task with title, description, priority |
| `update_task` | W | Update column, priority, title, description, or due date |
| `add_task_comment` | W | Add a dev comment to a task's activity feed |

### Specs & Implementation

| Tool | R/W | Description |
|---|---|---|
| `get_spec` | R | Current spec document for a task (markdown) |
| `get_spec_versions` | R | Version history with change summaries |
| `get_prototype` | R | Prototype HTML (self-contained, renderable) |
| `get_implementation_plan` | R | Current implementation plan for a task |
| `update_implementation_plan` | W | Write/update the dev's implementation plan |

### Product DNA

| Tool | R/W | Description |
|---|---|---|
| `lookup_dna` | R | Search across decisions and features by keyword |
| `get_decisions` | R | List decisions with optional status/category filters |
| `get_features` | R | List features with optional status filter |
| `create_decision` | W | Record a new product/technical decision |
| `supersede_decision` | W | Replace an existing decision (preserves history) |

### Project Context

| Tool | R/W | Description |
|---|---|---|
| `get_project_context` | R | Full project context: domain, stack, goals, DNA summary |
| `get_recent_activity` | R | Recent activity across the project |

### Communication

| Tool | R/W | Description |
|---|---|---|
| `ask_clarification` | W | Ask the PM a question about a task |

**Total: 12 read, 7 write, 0 delete.**

---

## Configuration Options

All configuration is via environment variables in `.mcp.json`:

| Variable | Required | Default | Description |
|---|---|---|---|
| `DISKO_API_KEY` | Yes | — | Your MCP API key from DISKO Settings |
| `DISKO_PROJECT_ID` | Yes | — | The project UUID from your DISKO URL |
| `DISKO_URL` | No | `https://app.getdisko.io` | DISKO instance URL (for self-hosted) |
| `DISKO_READ_ONLY` | No | `false` | Set to `true` to hide all write tools |
| `DISKO_TOOLS` | No | all | Comma-separated tool categories to enable |

### Read-only mode

If you want to give someone read-only access (no writes to your board):

```json
{
  "mcpServers": {
    "disko": {
      "command": "npx",
      "args": ["@getdisko/mcp-server"],
      "env": {
        "DISKO_API_KEY": "dk_live_their_key",
        "DISKO_PROJECT_ID": "your-project-uuid",
        "DISKO_READ_ONLY": "true"
      }
    }
  }
}
```

### Tool filtering

Only expose specific tool categories:

```json
{
  "env": {
    "DISKO_TOOLS": "tasks,specs"
  }
}
```

Available categories: `tasks`, `specs`, `dna`, `context`, `communication`

Tool filtering composes with read-only mode — `DISKO_TOOLS=tasks` + `DISKO_READ_ONLY=true` exposes only the 3 read-only task tools.

### Multiple projects

Each MCP server instance connects to one project. To work across multiple projects, add a separate entry for each:

```json
{
  "mcpServers": {
    "disko-backend": {
      "command": "npx",
      "args": ["@getdisko/mcp-server"],
      "env": {
        "DISKO_API_KEY": "dk_live_your_key",
        "DISKO_PROJECT_ID": "uuid-for-backend-project"
      }
    },
    "disko-mobile": {
      "command": "npx",
      "args": ["@getdisko/mcp-server"],
      "env": {
        "DISKO_API_KEY": "dk_live_your_key",
        "DISKO_PROJECT_ID": "uuid-for-mobile-project"
      }
    }
  }
}
```

The same API key works across all your projects. Claude Code will see tools from both servers — prefixed by server name (e.g., `disko-backend` and `disko-mobile`) so there's no collision.

---

## The PM-Dev Loop

This is what makes DISKO different. Your PM works in DISKO, you work in your IDE, and the MCP server is the bridge:

```
PM (in DISKO)                          Dev (in IDE with Claude Code)
─────────────                          ────────────────────────────
1. Creates task DISKO-42        →
2. Writes spec via chat         →
3. Refines with enrichment      →
4. Prototype generated          →
                                       5. "Get me DISKO-42" → reads spec + prototype
                                       6. Writes implementation plan
                                       7. "Ask PM: should login support SSO?"
8. Sees question, answers       ←
                                       9. "Get DISKO-42" → reads PM's answer
                                       10. Implements the feature
                                       11. "Move DISKO-42 to Ready"
                                       12. "Record decision: chose JWT over sessions"
13. Board updated               ←
14. Decision in product DNA     ←
```

---

## Troubleshooting

**"DISKO_API_KEY environment variable is required"**
Your `.mcp.json` is missing the API key, or the env var name is misspelled.

**"Failed to validate connection"**
Either your API key is invalid/revoked, or your project ID doesn't match a project you own. Check both in DISKO Settings.

**Server shows as disconnected in Claude Code**
Make sure you have Node.js 18+ installed (`node --version`). Restart Claude Code after editing `.mcp.json`.

**Tools don't appear**
If using `DISKO_TOOLS`, check for typos in category names. Valid categories: `tasks`, `specs`, `dna`, `context`, `communication`.

**"Project not found" errors**
The `DISKO_PROJECT_ID` must be the UUID from the URL, not the project name.

---

## Requirements

- Node.js 18 or later
- A DISKO account with at least one project
- Claude Code, Cursor, Windsurf, or any MCP-compatible AI tool