AI Agent Integration

Connect AI coding agents like Claude Code, Cursor, and others to your Simple Commenter projects. The agents fetch feedback, understand what needs fixing, fix the code, and update comment status — all automatically.

How It Works

Simple Commenter provides an MCP (Model Context Protocol) server that AI coding agents use to communicate with your projects. The MCP server exposes five tools:

Setup

Step 1: Install the MCP Server

npm install -g @simple-commenter/mcp-server

Or use npx without installing globally — the setup wizard handles everything:

npx @simple-commenter/mcp-server init

Step 2: Run the Setup Wizard

simple-commenter-mcp init

The wizard will:

1. Authenticate with your email and a 6-digit code
2. Let you pick a default project
3. Configure status preferences for AI workflows
4. Auto-create a .mcp.json in your project root

Step 3: Restart Your AI Tool

Restart Claude Code, Cursor, or whichever AI tool you use. The MCP server will be available automatically.

Verify Your Setup

simple-commenter-mcp doctor

This checks Node.js version, config, API connectivity, and .mcp.json — reports pass/fail for each.

Typical Workflow

Ask your AI agent:

"Check Simple Commenter for open feedback and fix the issues"

The agent will:

1. Call list_projects to find your project
2. Call list_comments with status=todo to get open issues
3. Call get_comment on each to see the element, screenshot, and page URL
4. Mark comments as in_progress while working
5. Fix the code
6. Reply with what was fixed
7. Mark as done

Configuration

.mcp.json (auto-created by init)

{
  "mcpServers": {
    "simple-commenter": {
      "command": "simple-commenter-mcp",
      "args": ["serve"]
    }
  }
}

Environment Variable (CI / Docker)

For automated environments, pass the token as an environment variable instead of using the config file:

{
  "mcpServers": {
    "simple-commenter": {
      "command": "npx",
      "args": ["@simple-commenter/mcp-server", "serve"],
      "env": {
        "SIMPLE_COMMENTER_API_TOKEN": "your-token"
      }
    }
  }
}

You can generate a token from the AI Agent dashboard or via CLI login.

Authentication Priority

The server checks for credentials in this order:

1. --token <token> CLI flag
2. SIMPLE_COMMENTER_API_TOKEN environment variable
3. ~/.simple-commenter/config.json (from init command)

Managing Tokens

Go to Account > AI Agent in the dashboard to:

• View all connected AI agent tokens
• Generate new tokens for CI or additional agents
• Revoke tokens that are no longer needed

CLI Commands

login and logout still work as aliases for init and reset.

Supported AI Tools

The MCP server works with any tool that supports the Model Context Protocol:

• Claude Code — Anthropic's CLI coding agent
• Cursor — AI-powered code editor
• Any MCP-compatible agent — The protocol is open and growing

Security

• Credentials are stored in ~/.simple-commenter/config.json with chmod 600 (owner-only)
• The server warns if file permissions are too open
• For shared machines, use environment variables instead of the config file
• Add .simple-commenter/ to your .gitignore

Troubleshooting

Common Issues

Still Having Issues?

Run simple-commenter-mcp doctor for a full diagnostic check, or contact support.

Next Steps

• Set up Slack notifications
• Connect Trello for task management
• Configure webhooks for custom integrations