> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sudocode.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Use sudocode with AI assistants through Model Context Protocol

## What is MCP?

The sudocode MCP (Model Context Protocol) server enables AI assistants like Claude or Codex to directly interact with your sudocode project - finding work, creating issues, managing specs, and providing feedback.

<Note>
  Model Context Protocol (MCP) is an open standard developed by Anthropic that allows AI assistants to securely connect to external data sources and tools. Think of it as a standardized API that AI assistants can use to interact with your systems.
</Note>

The sudocode MCP server exposes 10 tools that agents can use to manage specs, issues, and relationships.

**Key benefits:**

* **Direct tool access**: AI can call sudocode commands without parsing text
* **Structured data**: Tools return JSON that AI can easily process
* **Workflow automation**: Agents can autonomously manage entire development workflows
* **Context awareness**: AI has full visibility into project state

## Why Use MCP with sudocode?

<CardGroup cols={2}>
  <Card title="Autonomous Development" icon="robot">
    **AI agents can self-direct**

    * Find and claim work independently
    * Create implementation plans
    * Provide feedback on specs
    * Manage task dependencies
  </Card>

  <Card title="Better Context" icon="brain">
    **AI understands your project**

    * Query issues and specs
    * Understand relationships
    * See what's blocked
    * Track project status
  </Card>

  <Card title="Workflow Integration" icon="arrows-rotate">
    **Seamless development flow**

    * Check ready work: `ready()`
    * Claim issues: `upsert_issue()`
    * Read specs: `show_spec()`
    * Link work: `link()`
  </Card>

  <Card title="Feedback Loop" icon="comments">
    **Bidirectional learning**

    * AI provides feedback on specs
    * Anchored comments at specific lines
    * Request clarifications
    * Suggest improvements
  </Card>
</CardGroup>

## Workflow Guides

Learn how to use sudocode MCP with these practical guides:

<CardGroup cols={3}>
  <Card title="Creating Specifications" icon="file-lines" href="/mcp/spec-creation">
    Capture requirements and design decisions that guide implementation
  </Card>

  <Card title="Creating Issues" icon="list-check" href="/mcp/issue-creation">
    Break down specs into actionable work items with dependencies
  </Card>

  <Card title="Executing Issues" icon="play" href="/mcp/issue-execution">
    How agents discover, claim, and complete work
  </Card>

  <Card title="Multi-Agent Coordination" icon="users" href="/mcp/multi-agent">
    Coordinate multiple AI agents working in parallel
  </Card>

  <Card title="Workflow Examples" icon="route" href="/mcp/workflows">
    6 practical workflow examples with tool invocations
  </Card>

  <Card title="Best Practices" icon="star" href="/mcp/agent-best-practices">
    Guidelines for effective agent work with sudocode
  </Card>
</CardGroup>

## MCP Tools Reference

The sudocode MCP server provides various tools for managing your project. Tools are organized by functionality and include complete parameter details.

### Issue Management Tools

**1. ready** - Find unblocked work

Find issues with no blockers that are ready to start.

* **Parameters:** None
* **Returns:** `{ issues: Issue[] }` - Array of ready issues
* **CLI equivalent:** `sudocode ready`

```typescript theme={null}
ready()
// Returns: { issues: [{ id: "ISSUE-001", title: "...", ... }] }
```

**2. list\_issues** - List and filter issues

Query issues with optional filters for status, priority, and search.

* **Parameters:**
  * `status` (string, optional): Filter by status - "open", "in\_progress", "blocked", "closed"
  * `priority` (number, optional): Filter by priority (0-4, 0=highest)
  * `archived` (boolean, optional): Include archived issues (default: false)
  * `limit` (number, optional): Max results (default: 50)
  * `search` (string, optional): Search in title or description
* **Returns:** Array of issue objects
* **CLI equivalent:** `sudocode issue list [options]`

```typescript theme={null}
list_issues({
  status: "open",
  priority: 0,
  limit: 10
})
```

**3. show\_issue** - View issue details

Get complete issue information including relationships and feedback.

* **Parameters:**
  * `issue_id` (string, required): Issue ID (e.g., "ISSUE-001")
* **Returns:** Full issue object with relationships
* **CLI equivalent:** `sudocode issue show <issue-id>`

```typescript theme={null}
show_issue({ issue_id: "ISSUE-001" })
```

**4. upsert\_issue** - Create or update issue

Create new issues or update existing ones. If `issue_id` is provided, updates; otherwise creates new.

* **Parameters:**
  * `issue_id` (string, optional): Issue ID to update (omit to create new)
  * `title` (string, required for create): Issue title
  * `description` (string, optional): Issue description (supports `[[ID]]` references)
  * `status` (string, optional): "open", "in\_progress", "blocked", "closed"
  * `priority` (number, optional): Priority 0-4 (0=highest)
  * `parent` (string, optional): Parent issue ID
  * `tags` (string\[], optional): Array of tags
  * `archived` (boolean, optional): Archive status
* **Returns:** Created or updated issue object
* **CLI equivalent:** `sudocode issue create` / `sudocode issue update`

```typescript theme={null}
// Create new issue
upsert_issue({
  title: "Implement OAuth login",
  description: "Implements [[SPEC-001]]",
  status: "open",
  priority: 0,
  tags: ["auth", "backend"]
})

// Update existing issue
upsert_issue({
  issue_id: "ISSUE-001",
  status: "in_progress"
})

// Close issue
upsert_issue({
  issue_id: "ISSUE-001",
  status: "closed"
})
```

### Spec Management Tools

**5. list\_specs** - List specifications

Query all specs with optional search filter.

* **Parameters:**
  * `limit` (number, optional): Max results (default: 50)
  * `search` (string, optional): Search in title or description
* **Returns:** Array of spec objects
* **CLI equivalent:** `sudocode spec list [options]`

```typescript theme={null}
list_specs({
  search: "authentication",
  limit: 20
})
```

**6. show\_spec** - View spec details

Get complete spec information including all anchored feedback.

* **Parameters:**
  * `spec_id` (string, required): Spec ID (e.g., "SPEC-001")
* **Returns:** Full spec object with content and feedback
* **CLI equivalent:** `sudocode spec show <spec-id>`

```typescript theme={null}
show_spec({ spec_id: "SPEC-001" })
```

**7. upsert\_spec** - Create or update spec

Create new specifications or update existing ones.

* **Parameters:**
  * `spec_id` (string, optional): Spec ID to update (omit to create new)
  * `title` (string, required for create): Spec title
  * `description` (string, optional): Spec description/content
  * `priority` (number, optional): Priority 0-4 (0=highest)
  * `parent` (string, optional): Parent spec ID
  * `tags` (string\[], optional): Array of tags
* **Returns:** Created or updated spec object
* **CLI equivalent:** `sudocode spec create` / `sudocode spec update`

```typescript theme={null}
// Create new spec
upsert_spec({
  title: "Authentication System Design",
  description: "OAuth 2.0 implementation details...",
  priority: 0,
  tags: ["architecture", "auth"]
})

// Update existing spec
upsert_spec({
  spec_id: "SPEC-001",
  description: "Updated content..."
})
```

### Relationship Tools

**8. link** - Create relationships

Create typed relationships between entities (specs or issues).

* **Parameters:**
  * `from_id` (string, required): Source entity ID
  * `to_id` (string, required): Target entity ID
  * `type` (string, optional): Relationship type - "blocks", "implements", "references", "depends-on", "discovered-from", "related"
* **Returns:** Created relationship object
* **CLI equivalent:** `sudocode link <from> <to> <type>`

```typescript theme={null}
// Issue implements spec
link({
  from_id: "ISSUE-001",
  to_id: "SPEC-001",
  type: "implements"
})

// Issue blocks another issue
link({
  from_id: "ISSUE-002",
  to_id: "ISSUE-001",
  type: "blocks"
})
```

**Relationship types:**

* **blocks**: Hard blocker (to\_id must complete before from\_id can proceed)
* **implements**: Issue implements a spec
* **references**: Soft reference between entities
* **depends-on**: General dependency
* **discovered-from**: New work discovered during implementation
* **related**: General association

**9. add\_reference** - Add inline cross-reference

Insert Obsidian-style `[[ID]]` references into markdown content.

* **Parameters:**
  * `entity_id` (string, required): Entity to add reference to
  * `reference_id` (string, required): ID to reference (e.g., "ISSUE-001", "SPEC-002")
  * `display_text` (string, optional): Custom display text
  * `relationship_type` (string, optional): Also create typed relationship
  * `line` (number, optional): Line number to insert at (use line OR text, not both)
  * `text` (string, optional): Text to search for insertion point (use line OR text, not both)
  * `format` (string, optional): "inline" (default) or "newline"
* **Returns:** Success confirmation
* **CLI equivalent:** `sudocode add-ref <entity> <reference> [options]`

```typescript theme={null}
// Add reference at specific line
add_reference({
  entity_id: "SPEC-001",
  reference_id: "ISSUE-001",
  line: 42,
  format: "inline"
})

// Add reference with custom text
add_reference({
  entity_id: "SPEC-001",
  reference_id: "ISSUE-001",
  display_text: "See implementation",
  text: "## Implementation",
  relationship_type: "implements"
})
```

### Feedback Tools

**10. add\_feedback** - Provide anchored feedback

Add feedback to a spec, anchored at a specific line or text location.

* **Parameters:**
  * `issue_id` (string, required): Issue providing the feedback
  * `spec_id` (string, required): Spec receiving the feedback
  * `content` (string, required): Feedback content
  * `type` (string, optional): "comment", "suggestion", or "request"
  * `line` (number, optional): Line number to anchor at (use line OR text, not both)
  * `text` (string, optional): Text to anchor at (use line OR text, not both)
* **Returns:** Created feedback object
* **CLI equivalent:** `sudocode feedback add <issue> <spec> [options]`

```typescript theme={null}
// Request clarification
add_feedback({
  issue_id: "ISSUE-001",
  spec_id: "SPEC-001",
  content: "Token expiration policy not specified. Recommend 15min for access tokens.",
  type: "request",
  line: 42
})

// Add implementation comment
add_feedback({
  issue_id: "ISSUE-005",
  spec_id: "SPEC-001",
  content: "OAuth implemented with PKCE extension for enhanced security",
  type: "comment",
  text: "OAuth Flow"
})

// Suggest improvement
add_feedback({
  issue_id: "ISSUE-010",
  spec_id: "SPEC-002",
  content: "Consider adding rate limiting: 10 requests/minute per client",
  type: "suggestion",
  line: 78
})
```

**Feedback types:**

* **comment**: Informational feedback, no action required
* **suggestion**: Propose improvements or changes
* **request**: Request clarification or missing information

## Typical Agent Workflow

Here's how an AI agent typically uses these tools:

<Steps>
  <Step title="Find available work">
    ```typescript theme={null}
    // Check what's ready to work on
    const work = await ready()
    // Returns: { issues: [...], specs: [...] }
    ```
  </Step>

  <Step title="Claim a task">
    ```typescript theme={null}
    // Update issue status and assign
    await upsert_issue({
      issue_id: "ISSUE-001",
      status: "in_progress",
      assignee: "agent-01"
    })
    ```
  </Step>

  <Step title="Review spec">
    ```typescript theme={null}
    // Read the spec to understand requirements
    const spec = await show_spec({
      spec_id: "SPEC-001"
    })
    ```
  </Step>

  <Step title="Provide feedback">
    ```typescript theme={null}
    // If spec is unclear, request clarification
    await add_feedback({
      issue_id: "ISSUE-001",
      spec_id: "SPEC-001",
      content: "Token expiration policy not specified",
      type: "request",
      line: 42
    })
    ```
  </Step>

  <Step title="Create implementation plan">
    ```typescript theme={null}
    // Break down into subtasks
    const subtask1 = await upsert_issue({
      title: "Implement OAuth token generation",
      parent: "ISSUE-001"
    })

    const subtask2 = await upsert_issue({
      title: "Add token validation middleware",
      parent: "ISSUE-001"
    })
    ```
  </Step>

  <Step title="Link work to spec">
    ```typescript theme={null}
    // Create implementation relationships
    await link({
      from_id: "ISSUE-001",
      to_id: "SPEC-001",
      type: "implements"
    })
    ```
  </Step>
</Steps>

## Example Interactions

### Finding and Claiming Work

```
You: What work is ready for me to start?

Claude: Let me check what's available.
[Calls ready()]

There are 3 issues ready to work on:

1. ISSUE-005: Implement OAuth 2.0 authentication (Priority 0)
2. ISSUE-008: Add rate limiting to API (Priority 1)
3. ISSUE-012: Write integration tests (Priority 2)

Would you like me to claim one of these for you?

You: Yes, claim the OAuth issue for me.

Claude: I'll update ISSUE-005 to mark it as in progress.
[Calls upsert_issue({ issue_id: "ISSUE-005", status: "in_progress", assignee: "alice" })]

Done! ISSUE-005 is now assigned to you and marked as in progress.
Let me get the details so we can start working on it.
[Calls show_issue({ issue_id: "ISSUE-005" })]

This issue implements SPEC-001 (Authentication System Design).
Would you like me to show you the spec?
```

### Providing Feedback on Specs

```
You: I'm implementing ISSUE-005 and the spec doesn't mention token expiration

Claude: Let me check the spec first to see what's specified.
[Calls show_spec({ spec_id: "SPEC-001" })]

You're right - the spec doesn't specify token expiration policy.
I'll add feedback to the spec to request this clarification.
[Calls add_feedback({
  issue_id: "ISSUE-005",
  spec_id: "SPEC-001",
  content: "Token expiration policy not specified. Recommend adding: access tokens (15 min), refresh tokens (7 days)",
  type: "request",
  line: 42
})]

I've added a feedback request to the spec at line 42 (the Token Management section).
For now, I suggest we proceed with industry standard durations:
- Access tokens: 15 minutes
- Refresh tokens: 7 days

Would you like me to document this assumption in the issue?
```

## Configuration Options

### Environment Variables

<ParamField path="SUDOCODE_WORKING_DIR" type="string">
  **Working directory for sudocode operations**

  Default: Current working directory

  Example: `/Users/alice/projects/my-app`
</ParamField>

<ParamField path="SUDOCODE_PATH" type="string">
  **Path to sudocode CLI executable**

  Default: `sudocode` (from PATH)

  Example: `/usr/local/bin/sudocode`
</ParamField>

<ParamField path="SUDOCODE_DB" type="string">
  **Path to sudocode database file**

  Default: Auto-discover from working directory

  Example: `/Users/alice/projects/my-app/.sudocode/sudocode.db`
</ParamField>

### Command-Line Options

```bash theme={null}
sudocode-mcp [options]

Options:
  -w, --working-dir <path>  Working directory
  --cli-path <path>         Path to sudocode CLI
  --db-path <path>          Database path
  --no-sync                 Skip initial sync on startup
  -h, --help                Show help message
```

### Advanced Configuration

```json theme={null}
{
  "mcpServers": {
    "sudocode": {
      "command": "sudocode-mcp",
      "args": [
        "--working-dir", "/path/to/project",
        "--no-sync"
      ],
      "env": {
        "SUDOCODE_PATH": "/custom/path/to/sudocode"
      }
    }
  }
}
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Tools not showing up in Claude Code">
    **Cause:** MCP server not configured or not started

    **Solution:**

    1. Check Claude Code MCP settings
    2. Ensure `command` points to `sudocode-mcp`
    3. Verify `SUDOCODE_WORKING_DIR` is an absolute path
    4. Restart Claude Code
  </Accordion>

  <Accordion title="Error: sudocode command not found">
    **Cause:** sudocode CLI not in PATH or wrong path specified

    **Solution:**

    1. Install sudocode CLI: `npm install -g @sudocode/cli`
    2. Or specify path in config:
       ```json theme={null}
       "env": {
         "SUDOCODE_PATH": "/full/path/to/sudocode"
       }
       ```
  </Accordion>

  <Accordion title="Error: Database not found">
    **Cause:** Working directory not set or project not initialized

    **Solution:**

    1. Ensure project has `.sudocode/` directory
    2. Initialize if needed: `sudocode init`
    3. Set working directory in config:
       ```json theme={null}
       "env": {
         "SUDOCODE_WORKING_DIR": "/absolute/path"
       }
       ```
  </Accordion>

  <Accordion title="Tools return stale data">
    **Cause:** Database not synced after git pull

    **Solution:**

    1. Restart MCP server (restart Claude Code)
    2. Server runs `sudocode import` on startup
    3. Or manually sync: `sudocode sync`
  </Accordion>

  <Accordion title="Permission errors">
    **Cause:** MCP server can't access files

    **Solution:**

    1. Check directory permissions
    2. Ensure working directory is readable/writable
    3. Verify user running Claude Code has access
  </Accordion>
</AccordionGroup>

## Resources

### MCP Resources

The sudocode MCP server exposes resources that provide context to AI:

**sudocode://quickstart** - Quickstart guide embedded in MCP

* Core concepts (specs, issues, feedback)
* Typical workflow examples
* Relationship types explained

AI assistants can read this resource to understand sudocode without external documentation.

### Related Documentation

<CardGroup cols={3}>
  <Card title="Agent Workflows" icon="diagram-project" href="/mcp/workflows">
    Practical workflow examples for AI agents
  </Card>

  <Card title="CLI Documentation" icon="terminal" href="/cli/overview">
    Command-line interface reference
  </Card>

  <Card title="Concepts" icon="book" href="/concepts/specs">
    Core concepts and architecture
  </Card>
</CardGroup>

## Next Steps

<Steps>
  <Step title="Install the MCP server">
    Follow the [Agent Setup guide](/quickstart#step-4%3A-set-up-your-agent-optional) for setting up the sudocode MCP server with your specific agent
  </Step>

  <Step title="Configure your agent">
    Set up your AI agent with the [Agent Setup guide](/quickstart#step-4:-set-up-your-agent)
  </Step>

  <Step title="Review the tools">
    Study the [MCP tools reference](#mcp-tools-reference) above
  </Step>

  <Step title="Build workflows">
    Explore [agent workflow examples](/mcp/workflows) to see practical patterns
  </Step>
</Steps>

<Card title="Agent Workflow Examples" icon="diagram-project" href="/mcp/workflows">
  See 6 practical workflow examples showing how AI agents use MCP tools
</Card>