MCP Integration

Quick start

Three steps to get Codmir tools inside your AI assistant:

1. Authenticate — run codmir login in your terminal.
2. Add the MCP config to your editor (see below).
3. Use it — ask your AI to “list my to-do items” or “create a bug ticket for the login crash.”

Claude Code (recommended)

If you use Claude Code (CLI, VS Code extension, or desktop app), Codmir integrates as an MCP skill. Ask Claude to create tickets, list tasks, run AI jobs, and track your work—all from the same conversation.

One-command setup

# Install Codmir as a Claude Code MCP server
codmir install claude

# That's it. Claude can now use all Codmir tools.

Or set it up manually

Run this in your terminal to register the MCP server directly:

claude mcp add codmir -- npx @codmir/mcp

Or add it to .claude/settings.json in your project:

{
  "mcpServers": {
    "codmir": {
      "command": "npx",
      "args": ["@codmir/mcp"]
    }
  }
}

What you can do

Once installed, just talk to Claude naturally:

Let Claude set it up for you

Already in Claude Code? Copy this prompt and paste it directly into your conversation. Claude will handle the rest.

Set up Codmir in this project so I can manage tickets and tasks from here.

1. Check if the overseer CLI is installed (run: codmir --version). If not, install it globally: npm install -g @codmir/cli
2. Authenticate: run codmir login and follow the prompts
3. Register Codmir as an MCP server: run codmir install claude
4. Verify by running: codmir mcp tools

After setup, list my current to-do items to confirm everything works.

Other editors

Windsurf

codmir install windsurf

Or add manually to .windsurf/mcp.json:

{
  "mcpServers": {
    "codmir": {
      "command": "npx",
      "args": ["@codmir/mcp"]
    }
  }
}

Cursor

codmir install cursor

Or add manually to .cursor/mcp.json:

{
  "mcpServers": {
    "codmir": {
      "command": "npx",
      "args": ["@codmir/mcp"]
    }
  }
}

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "codmir": {
      "command": "npx",
      "args": ["@codmir/mcp"]
    }
  }
}

VS Code Extension

The Codmir VS Code extension includes a built-in To-Do List sidebar that connects to the same API. Install the extension from the marketplace, sign in, and the to-do tree view appears automatically under the Codmir sidebar.

Authentication

The MCP server loads credentials in this order:

1. ~/.codmir/credentials.json — written by codmir login
2. Environment variables: CODMIR_API_TOKEN, CODMIR_USER_ID, CODMIR_API_URL (optional)

# Recommended: interactive login
codmir login

# Or set env vars for CI / headless environments
export CODMIR_API_TOKEN="your-token"
export CODMIR_USER_ID="your-user-id"

Available MCP tools

CLI usage

The codmir mcp command gives you direct access to MCP tools from the terminal.

List to-do items

# List all actionable items
codmir mcp todo

# Filter by priority
codmir mcp todo --priority high

# Filter by status
codmir mcp todo --status in_progress

# JSON output for scripting
codmir mcp todo --json

Update ticket status

# Mark a ticket as done
codmir mcp done TKT-42

# Start working on a ticket
codmir mcp start TKT-42

Call any MCP tool

# List available tools
codmir mcp tools

# Call a tool with JSON args
codmir mcp call create_ticket '{"projectId":"proj_123","title":"Fix login crash","type":"BUG","priority":"HIGH"}'

# Execute an AI task
codmir mcp call execute_task '{"projectId":"proj_123","instructions":"Add input validation to signup form"}'

Start the MCP server

# Run the stdio server locally (used by editor configs)
codmir mcp serve

# Or directly via npx
npx @codmir/mcp

SDK usage (programmatic)

Use @codmir/sdk/mcp to call MCP tools from your own TypeScript/JavaScript code.

npm install @codmir/sdk

import { MCPClient } from '@codmir/sdk/mcp';

const mcp = new MCPClient({
  apiUrl: 'https://codmir.com',
  token: process.env.CODMIR_API_TOKEN!,
  userId: process.env.CODMIR_USER_ID!,
});

// List to-do items
const todos = await mcp.listTodo({
  projectId: 'proj_123',
  priority: 'high',
});
console.log(todos.data);

// Mark a ticket as done
await mcp.updateTodoStatus({
  projectId: 'proj_123',
  ticketId: 'TKT-42',
  status: 'done',
});

// Execute an AI task
const result = await mcp.executeTask({
  projectId: 'proj_123',
  instructions: 'Add rate limiting to the /api/auth endpoint',
});

// Call any tool generically
const context = await mcp.callTool('get_project_context', {
  projectId: 'proj_123',
});

VS Code extension

The Codmir extension adds a To-Do List tree view to the sidebar. It shows all actionable tickets from your linked project, grouped by status or priority.

Features

• Tickets grouped by status (default), priority, or flat list
• Inline actions: mark done, mark in-progress, open in browser
• Auto-refreshes on workspace open
• Excludes tickets with auto-execution workflow enabled
• Priority & type icons with rich markdown tooltips

Commands

Troubleshooting

“Not authenticated”

Run codmir login and try again. Credentials are stored in ~/.codmir/credentials.json.

MCP server not connecting

Restart your editor after updating the MCP config. Check the output/debug console for errors. You can test the server manually:

# Test the server starts
npx @codmir/mcp

# Or via CLI
codmir mcp serve

Debug mode

# Set DEBUG env var to see request/response logs
DEBUG=codmir:mcp npx @codmir/mcp