MCP Integration
The Model Context Protocol (MCP) lets AI assistants interact with Codmir directly—creating tickets, listing to-do items, running tasks, and querying production errors without leaving your editor.
Quick start
Three steps to get Codmir tools inside your AI assistant:
- Authenticate — run
overseer loginin your terminal. - Add the MCP config to your editor (see below).
- 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.
Auto-setup prompt
Claude will install the CLI, authenticate, and register the MCP server.
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:
~/.codmir/credentials.json— written byoverseer login- 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
| Tool | Description |
|---|---|
| list_todo | List actionable to-do tickets (open, in-progress, review) |
| update_todo_status | Mark a ticket as done, in-progress, or reopen it |
| execute_task | Execute an AI-powered code task |
| get_sprint_tasks | Get sprint tasks with status filter |
| create_ticket | Create a bug, feature, task, or improvement ticket |
| list_project_tasks | List all project tasks |
| check_task_status | Check a running task’s status |
| get_project_context | Project overview, tech stack, team info |
| store_conversation | Save conversation as project docs |
| lookup_error | Look up a production error by any reference |
| list_recent_errors | List recent production errors |
| get_error_context | Enriched error context for debugging |
| get_sdk_reference | SDK API reference for a topic |
| generate_sdk_code | Generate ready-to-use SDK code |
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
| Command | Action |
|---|---|
| Codmir: Refresh To-Do List | Re-fetch tickets from the API |
| Codmir: Mark as Done | Update ticket status to done |
| Codmir: Mark In Progress | Update ticket status to in-progress |
| Codmir: Open in Browser | Open the ticket in the Codmir web app |
| Codmir: Group by Status / Priority | Change how tickets are grouped in the tree |
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
See also: SDK docs · CLI reference · Connecting a project