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 six tools:

Letting the Agent File Feedback

create_comment works in the other direction to the rest: instead of reading your feedback, the agent adds its own. Point it at a page and it can log what it finds — "review the pricing page and file anything that looks broken" — and the comments land in your dashboard alongside visitor feedback.

The agent passes a page path (like /pricing) and the comment text. It can also pin the comment to a specific element by passing a CSS selector, or the exact visible text of the element. When it does, the widget shows a normal pin on the live page. Without one, the comment is attached to the page rather than an element: it appears in the dashboard and in the widget's feedback list, marked as a page comment, and you can pin it to an element later from the widget.

The setup wizard asks whether the agent may create comments. Answer no and the tool is marked as disabled, so agents leave it alone unless you ask directly.

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. Ask whether the agent may write replies and create comments
5. Auto-create a .mcp.json in your project root

Email code didn't arrive?

Generate a token in the dashboard (Account → AI Agent → Generate New Token) and pass it directly to skip the email step:

npx @simple-commenter/mcp-server init --token YOUR_TOKEN

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