MCP & AI Connections

MCP (Model Context Protocol) connects your feedback to an external AI tool. Use a hosted HTTPS connection for browser clients, or the local npm server for coding tools. The built-in AI Assistant is a separate dashboard chat.

Find MCP settings and your token

Open any project and click MCP directly in the project sidebar. It is a separate item beside Comments, Board, and Assets. From the workspace, use Workspace settings → MCP & AI connections. You can also open MCP settings directly.

Only workspace owners can authorize external connections or generate account API tokens. Team members should ask the owner to connect the workspace. Project access is selected during browser authorization; opening setup from a project does not grant access automatically.

For a token or API key, find Local API tokens, give the token a name, and click Generate token. Copy it immediately: the full value is shown once. Local tokens have account-wide read, write, and settings access. Use hosted OAuth authorization for read-only or selected-project access.

Availability and Pricing

MCP is included on supported paid plans, including Solo, Team, Pro, Agency, Enterprise, and Unlimited lifetime plans, and during the 14-day trial. It is not available on the free plan after the trial. Use get_connection_info to check the connected account's current plan and access.

There is no separate MCP subscription or per-request fee. Hosted MCP allows 120 authenticated requests per minute per connection. The local server's MCP API allows 120 requests per minute per integration token. These are MCP limits, not a plan-specific allowance; your AI provider's usage limits apply separately. See Troubleshooting for rate-limit recovery.

Hosted connection: ChatGPT and Claude

The hosted MCP route uses your existing Simple Commenter domain:

https://www.simplecommenter.com/api/mcp

Hosted MCP is enabled by default after deployment. Deployment operators can optionally disable it with MCP_ENABLED=false. Check the server status in MCP settings before connecting. Hosted connection unavailable means that hosted access is disabled or unavailable on that deployment; use the local setup below while it is unavailable. The URL by itself does not establish a working connection.

The hosted URL uses Streamable HTTP. It is the address to paste into a remote MCP client. The npm package runs locally over stdio and does not provide a URL to paste into ChatGPT. Browser setup uses OAuth sign-in; it does not require you to generate or paste a local API token.

ChatGPT

1. Open MCP in the project sidebar and select ChatGPT.
2. In ChatGPT, enable Developer mode under Settings → Security and login.
3. Open Plugins, choose +, and create a developer-mode app using the hosted server URL. Choose OAuth authentication and dynamic client registration when offered.
4. Sign in to Simple Commenter. Select the permitted projects and allowed actions, then authorize the connection.
5. In a chat, select the app from Developer mode in the plus menu. Ask: “List my projects and show unresolved feedback.”

Custom app access depends on the ChatGPT account and workspace policy. This server supports dynamic client registration (DCR), rather than Client ID Metadata Documents (CIMD). See OpenAI's developer-mode guide for current client requirements.

Claude

1. Open Customize → Connectors in Claude.
2. Choose + → Add custom connector, paste the hosted URL, and add the connector.
3. Connect and sign in to Simple Commenter, then select projects and approve the allowed actions.
4. Enable the connector for the conversation from + → Connectors, then ask Claude to list your feedback.

Organization owners may need to add the connector first. See Claude's custom connector guide.

Choose access and disconnect

Browser authorization starts with read access and selected projects. Enable write access only when the client should create comments, reply, or triage feedback. Settings access permits administrative operations. Workspace-wide access, including future projects, is a separate explicit choice; creating projects and managing the workspace team require it as well as settings access.

Read access is always included. Write and settings access are optional and independent; enabling one does not enable the other. A client's tool approval dialog cannot expand the access granted in Simple Commenter.

In MCP → Connected apps, review allowed actions, permitted projects, and last use. Click Disconnect to revoke a connection. To add projects or change permissions, reconnect from the AI client and complete authorization again. Revocation also invalidates that connection's saved downloads and job results.

What your AI can do

Read feedback with project context, screenshot references, replies, tags, current statuses, and direct dashboard links. Search, export, and reporting apply the connection's project permissions. Changes require the appropriate granted access.

The connection gives your AI access to feedback. Editing website code also requires access to the relevant code repository and development tools.

Try a workflow

• “List my projects and show the current statuses for my website.”
• “Find urgent feedback created this week, including feedback on assets.”
• “Export all feedback from this project to CSV, including archived comments.”
• “Create a report of feedback by project, status, and priority.”
• “Show me the proposed changes before moving these three comments to review.”

Tool reference

The hosted and local servers share these 27 tools. Your client discovers their JSON input schemas automatically. The tables below use their exact parameter names. Supply project_id from list_projects for a single-project tool; a local configured default can supply it when omitted. Hosted setup does not set a default project. Tool availability follows the connected server version; refresh discovery after upgrading and check hosted availability in settings.

Filters and complete results

Feedback filters are project_id or project_ids (up to 50), query (search is an alias), comma-separated status, priority, and tags, exact page slug, author, created_after, created_before, include_archived, source, and asset_id. list_comments uses one project_id rather than project_ids. Dates use ISO timestamps with a timezone; both endpoints are inclusive. Tags match any supplied tag. Text search matches titles and comment text, not the reply thread.

source accepts all, website, or asset and defaults to all. include_archived defaults to false. Deleted feedback is always excluded. Without project filters, search, exports, and reports cover every project in the connection's grant, including when the local setup has a default project.

list_comments, search_comments, and list_tasks return total and next_offset. Use that offset until it is null; each page defaults to 50 records and accepts a limit of 1–100 and offset of 0–1,000,000. Search text is limited to 1,000 characters. An export or report processes the entire matching set without limit or offset. Both have a maximum of 50,000 comments and an 8 MiB generated file limit; narrow the project or date range if exceeded.

Dashboard links require sign-in and the viewer's own access. Website feedback links open the Board item when it is available in the active view; asset links open the asset viewer. Archived feedback may not open in the active Board; retrieve its detail with get_comment or restore it when appropriate.

For example, call search_comments with these arguments, then use the returned next_offset to continue:

{
  "project_ids": ["PROJECT_ID"],
  "created_after": "2026-09-01T00:00:00Z",
  "created_before": "2026-09-06T23:59:59Z",
  "priority": "high,urgent",
  "source": "all",
  "include_archived": false,
  "limit": 100,
  "offset": 0
}

Export CSV from the dashboard

Open a project → Comments or Board → Export CSV, beside Add comment. Choose All website feedback for all accessible statuses or Current filters for the complete filtered set, including records below the fold. On Board, filtered export waits for all statuses to finish loading. Both dashboard choices exclude archived and asset feedback. General → Export Feedback also exports all website feedback.

Use MCP export_comments with source: "all" and include_archived: true when you need assets and archived feedback, or cross-project exports. MCP CSV rows include project, comment, status, priority, tags, author, creation date, source, page or asset, archive state, dashboard URL, screenshot URL, and comment and reply attachment URLs. Dashboard CSV also includes the reply thread; the MCP CSV does not include reply text.

Updating feedback safely

Read get_project_context before choosing a status; custom and enabled statuses vary by project. Priorities are low, normal, high, and urgent. For updates, tags is a replacement array (up to 30 tags); [] clears tags. visibility is all or team, and changing it can change client visibility. archived: true archives feedback; false restores it. Restore archived feedback before replying or making other changes. There is no permanent-delete tool. New comments and replies accept up to 30,000 text characters; a new comment's optional title accepts up to 500. Tags contain 1–40 letters, numbers, underscores, or hyphens.

Use an idempotency_key for create/reply retries. It is required for bulk updates, project/member creation, and background jobs: 8–128 letters, digits, underscores, periods, colons, or hyphens. Reuse exactly the same key and arguments when retrying the same action; receipts last seven days. If the earlier outcome is uncertain, inspect the affected item before sending a new key. Bulk results can contain successful and failed items, so review each outcome.

Project and team administration

get_project_settings and update_project_settings support projectName, domain, active, enabledStatuses, emailNotifications, emailFrequency, notifyOnOwnComments, drawing, screenshots, uploads, commentTitle, metaData, minimized, clientAccess, and tokenAccess. Read the current settings before changing access controls. clientAccess is open, request, or invite; tokenAccess is a boolean. Status names must already exist in the project. emailFrequency accepts minute, 15minutes, hourly, daily, weekly, or monthly. Other settings and credentials are not exposed by these tools.

Adding a team member through MCP does not send an invitation email. Ask the workspace owner to arrange access through the dashboard when an invitation is needed.

Reports, tasks, and reusable workflows

Use start_task for an export or report that takes longer to produce. For example, these arguments start a CSV of website and asset feedback:

{
  "operation": "export_comments",
  "arguments": {
    "project_id": "PROJECT_ID",
    "source": "all",
    "include_archived": true
  },
  "idempotency_key": "feedback-export-2026-09-06"
}

Save the returned task_id. Call get_task with {"task_id":"TASK_ID"} no sooner than the returned poll_interval_ms (currently 3,000 ms). Status is queued, running, completed, failed, or cancelled; a completed task includes result and its download artifact. cancel_task stops an unfinished job. Jobs are private to the connection that started them and expire 24 hours after creation. New starts are rejected when the connection already has five unfinished jobs. Background processing uses the same data and file-size limits as direct exports.

Download links last 15 minutes. While a completed job and its stored artifact remain available, retrieving the job renews an expired download link. Artifact content is retained for 24 hours after creation; renewal does not extend that retention. Regenerate a direct export after its link expires, or start a new job after the old one expires. Screenshot and attachment links inside a CSV expire separately; generate a fresh export when you need new file links.

These are regular MCP tools; support for experimental protocol task APIs is not required.

Compatible clients can browse connection, project, comment, and job resources, or use the triage_feedback, release_report, and investigate_comment prompts. Hosts that support MCP Apps can display a read-only feedback browser. Other clients receive ordinary tool results and links.

Reply attachments

Attachment uploads require a client capable of uploading files to a signed URL. Call prepare_attachment_upload with these arguments (the size is the actual file size in bytes):

{
  "project_id": "PROJECT_ID",
  "filename": "review.png",
  "mime_type": "image/png",
  "size": 12345
}

Upload those bytes with HTTP PUT to the returned upload_url, using its headers, before the returned expires_at (15 minutes). Then call reply_to_comment:

{
  "project_id": "PROJECT_ID",
  "comment_id": "COMMENT_ID",
  "text": "Here is the updated screenshot.",
  "attachments": [{ "upload_id": "UPLOAD_ID" }],
  "idempotency_key": "review-reply-2026-09-06"
}

Each upload is usable once, in the same project and connection. Its declared type and size must match the uploaded object. MCP accepts files up to 100 MiB and at most 10 files per reply; plan file-size, file-count, type, storage, and retention limits may be lower. Uploads must be enabled for the project. Arbitrary remote URLs and local file paths are not imported as attachments.

Local workflow preferences

Local setup can disable AI-created comments or replies. These preferences are enforced for local tool calls. Status choices are read for the selected project; use get_project_context after changing projects to inspect its current workflow.

Local setup: Cursor and Claude Code

Step 1: Run the setup wizard

From your project's root directory, run:

npx @simple-commenter/mcp-server init

Alternatively, install the command globally and run it:

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

Step 2: Choose the project and preferences

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. Create a .mcp.json in your project root if one does not already exist

Email code didn't arrive?

Generate an API key in MCP settings (MCP → Local API tokens → Generate token) and pass it directly to skip the email step:

npx @simple-commenter/mcp-server init --token "$SIMPLE_COMMENTER_API_TOKEN"

Set SIMPLE_COMMENTER_API_TOKEN to your token in your local shell or secret manager first. The quotes pass its value as one argument. The wizard's --token option skips email verification; init does not automatically read the environment variable unless you pass it this way. Never include a real token in shared instructions or screenshots.

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 file and its permissions, token, API connectivity, default project, and .mcp.json — reports pass/fail for each. Without a global installation, run npx @simple-commenter/mcp-server doctor instead.

Configuration

.mcp.json

The wizard writes a node command pointing to its installed index.js and leaves any existing .mcp.json unchanged. For a manual, portable setup, merge this entry into your client's MCP configuration:

{
  "mcpServers": {
    "simple-commenter": {
      "command": "npx",
      "args": ["-y", "@simple-commenter/mcp-server", "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": ["-y", "@simple-commenter/mcp-server", "serve"],
      "env": {
        "SIMPLE_COMMENTER_API_TOKEN": "REPLACE_WITH_API_TOKEN"
      }
    }
  }
}

You can generate a token from the MCP settings 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 local tokens

Open MCP → Local API tokens or go directly to MCP settings to generate named tokens, inspect last use, and revoke credentials you no longer need.

CLI Commands

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

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

Hosted connection and permissions

Feedback, exports, and uploads

Local setup

Still having issues?

Run simple-commenter-mcp doctor for local diagnostics. For hosted issues, include the client name, MCP settings status, tool name, and error code when contacting support. Leave out tokens, authorization codes, signed download URLs, and private feedback.

Next Steps

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