Setup Guide

This guide walks you through setting up sudocode’s MCP (Model Context Protocol) integration for various AI agents. The MCP server allows any Agent to directly interact with your sudocode project—creating issues, managing specs, and providing feedback.

Prerequisites

Before setting up any Agent, ensure you have the following:

Install sudocode CLI

Install the sudocode CLI globally:

npm install -g sudocode

Verify installation:

sudocode --version

Expected output

sudocode/1.0.0

Verify sudocode-mcp command

Test that the MCP server runs correctly:

sudocode-mcp

Expected output

✓ sudocode initialized successfully
sudocode MCP server running on stdio

The MCP server is included with the sudocode CLI installation. If you see the success message, you’re ready to configure your agent!

Press Ctrl+C to stop the server. The MCP server will startup automatically with your agent once configured.

Initialize your project

Make sure you have a sudocode project initialized:

cd your-project
sudocode init

If all prerequisites are met, choose your AI agent below to continue setup!

Choose Your Agent

Select your AI assistant to see specific setup instructions:

Claude Code

Official Anthropic CLI with plugin marketplace

Codex

OpenAI’s AI coding assistant

Cursor

AI-powered code editor

VS Code

Visual Studio Code with MCP extensions

Other MCP Agents

Generic MCP configuration for any compatible agent

Claude Code

Claude Code has the simplest setup thanks to the plugin marketplace:

Add sudocode plugin from marketplace

claude plugin marketplace add sudocode-ai/sudocode

Expected output

✓ Added sudocode-ai/sudocode to plugin marketplace

Install the plugin

claude plugin install sudocode

Expected output

✓ Installed sudocode plugin
✓ MCP server configured

Verify installation

Start Claude Code and test the integration:

claude

Then ask Claude:

Can you create a "Hello World" issue?

If you see Claude using tools like plugin:sudocode:sudocode - upsert_issue, the setup is working!

Claude Code is now configured with sudocode! The plugin automatically handles MCP server configuration and working directory detection.

Codex

Codex is not currently supported, but we will support it soon!

If you’d like to see Codex support prioritized, please open a discussion to let us know. We’re actively working on expanding agent compatibility.

Cursor

Cursor uses an MCP configuration file in the .cursor directory of your project root.

Setup the MCP Server

Option 1: Automated Setup

Run this command in your project root to automatically configure Cursor:

mkdir -p .cursor && \
if [ -f .cursor/mcp.json ]; then \
  jq '.mcpServers.sudocode = {"command": "sudocode-mcp"}' .cursor/mcp.json > .cursor/mcp.json.tmp && \
  mv .cursor/mcp.json.tmp .cursor/mcp.json; \
else \
  echo '{"mcpServers":{"sudocode":{"command":"sudocode-mcp"}}}' | jq '.' > .cursor/mcp.json; \
fi && \
echo "✓ Configuration created! Now enable the MCP server in Cursor (see next step)."

What this command does

Creates .cursor/ directory if it doesn’t exist
If mcp.json exists, uses jq to add the sudocode server
If mcp.json doesn’t exist, creates it with the sudocode configuration
Preserves any existing MCP servers in the file

Note: This command requires jq (JSON processor). Install it with:

macOS: brew install jq
Ubuntu/Debian: sudo apt-get install jq
Other: See jq installation

Option 2: Manual Setup

Create .cursor directory

In your project root directory, create a .cursor directory if it doesn’t exist:

mkdir -p .cursor

Create or edit .cursor/mcp.json

Open or create .cursor/mcp.json and add the following configuration:

{
  "mcpServers": {
    "sudocode": {
      "command": "sudocode-mcp"
    }
  }
}

If you already have other MCP servers configured, just add the "sudocode" entry inside the existing "mcpServers" object.

Save the file

Save the .cursor/mcp.json file.

Enable the MCP Server

After creating the configuration (using either option above), you need to enable the MCP server in Cursor: Option A: Click Enable (when prompted) When Cursor detects the new MCP configuration, an Enable button will appear on the left side. Click it to activate the sudocode MCP server.

Cursor showing Enable button for sudocode MCP server

Option B: Enable via Settings Alternatively, you can manually enable the MCP server:

Go to Cursor > Settings > Cursor Settings
Enable the MCP server

Cursor Settings page showing MCP enable option

No restart required! Once you enable the MCP server, it will be active immediately.

Verify Setup

Test that sudocode is working in Cursor by asking it to create an issue:

Can you create a "Hello World" issue using sudocode?

If the setup is working, you’ll see Cursor use the sudocode MCP tools:

Cursor successfully creating an issue using sudocode MCP

Cursor is now configured with sudocode! The MCP server will automatically run when you use sudocode tools in Cursor.

VS Code

VS Code supports MCP through workspace configuration. You can set it up using the Command Palette or by creating a configuration file:

Setup the MCP Server

Method 1: Command Palette (Recommended)

Open Command Palette

Press Cmd+Shift+P (macOS) or Ctrl+Shift+P (Windows/Linux) to open the Command Palette.Type and select:

MCP: Add Server

VS Code Command Palette showing MCP: Add Server command

Select Command (stdio)

When prompted for the server type, select Command (stdio).

MCP server type selection dialog showing Command (stdio) option

Enter command

Type the command:

sudocode-mcp

Enter Command dialog with sudocode-mcp typed in

Name the server

Give it a name (we recommend sudocode-mcp).

Enter Server ID dialog with sudocode-mcp as the name

Choose Workspace

When prompted to choose between Global or Workspace, select Workspace.

Make sure to select Workspace (not Global) so the MCP server runs in your project directory.

Installation location dialog showing Global vs Workspace options with Workspace selected

Verify configuration

Check that .vscode/mcp.json was created in your project root:

cat .vscode/mcp.json

You should see something like this:

{
  "servers": {
    "sudocode-mcp": {
      "type": "stdio",
      "command": "sudocode-mcp",
      "args": []
    }
  },
  "inputs": []
}

VS Code showing the created .vscode/mcp.json file with sudocode-mcp configuration

Method 2: Manual Configuration

If you prefer to configure manually or want to automate setup:

Create or update configuration

Run this command in your project root to create/update the MCP configuration:

mkdir -p .vscode && \
if [ -f .vscode/mcp.json ]; then \
  jq '.servers["sudocode-mcp"] = {"type": "stdio", "command": "sudocode-mcp", "args": []}' .vscode/mcp.json > .vscode/mcp.json.tmp && \
  mv .vscode/mcp.json.tmp .vscode/mcp.json; \
else \
  echo '{"servers":{"sudocode-mcp":{"type":"stdio","command":"sudocode-mcp","args":[]}},"inputs":[]}' | jq '.' > .vscode/mcp.json; \
fi

What this command does

Creates .vscode/ directory if it doesn’t exist
If mcp.json exists, uses jq to add the sudocode-mcp server
If mcp.json doesn’t exist, creates it with the sudocode-mcp configuration
Preserves any existing MCP servers in the file

Note: This command requires jq (JSON processor). Install it with:

macOS: brew install jq
Ubuntu/Debian: sudo apt-get install jq
Other: See jq installation

Alternative: Create file manually

Or simply create .vscode/mcp.json with this content:

{
  "servers": {
    "sudocode-mcp": {
      "type": "stdio",
      "command": "sudocode-mcp",
      "args": []
    }
  },
  "inputs": []
}

Reload VS Code

Reload VS Code to apply the configuration:

Press Cmd+Shift+P (macOS) or Ctrl+Shift+P (Windows/Linux)
Select “Developer: Reload Window”

Verify Setup

Test that MCP tools are available in VS Code:

Test sudocode integration

Open Github Copilot, and just ask:

Can you create a "Hello World" issue using sudocode?

You should see a tool call like the one below. You should be all set!

Example of sudocode creating a hello world issue

Other MCP-Compatible Agents

For any MCP-compatible AI agent, you can configure the sudocode MCP server manually:

Locate your agent's MCP configuration

Find where your agent stores MCP server configuration. This is typically in:

A config file (JSON, YAML, or TOML)
Application settings UI
Command-line arguments

Consult your agent’s documentation for “MCP server configuration” or “tool integration”.

Add sudocode MCP server

Add the following configuration to your agent’s MCP servers:JSON format:

    {
        "mcpServers": {
            "sudocode": {
            "command": "sudocode-mcp"
            }
        }
    }

YAML format:

mcpServers:
  sudocode:
    command: sudocode-mcp

Remember that this MCP configuration needs to be placed at the root of your project directory.

Restart your agent

Restart your AI agent to load the MCP server configuration.

Verify the integration

Test by asking your agent to interact with sudocode:

Can you create a "Hello World" issue?

If you see Claude using tools like plugin:sudocode:sudocode - upsert_issue, the setup is working!

Troubleshooting

Command not found: sudocode-mcp

Cause: sudocode CLI not installed or not in PATHSolution:

Install sudocode globally:
```
npm install -g sudocode
```
Verify installation:
```
sudocode-mcp --help
```
If still not found, check your PATH includes npm global bin:
```
npm config get prefix
```

MCP tools not showing up in agent

Cause: MCP server not configured correctly or agent not restartedSolution:

Verify MCP configuration in your agent’s settings
Ensure command is set to sudocode-mcp
Restart your agent completely
Check agent logs for MCP server errors

Error: Database not found

Cause: Project not initializedSolution:

Verify your project has .sudocode/ directory:
```
ls -la .sudocode/
```
Initialize if needed:
```
sudocode init
```

Tools return stale or empty data

Cause: Database not synced after git operationsSolution:

Manually sync:
```
sudocode sync
```
Check that .sudocode/cache.db exists and is not corrupted

Permission denied errors

Cause: MCP server can’t access project filesSolution:

Check directory permissions:
```
ls -la .sudocode/
```
Ensure .sudocode/ directory is readable and writable
Verify the user running your agent has file access
On macOS, check System Settings � Privacy & Security

Plugin install fails (Claude Code)

Cause: Plugin not found in marketplace or network issueSolution:

Verify you added the marketplace source:

claude plugin marketplace add sudocode-ai/sudocode

Check network connectivity
Check Claude Code logs for detailed errors

What’s Next?

After setting up your agent, explore these resources:

MCP Tools Reference

Learn about all 10 MCP tools available to your agent

Agent Workflows

See practical workflow examples for AI agents

Quick Start Guide

Create your first spec and issue

Core Concepts

Understand specs, issues, and relationships

Need help with a specific agent? Open a discussion and let us know which agent you’re using. We’ll prioritize documentation based on community needs!

Getting Started

Core Concepts

Examples & Tutorials

Prerequisites

Choose Your Agent

Claude Code

Codex

Cursor

VS Code

Other MCP Agents

Claude Code

Codex

Cursor

Setup the MCP Server

Enable the MCP Server

Verify Setup

VS Code

Setup the MCP Server

Verify Setup

Other MCP-Compatible Agents

Troubleshooting

What’s Next?

MCP Tools Reference

Agent Workflows

Quick Start Guide

Core Concepts

Getting Started

Core Concepts

Examples & Tutorials

​Prerequisites

​Choose Your Agent

Claude Code

Codex

Cursor

VS Code

Other MCP Agents

​Claude Code

​Codex

​Cursor

​Setup the MCP Server

​Enable the MCP Server

​Verify Setup

​VS Code

​Setup the MCP Server

​Verify Setup

​Other MCP-Compatible Agents

​Troubleshooting

​What’s Next?

MCP Tools Reference

Agent Workflows

Quick Start Guide

Core Concepts

Prerequisites

Choose Your Agent

Claude Code

Codex

Cursor

Setup the MCP Server

Enable the MCP Server

Verify Setup

VS Code

Setup the MCP Server

Verify Setup

Other MCP-Compatible Agents

Troubleshooting

What’s Next?