MCP Integration

Quick start

Three steps to get Codmir tools inside your AI assistant:

1. Authenticate — run overseer 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
overseer 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: overseer --version). If not, install it globally: npm install -g @codmir/cli
2. Authenticate: run overseer login and follow the prompts
3. Register Codmir as an MCP server: run overseer install claude
4. Verify by running: overseer mcp tools

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

Other editors

Windsurf

overseer install windsurf

Or add manually to .windsurf/mcp.json:

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

Cursor

overseer 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 overseer login
2. Environment variables: CODMIR_API_TOKEN, CODMIR_USER_ID, CODMIR_API_URL (optional)

# Recommended: interactive login
overseer 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 overseer mcp command gives you direct access to MCP tools from the terminal.

List to-do items

# List all actionable items
overseer mcp todo

# Filter by priority
overseer mcp todo --priority high

# Filter by status
overseer mcp todo --status in_progress

# JSON output for scripting
overseer mcp todo --json

Update ticket status

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

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

Call any MCP tool

# List available tools
overseer mcp tools

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

# Execute an AI task
overseer 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)
overseer 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 overseer 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
overseer mcp serve

Debug mode

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