Overview

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.

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.

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?

Autonomous Development

AI agents can self-direct

Find and claim work independently
Create implementation plans
Provide feedback on specs
Manage task dependencies

Better Context

AI understands your project

Query issues and specs
Understand relationships
See what’s blocked
Track project status

Workflow Integration

Seamless development flow

Check ready work: ready()
Claim issues: upsert_issue()
Read specs: show_spec()
Link work: link()

Feedback Loop

Bidirectional learning

AI provides feedback on specs
Anchored comments at specific lines
Request clarifications
Suggest improvements

Workflow Guides

Learn how to use sudocode MCP with these practical guides:

Creating Specifications

Capture requirements and design decisions that guide implementation

Creating Issues

Break down specs into actionable work items with dependencies

Executing Issues

How agents discover, claim, and complete work

Multi-Agent Coordination

Coordinate multiple AI agents working in parallel

Workflow Examples

6 practical workflow examples with tool invocations

Best Practices

Guidelines for effective agent work with sudocode

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

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]

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>

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

// 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]

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>

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

// 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>

// 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]

// 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]

// 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:

Find available work

// Check what's ready to work on
const work = await ready()
// Returns: { issues: [...], specs: [...] }

Claim a task

// Update issue status and assign
await upsert_issue({
  issue_id: "ISSUE-001",
  status: "in_progress",
  assignee: "agent-01"
})

Review spec

// Read the spec to understand requirements
const spec = await show_spec({
  spec_id: "SPEC-001"
})

Provide feedback

// 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
})

Create implementation plan

// 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"
})

Link work to spec

// Create implementation relationships
await link({
  from_id: "ISSUE-001",
  to_id: "SPEC-001",
  type: "implements"
})

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

SUDOCODE_WORKING_DIR

string

Working directory for sudocode operationsDefault: Current working directoryExample: /Users/alice/projects/my-app

SUDOCODE_PATH

string

Path to sudocode CLI executableDefault: sudocode (from PATH)Example: /usr/local/bin/sudocode

SUDOCODE_DB

string

Path to sudocode database fileDefault: Auto-discover from working directoryExample: /Users/alice/projects/my-app/.sudocode/sudocode.db

Command-Line Options

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

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

Troubleshooting

Tools not showing up in Claude Code

Cause: MCP server not configured or not startedSolution:

Check Claude Code MCP settings
Ensure command points to sudocode-mcp
Verify SUDOCODE_WORKING_DIR is an absolute path
Restart Claude Code

Error: sudocode command not found

Cause: sudocode CLI not in PATH or wrong path specifiedSolution:

Install sudocode CLI: npm install -g @sudocode/cli

Or specify path in config:

"env": {
  "SUDOCODE_PATH": "/full/path/to/sudocode"
}

Error: Database not found

Cause: Working directory not set or project not initializedSolution:

Ensure project has .sudocode/ directory
Initialize if needed: sudocode init

Set working directory in config:

"env": {
  "SUDOCODE_WORKING_DIR": "/absolute/path"
}

Tools return stale data

Cause: Database not synced after git pullSolution:

Restart MCP server (restart Claude Code)
Server runs sudocode import on startup
Or manually sync: sudocode sync

Permission errors

Cause: MCP server can’t access filesSolution:

Check directory permissions
Ensure working directory is readable/writable
Verify user running Claude Code has access

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.

Agent Workflows

Practical workflow examples for AI agents

CLI Documentation

Command-line interface reference

Concepts

Core concepts and architecture

Next Steps

Install the MCP server

Follow the Agent Setup guide for setting up the sudocode MCP server with your specific agent

Configure your agent

Set up your AI agent with the Agent Setup guide

Review the tools

Study the MCP tools reference above

Build workflows

Explore agent workflow examples to see practical patterns

Agent Workflow Examples

See 6 practical workflow examples showing how AI agents use MCP tools

MCP Server

MCP Workflow Examples

What is MCP?

Why Use MCP with sudocode?

Autonomous Development

Better Context

Workflow Integration

Feedback Loop

Workflow Guides

Creating Specifications

Creating Issues

Executing Issues

Multi-Agent Coordination

Workflow Examples

Best Practices

MCP Tools Reference

Issue Management Tools

Spec Management Tools

Relationship Tools

Feedback Tools

Typical Agent Workflow

Example Interactions

Finding and Claiming Work

Providing Feedback on Specs

Configuration Options

Environment Variables

Command-Line Options

Advanced Configuration

Troubleshooting

Resources

MCP Resources

Agent Workflows

CLI Documentation

Concepts

Next Steps

Agent Workflow Examples

MCP Server

MCP Workflow Examples

​What is MCP?

​Why Use MCP with sudocode?

Autonomous Development

Better Context

Workflow Integration

Feedback Loop

​Workflow Guides

Creating Specifications

Creating Issues

Executing Issues

Multi-Agent Coordination

Workflow Examples

Best Practices

​MCP Tools Reference

​Issue Management Tools

​Spec Management Tools

​Relationship Tools

​Feedback Tools

​Typical Agent Workflow

​Example Interactions

​Finding and Claiming Work

​Providing Feedback on Specs

​Configuration Options

​Environment Variables

​Command-Line Options

​Advanced Configuration

​Troubleshooting

​Resources

​MCP Resources

​Related Documentation

Agent Workflows

CLI Documentation

Concepts

​Next Steps

Agent Workflow Examples

What is MCP?

Why Use MCP with sudocode?

Workflow Guides

MCP Tools Reference

Issue Management Tools

Spec Management Tools

Relationship Tools

Feedback Tools

Typical Agent Workflow

Example Interactions

Finding and Claiming Work

Providing Feedback on Specs

Configuration Options

Environment Variables

Command-Line Options

Advanced Configuration

Troubleshooting

Resources

MCP Resources

Related Documentation

Next Steps