Talk to your Superflow comments from Claude Code, Claude Desktop, Cursor, Gemini CLI, claude.ai, ChatGPT or any MCP client.
Superflow is a visual feedback and AI review layer for websites. Your team, your clients and AI review agents leave comments pinned on live pages. With this MCP server your assistant can read that feedback, filter and count it, reply, resolve, triage in bulk, and draft client updates. It can also run the admin side: create a project for a new client, invite their reviewers, hand over the install snippet and check it, and manage statuses, tags and the team. And it can run the AI review agents (with a credit estimate first), schedule them, push findings to Jira, Asana, ClickUp or Monday, and post to Slack. All without leaving the editor or the chat.
| Local package | Hosted server | |
|---|---|---|
| What | npx -y @usesuperflow/mcp, a small bridge on your machine: stdio to your client, the hosted server behind it |
https://mcp.usesuperflow.ai/mcp, nothing to install |
| Auth | npx -y @usesuperflow/mcp login (browser sign-in), or an API key in SUPERFLOW_API_KEY |
OAuth, or the same API key as a bearer token |
| Tools | 101 tools: playbooks, checks (failing checks, site score, mark fixed, exclude, owners, reject), site settings (care or watch, time zone, form tests), comments (read, filter, search, count, export, update, resolve, reply, bulk), admin (projects, pages, members, guests, statuses, tags, workspace, review links, notifications, API keys, billing and invoices), and agents, runs, schedules and integrations | Workspace, project, agent, analytics and team tools |
| Best for | Claude Code, Claude Desktop, Cursor, Gemini CLI | claude.ai, ChatGPT, the Claude API, any remote client |
Both give the same tools, because the local package forwards every request to the hosted server (see How the local package works). You can use both at once.
Sign in once with your browser. New to Superflow? You can sign up on the same page:
npx -y @usesuperflow/mcp loginThe sign-in is saved (see Sign in with the browser), so the
configs below work without a key: leave out the SUPERFLOW_API_KEY lines. For CI, or a
key with narrower scopes, use an API key instead. See Get an API key.
claude mcp add superflow -e SUPERFLOW_API_KEY=sf_pat_... -- npx -y @usesuperflow/mcpAdd this to claude_desktop_config.json (Settings > Developer > Edit Config), then restart Claude Desktop:
{
"mcpServers": {
"superflow": {
"command": "npx",
"args": ["-y", "@usesuperflow/mcp"],
"env": {
"SUPERFLOW_API_KEY": "sf_pat_..."
}
}
}
}Add this to ~/.cursor/mcp.json, or .cursor/mcp.json in a project:
{
"mcpServers": {
"superflow": {
"command": "npx",
"args": ["-y", "@usesuperflow/mcp"],
"env": {
"SUPERFLOW_API_KEY": "sf_pat_..."
}
}
}
}gemini mcp add -s user -e SUPERFLOW_API_KEY=sf_pat_... superflow npx -y @usesuperflow/mcpDo not put -- before npx. Or add the same mcpServers block as Cursor to
~/.gemini/settings.json, or to .gemini/settings.json in a project.
Gemini CLI starts MCP servers only in a trusted folder. It asks the first time you open a
folder; for a headless gemini -p run, pass --skip-trust or set
GEMINI_CLI_TRUST_WORKSPACE=true. The tools show up as mcp_superflow_superflow_..., and
gemini mcp list should show superflow as Connected.
Go to Settings > Connectors > Add custom connector and paste:
https://mcp.usesuperflow.ai/mcp
Claude opens the Superflow consent screen. You pick the workspace and the permissions. No token is copied anywhere.
Add a custom MCP connector in ChatGPT and use the same URL, https://mcp.usesuperflow.ai/mcp. ChatGPT runs the OAuth flow.
claude mcp add --transport http superflow \
https://mcp.usesuperflow.ai/mcp \
--header "Authorization: Bearer sf_pat_..."For Cursor, see examples/cursor-mcp.json. For the Claude API, see examples/claude-api.json.
More examples: examples/.
-
Open the Superflow portal and go to Settings > Integrations > API keys.
-
Check the workspace selector at the top. A key belongs to one workspace.
-
Create a key, give it a name (for example
Cursor on my laptop), and pick the scopes for what the assistant should do:- Comments:
comments:read,comments:writeandprojects:read. - Admin tools:
projects:write(projects, pages, install checks, statuses, tags, review links),users:invite(invite members and guests),users:write(remove members and guests),workspace:read(workspace, credit usage, activity, your notification settings) andworkspace:write(rename the workspace, change your notification settings). - Agents:
agents:read(agents, packs, estimates, runs, schedules),agents:write(create, change and delete agents and packs) andagents:run(start runs and manage schedules; runs spend AI credits). Findings also needcomments:read. - Integrations:
integrations:read(connected tools) andintegrations:write(connect links, push a comment to a tracker, post to Slack; pushing also needscomments:read).
Leave out the write scopes for a read-only key. A tool whose scope the key lacks answers with a clear forbidden error.
- Comments:
-
Pick an expiry, then copy the key. It is shown once. Superflow stores only a hash.
The same key works for the local package, the hosted server and the REST API. Revoke it on the same screen.
npx -y @usesuperflow/mcp is a thin bridge. It speaks stdio to your MCP client and forwards every request (tools, prompts, resources, completions) to the hosted server at https://mcp.usesuperflow.ai/mcp over Streamable HTTP, with your API key or your login sign-in as the bearer token. The tools run on the hosted server, so the local package and the hosted connector are one server: the same tools, the same answers, and the same key. Results and errors come back unchanged. The install snippets below do not change.
What the bridge adds: it renews a sign-in's token (once more after a refused one), applies read-only mode locally, waits up to 150 seconds for a tool call (the longest tools, tag rewrites, take up to 90), and says clearly when the hosted server cannot be reached or refuses the key. A tool call is never sent twice, since it may change data. It names itself to the hosted server (X-Superflow-Client: superflow-mcp/<version>).
For development only, SUPERFLOW_API_BASE_URL switches to direct mode: the tools run in the process and call that REST API themselves, and the server says so on stderr at start.
npx -y @usesuperflow/mcp login opens Superflow's consent screen in your browser. Sign in (or
sign up), pick the workspace and the permissions, and approve. The terminal finishes on its
own.
-
It is OAuth 2.1 with PKCE on a one-time loopback address (
http://127.0.0.1:<port>), the same consent screen the hosted connector uses. No key is copied by hand. -
It asks for the scopes the tools need:
workspace:read,projects:read,projects:write,agents:read,agents:run,agents:write,analytics:read,comments:read,comments:write,integrations:read,integrations:writeandingest. Untick any on the consent screen. Four are left out, so you ask for them by name:users:invite(sends real invite email),users:write(removes members and guests),workspace:write(creates and revokes API keys, renames the workspace) andusers:read(no tool needs it). -
--scopereplaces that list, to narrow it or to add one of the four. Name every scope you want, separated by spaces or commas. A sign-in's scopes cannot be changed afterwards: runloginagain with the new list.npx -y @usesuperflow/mcp login --helpprints both lists.npx -y @usesuperflow/mcp login --scope "comments:read projects:read" -
The sign-in is saved in the macOS Keychain, the Linux Secret Service (
secret-tool), or, when neither is available,~/.config/superflow-mcp/credentials.json(%APPDATA%on Windows) readable only by you. The command says which. -
Access tokens last an hour and are renewed in the background while the server runs.
-
npx -y @usesuperflow/mcp logoutends the sign-in and removes it. You can also revoke it in Superflow under Settings > Integrations > API keys > Connected AI apps. -
SUPERFLOW_API_KEY, when set, always wins over a saved sign-in.
| Variable | Required | Default | What it does |
|---|---|---|---|
SUPERFLOW_API_KEY |
no, if you ran login |
Your API key (sf_pat_...). Wins over a saved sign-in. |
|
SUPERFLOW_AUTH_URL |
no | https://mcp.usesuperflow.ai |
The sign-in server login uses. |
SUPERFLOW_CREDENTIALS_STORE |
no | auto |
auto (Keychain or Secret Service, else a file) or file. |
SUPERFLOW_CREDENTIALS_FILE |
no | ~/.config/superflow-mcp/credentials.json |
Where the file store keeps the sign-in. |
SUPERFLOW_MCP_URL |
no | https://mcp.usesuperflow.ai/mcp |
The hosted MCP server the bridge forwards to. Must be https (http only for localhost). A saved sign-in uses the server it signed in with. Staging: https://superflowmcphandler-4mfhcuyw2q-uc.a.run.app/mcp (use the run.app origin: the cloudfunctions.net one fails the OAuth resource check). |
SUPERFLOW_API_BASE_URL |
no | Development only. When set, the tools run in the process against this REST API instead of the hosted server (direct mode). The API is served by the same function as the hosted MCP server: https://mcp.usesuperflow.ai/v1, staging https://superflowmcphandler-4mfhcuyw2q-uc.a.run.app/v1. Must be https (http only for localhost), and on the same origin as the MCP server the key or sign-in is for (SUPERFLOW_MCP_URL, the saved sign-in's, or the default), or the server refuses to start. |
|
SUPERFLOW_READ_ONLY |
no | false |
true hides every write tool. |
SUPERFLOW_LOG_LEVEL |
no | info |
debug, info, warn, error or silent. Logs go to stderr. |
Requires Node.js 20 or later.
Set SUPERFLOW_READ_ONLY=true and the 56 write tools are not listed, and a call to one is refused on your machine without reaching Superflow. The 45 read tools stay: the assistant can still read, filter, count and export, look up projects, guests, the workspace and credit usage, read agents, runs, findings, schedules and integrations, estimate what a run would cost, and get a link to connect a tool (those two only read). The prompts still work. For a hard guarantee, and prompts and server instructions that present changes as recommendations, also use a key without the write scopes (comments:write, projects:write, users:invite, users:write, workspace:write, agents:write, agents:run, integrations:write, ingest).
claude mcp add superflow -e SUPERFLOW_API_KEY=sf_pat_... -e SUPERFLOW_READ_ONLY=true -- npx -y @usesuperflow/mcpFull parameters and examples: docs/tools.md.
A check is one kind of problem the agents look for (link-broken, image-alt, mobile-overflow and the rest, by rule_key). Each check groups its open findings across the site.
| Tool | What it does |
|---|---|
superflow_list_failing_checks |
The failing checks of a site, worst first: severity, open findings, pages, owner and how many score points fixing it is worth. |
superflow_get_check_details |
One check: its fix guide and its open findings with their pages and links, 20 at a time. |
superflow_get_site_score |
The site score, the runs before it, and the lowest scoring pages. |
superflow_get_finding_source |
The line of stored HTML a finding points at, to find it in the code. |
superflow_mark_check_fixed |
Resolves every open finding of a check and has a rescan verify it (1 credit). Needs confirm: true; without it the tool shows what it would resolve. |
superflow_exclude_check |
Turns a check off for a site, with a reason. Needs confirm: true. |
superflow_include_check |
Turns an excluded check back on. |
superflow_assign_check_owner |
Sets who owns a check, or back to the default owner. |
superflow_reject_comment |
Rejects an agent finding as wrong, not important, not applicable or cannot tell. It cannot be undone, so it needs confirm: true; without it the tool shows the finding. |
superflow_get_check_settings |
The confidence floor and the default owners for content, design and dev checks. |
superflow_set_default_owners |
Sets the default owners for content, design and dev checks. |
| Tool | What it does |
|---|---|
superflow_get_site_monitoring |
Whether a site is in care (agents run on a schedule) or watch (Version history only), with the cadence, time zone and the run in progress. |
superflow_set_site_mode |
Moves a site to care or watch. care runs agents and spends AI credits, so it needs confirm: true; on a site never monitored it starts a full check now. |
superflow_set_site_timezone |
The time zone scheduled checks and Version history captures run in. |
superflow_list_forms |
The forms the Forms agent found on a site, with their test settings and last result. |
superflow_set_form_testing |
Turns a form's test on or off. On needs confirm: true: each test lands in the client's inbox as a lead. |
Resolving or marking a check fixed is a claim: a rescan verifies it, and a problem that is still there comes back as an open finding. superflow_resolve_comment and superflow_update_comment say when they queued that rescan.
| Tool | What it does |
|---|---|
superflow_get_me |
Who the key belongs to: member, workspace, plan, scopes. |
superflow_list_projects |
Projects (websites) with install status and open comment counts. |
superflow_list_pages |
Pages of a project with open and total comment counts. |
superflow_list_members |
Your team, plus a project's guests. |
superflow_list_statuses |
Workflow statuses in order, and which count as resolved. |
superflow_list_tags |
The tags on comments, workspace-wide or for one project, and how many comments carry each. |
superflow_list_comments |
Find comments by project, page, status, assignee, tags, dates, text and more. |
superflow_get_comment |
One comment with every field and its replies. |
superflow_comment_stats |
Counts grouped by page, status, assignee, week and more, plus response times. |
superflow_export_comments |
Export matching comments as csv, json or markdown. |
superflow_create_comment |
Leave a new, public comment on a page. |
superflow_update_comment |
Change one comment: text, priority, status, assignee, tags (a new name creates the tag), page or pin. |
superflow_resolve_comment |
Resolve one comment, with an optional note. |
superflow_reopen_comment |
Reopen one comment, with an optional note. |
superflow_add_reply |
Reply in a thread, with @mentions. |
superflow_update_reply |
Edit a reply. |
superflow_delete_reply |
Delete a reply (needs confirm). |
superflow_delete_comment |
Delete a comment thread for good (needs confirm; it cannot be restored). |
superflow_bulk_update_comments |
Change up to 200 comments at once (dry run first, then confirm). |
superflow_add_attachment |
Attach a file by URL to a comment or reply. |
| Tool | What it does |
|---|---|
superflow_get_project |
One project: install status, counts, statuses and settings. |
superflow_create_project |
Create a project for a site, optionally inviting guests (sends email). |
superflow_update_project |
Rename, change settings (guest comments, toolbar, commenting) or add domains. |
superflow_archive_project |
Archive a project. Nothing is deleted. |
superflow_unarchive_project |
Bring an archived project back. |
superflow_delete_project |
Delete a project for good, with its comments (needs confirm). |
superflow_get_install_snippet |
The script tag and install steps for the site's platform. |
superflow_verify_install |
Check that the snippet is live on the site. |
superflow_get_page |
One page with its comment counts. |
superflow_add_page |
Add a page before anyone comments on it. |
superflow_remove_page |
Remove a page and delete its comments for good (needs confirm). |
superflow_invite_member |
Invite teammates to the workspace (sends email). |
superflow_remove_member |
Remove a teammate, optionally reassigning their open comments (owner only, needs confirm). |
superflow_list_guests |
A project's guests. |
superflow_invite_guest |
Invite clients or reviewers to one project (sends email). |
superflow_remove_guest |
Take a guest off one project (needs confirm). |
superflow_create_status |
Add a custom status, for the workspace or one project. |
superflow_update_status |
Rename or recolor a status. |
superflow_reorder_statuses |
Set the order of the statuses. |
superflow_delete_status |
Delete a status, moving its comments to another (needs confirm). |
superflow_update_tag |
Rename or recolor a tag on every comment that carries it. |
superflow_delete_tag |
Take a tag off every comment that carries it (needs confirm). |
superflow_merge_tags |
Fold one tag into another, or into a new name (needs confirm). |
superflow_get_organization |
The workspace: plan, seats, projects and AI credits. |
superflow_update_organization |
Rename the workspace (owner only). |
superflow_get_credit_usage |
AI credits used, by project, agent or day. |
superflow_list_activity |
Changes made through the API, newest first. |
superflow_list_review_links |
Active public review links. |
superflow_create_review_link |
Share a project with a public review link (Velt-internal accounts only for now). |
superflow_revoke_review_link |
Turn a review link off (needs confirm). |
superflow_get_notification_settings |
Your own digest, inbox and email settings. |
superflow_update_notification_settings |
Change your own notification settings. |
Tags are workspace-wide and live on the comments: a tag exists while some comment carries it, and putting a new name on a comment creates it. Give tags by name; a tag_ id works only for a tag already on the comment, and a color given with a name colors that comment's copy only, so one tag can show two colors. Tags are visible to everyone who can see the comment, clients and review-link viewers included, so do not put private notes in tags. superflow_list_tags reads up to 10,000 comments a page and pages on with next_cursor; a tag can show on several pages. Renaming, recoloring, deleting or merging a tag rewrites at most 500 comments a call: the assistant goes on with the next_cursor of each answer until it is null, and makes at most one retry pass for comments that could not be rewritten. The delete and merge previews count with the same paging, and the change itself starts from the first comment. Comments counted in failed then could not be changed (on a project with more than 1,000 comments, only the newest 1,000 can be), and the rewritten comments show as just updated.
| Tool | What it does |
|---|---|
superflow_list_agents |
AI review agents, built-in and custom, and which run by default. |
superflow_get_agent |
One agent, with a custom agent's instructions. |
superflow_create_agent |
Create a custom agent from plain-language instructions. |
superflow_update_agent |
Turn an agent on or off, or edit a custom agent. |
superflow_delete_agent |
Delete a custom agent (needs confirm). |
superflow_duplicate_agent |
Copy a custom agent. |
superflow_list_agent_packs |
Agent packs, such as Copy QA, SEO or your own. |
superflow_create_agent_pack |
Group agents into a pack. |
superflow_update_agent_pack |
Change a pack's name, description or agents. |
superflow_estimate_run |
What a run would cost in AI credits, and whether the balance covers it. Charges nothing. |
superflow_run_agents |
Start a run on a site, a page or a list of pages (spends credits; estimate first, then confirm). |
superflow_get_run |
A run's live status per agent. |
superflow_list_runs |
Every agent run of the workspace, newest first, with what started it: the API or MCP, a schedule, the portal or Always-on Monitoring. An import is not a run and is not listed. |
superflow_list_findings |
What a run found, with severity and confidence. Also takes an import's run id. |
superflow_set_schedule |
Create or change a scheduled run (cron, at most hourly; each run spends credits; the agents are fixed when it is saved). Needs confirm: true, except to pause or move the time zone; without it the tool shows the price of one run. |
superflow_list_schedules |
Scheduled runs, their agents, the next run and how the last one went (started, skipped and why, or failed to start). |
superflow_delete_schedule |
Delete a schedule (needs confirm). |
| Tool | What it does |
|---|---|
superflow_list_integrations |
Connected tools: Slack, Jira, Asana, ClickUp, Monday. |
superflow_get_integration |
One connection and whether it still works. |
superflow_connect_integration |
A link the user opens to connect a tool. The assistant cannot finish the sign-in. |
superflow_push_comment |
Create a Jira issue or a task from a comment, and link it on the comment. Needs project_key; a comment already in that tool returns its link and creates nothing. |
superflow_post_to_slack |
Post a message, with comments, to a Slack channel (needs confirm). |
Superflow has three priorities you can set: critical (P0), high (P1) and medium (P2). Removing an assignee or clearing a priority is not supported yet, so the assistant will ask you to do that in the Superflow toolbar. Filters can still find low and none priority comments and unassigned ones.
Every id parameter also takes a name, a site URL or an email, and a comment is given by its id or its link. The API resolves it. When a name matches more than one thing, the tool returns the candidates so the assistant can ask you which one.
Some admin changes are not available: a project's site URL cannot change (add extra domains instead), members have no roles beyond owner and admin, and review links have no expiry. Deleting a project is permanent. While a project has an active review link it is in preview: archiving, install checks and settings changes wait until the link is revoked. Site, domain and page addresses are full https:// URLs.
Some agent and integration features are not available yet: a run cannot be cancelled once started, schedules run on a cron (not when a page changes) with the agents fixed when the schedule is saved, a pack cannot be the default for runs (runs that name no agents use Superflow's default agents), and disconnecting a tool happens in the Superflow portal. Run prices are exact in scan pricing and an estimate in flat pricing; workspaces billed by model usage cannot be priced in advance. Pushing a comment needs the target's ids, not names, every time (a connection has no default project): Jira KEY:12345 (project key and numeric project id), Asana <workspace gid>:<project gid>, ClickUp <team>:<space>:<list>, Monday <board id>. Asana, ClickUp and Monday connections must also be set up to create items from Superflow.
| Tool | What it does |
|---|---|
superflow_use_playbook |
Gets a step-by-step plan for a job that takes several tools in order, and the model follows it: triage (what is broken on a site, as one ordered P0, P1, P2 list), fix (fix the approved items, have a rescan verify each, report), push_my_review (push your own review's findings in) and onboard_agency (a first client site, checked on a schedule). Nothing to install: the server serves them. |
| Tool | What it does |
|---|---|
superflow_get_billing |
Plan, whether it is active, when the period or trial ends, the billing interval, and the portal page to change it. |
superflow_get_payment_link |
The portal page where a person picks a plan and pays, or changes seats. Nothing is charged from a tool, and a workspace that already pays is never offered a second subscription. |
superflow_get_invoices |
The workspace's invoices, newest first, with Stripe's links to view, pay or download each. Owner only. |
| Tool | What it does |
|---|---|
superflow_list_api_keys |
Your own keys and app sign-ins in this workspace. Never the tokens. |
superflow_create_api_key |
A new key for CI or another tool. Needs an API key with workspace:write (a sign-in cannot create keys); scopes must be ones the current key has, and it cannot outlive it. Needs confirm: true; the preview says first when the key cannot be created. The token is shown once, in the conversation. |
superflow_revoke_api_key |
Revoke a key or sign-in. Needs confirm: true. |
| Tool | What it does |
|---|---|
superflow_get_team_analytics |
Comments added and resolved, and the active projects, over 1, 7, 14 or 30 days. |
superflow_get_people_analytics |
Who commented, who resolved, who has work waiting, over the same windows. |
superflow_get_all_time_analytics |
The workspace's all-time rollup. |
Analytics are computed once a day. When is_stale is true the numbers are not available yet; the tools say so instead of reporting zero activity.
| Tool | What it does |
|---|---|
superflow_import_findings |
Pushes the findings of your own review (your prompts, your agent) into Superflow. Each becomes an agent comment pinned on its page under your agent's name, and merges with the same finding next time. They are not checks: the failing checks and the fix list do not include them. Up to 500 per call, 5,000 per project per day. Needs the ingest scope. |
In Claude Code the fix playbook can run one subagent per item, up to 3 at a time; other clients run the same steps in order. The playbooks are also prompts of the same name, so clients that show prompts as slash commands offer /fix, /triage, /push_my_review and /onboard_agency.
The server also ships eleven prompts (triage, fix, push_my_review, onboard_agency, stale_threads, client_update, agent_findings_review, find_duplicates, launch_checklist, onboard_client, prelaunch_run) and six resources (superflow://projects, superflow://projects/{project}, superflow://projects/{project}/comments, superflow://comments/{comment}, superflow://organization, superflow://runs/{run}).
- What's broken on acme-dental.com? Then fix the critical ones.
- What is the site score of Acme, and which checks cost it the most points?
- Show me open comments on usesuperflow.ai/pricing.
- How many unresolved comments per page on the Acme project?
- Which comments from guests have had no reply from us in 3 days?
- Resolve everything tagged
copyon the homepage. - Assign all high priority mobile comments on Acme to Jen.
- What did the agents find in the last run? Which ones look like false positives?
- Reply to the newest comment on acme.com/pricing: fixed, please check.
- Draft a client update for Acme covering what was closed this week.
- Export every resolved comment on Acme from last week as a CSV.
- What is our median time to first reply on client comments, week by week?
- Create a project for client Northwind at northwind-dental.com on Webflow, invite dana@northwind-dental.com, and give me the install snippet.
- Is the Superflow snippet live on acme.com yet?
- How many member seats do we have left, and which agent used the most AI credits this month?
- Merge the tag "Copy text" into "copy", then add an "In review" status on Acme.
- Estimate a full run of the Pre-Launch pack on Acme, then run it.
- What did the agents find in the last run on Acme? Group it by severity and push the critical ones to Jira.
- Run the Pre-Launch pack on Acme every Monday at 9am Berlin time.
- Post the open critical comments on Acme to our #design-feedback Slack channel.
More in examples/prompts.md.
- Deletes, removals, tag merges and review link revokes need
confirm: true. Without it the tool only reads and shows what would happen. Deleting a comment, a project, or a page with its comments is permanent: nothing can be restored. - Invite tools (and guests on a new project) send real email. The assistant is told to ask you first.
- A review link makes a project visible to anyone who has the link.
- Agent runs spend AI credits. The assistant prices the run with
superflow_estimate_run, shows you the credits and asks;superflow_run_agentsstarts nothing withoutconfirm: true. When the balance is too low it tells you how to add credits and does not retry. - Pushing a comment creates a real issue or task in your Jira, Asana, ClickUp or Monday, and a Slack post is seen by everyone in the channel. The assistant asks first, and a Slack post needs
confirm: true. - Marking a check fixed resolves every one of its open findings and spends 1 credit on the rescan, excluding a check hides it for the whole site, and rejecting an agent finding cannot be undone. All three need
confirm: true; without it the tool only reads and shows what would happen. Resolving an imported finding (fromsuperflow_import_findings) never spends a credit: Superflow cannot rerun an outside agent, so it is only resolved. - A schedule runs agents, and spends credits, on every run. Creating one, or changing what or when it runs, needs
confirm: true; without it the tool prices one run and shows it. Pausing needs no confirm. - Bulk updates are a dry run by default: it says how many comments would change and how many already match. A real run needs
dry_run: falseandconfirm: true. The tool descriptions tell the assistant to ask you first. - Comment text comes from website visitors. Results that contain it carry a notice telling the model to treat it as data, not instructions.
- The key is only ever sent as the bearer token to the Superflow MCP server (in development mode, to the Superflow API), and it is never logged. See SECURITY.md.
@usesuperflow/mcp-staging is the same package built for Superflow staging. It is private:
run npm login first with an npm account that has access to the usesuperflow org.
npx -y @usesuperflow/mcp-staging login
claude mcp add superflow-staging -- npx -y @usesuperflow/mcp-stagingIt forwards to staging (https://superflowmcphandler-4mfhcuyw2q-uc.a.run.app/mcp) by default,
so it needs no SUPERFLOW_MCP_URL. It keeps its sign-in apart from the prod package (the
superflow-mcp-staging Keychain or Secret Service entry, or
~/.config/superflow-mcp-staging/credentials.json), so signing in to one never signs you out
of the other. Every push to the staging branch publishes a new version.
The hosted server lives at https://mcp.usesuperflow.ai/mcp. It speaks Streamable HTTP and accepts OAuth 2.1 (with dynamic client registration) or an API key as a bearer token. A client only sees the tools its scopes allow.
These are the hosted server's first 20 tools. They are being replaced by the package tool set, the 101 tools under Tools, on the hosted server and so through the local package too. Until a workspace has the package tool set, the local package forwards these 20.
| Area | Tool | Scope | What it does |
|---|---|---|---|
| Workspace | list_workspaces |
workspace:read |
Every workspace you belong to, marking the one this token is bound to. |
| Workspace | get_workspace |
workspace:read |
Plan, feature access, usage counters and AI credit balance. |
| Projects | list_projects |
projects:read |
Projects (websites), most recent activity first. |
| Projects | get_project |
projects:read |
One project: name, URL, status, category, versions, install platform. |
| Projects | get_install_snippet |
projects:read |
The script tag to paste into a site. |
| Projects | create_web_project |
projects:write |
Create a website project for a URL. |
| Projects | verify_installation |
projects:write |
Check whether the snippet is live on the site and mark it installed. |
| Projects | update_project_status |
projects:write |
Set a project's status, for example archive it. |
| Agents | list_agents |
agents:read |
Review agents in the workspace, plus their groups. |
| Agents | get_agent_run |
agents:read |
Status and findings of one run. Poll every 15 to 30 seconds after run_agents. |
| Agents | list_agent_runs |
agents:read |
Past runs, newest first, by project, agent or both. |
| Agents | create_agent |
agents:write |
Create a custom review agent from plain-language instructions. |
| Agents | run_agents |
agents:run |
Start one run per agent against a page. Uses AI credits. |
| Comments | list_comments |
comments:read |
Comments on a project, from people and agents. |
| Comments | get_agent_findings |
comments:read |
The comments an agent left, optionally for one run. |
| Analytics | get_team_analytics |
analytics:read |
Comment, resolution and project activity for a lookback window. |
| Analytics | get_people_analytics |
analytics:read |
Per-person activity: who commented, who resolved, who is idle. |
| Analytics | get_past_data_analytics |
analytics:read |
All-time counts, most active projects and people. |
| Team | invite_team_member |
users:invite |
Invite people to the workspace with access to every project. |
| Team | invite_guest |
users:invite |
Invite people to a single project only. |
Invites send real email. Both invite tools cap at 10 recipients per call, remove duplicates, and take the inviter from your grant, never from model input.
Two tools work with no token, at https://mcp.usesuperflow.ai/mcp/try:
{
"mcpServers": {
"superflow-try": {
"url": "https://mcp.usesuperflow.ai/mcp/try"
}
}
}| Tool | What it does |
|---|---|
run_site_preview |
Start a free Superflow review of any public URL. |
get_site_preview |
Poll it and read the findings once the agents finish. |
The authenticated endpoint never serves these two, and this endpoint never serves anything else.
| Scope | Grants |
|---|---|
workspace:read |
Read workspace plan, features and usage. With the local package and REST API also: AI credit usage, the API activity log and your own notification settings. |
projects:read |
Read projects, pages, members and install snippets. |
projects:write |
Create projects, verify installs, set status. With the local package and REST API also: update, archive and delete projects, add and remove pages, and manage statuses, tags and review links. |
agents:read |
Read agents and their run history. With the local package and REST API also: packs, run estimates, findings and schedules. |
agents:run |
Start agent runs (uses AI credits). With the local package and REST API also: manage schedules. |
agents:write |
Create agents. With the local package and REST API also: change, copy and delete agents, and manage packs. |
comments:read |
Read comments, replies, statuses, tags and agent findings. |
comments:write |
Create, update, resolve, reply to and delete comments (local package and REST API). |
analytics:read |
Read team, people and all-time analytics. |
users:invite |
Send workspace and project invitations, and post as a project guest. |
users:write |
Remove members and guests (local package and REST API). |
workspace:write |
Rename the workspace and change your own notification settings (local package and REST API). |
integrations:read |
Read connected tools (local package and REST API). |
integrations:write |
Get connect links, push comments to a tracker and post to Slack (local package and REST API). |
ingest |
Push your own review's findings in as agent comments; creates or merges, never deletes (local package and REST API). |
See docs/migrating-from-bugherd.md for how BugHerd terms and endpoints map to Superflow tools.
See CONTRIBUTING.md. In short: pnpm install, pnpm test, pnpm build, pnpm check:drift.
The e2e suite (pnpm test:e2e) runs the built package over real stdio on every pull request and every push to staging and main: in direct mode against a local fake API (every tool), and in bridge mode against a local fake of the hosted server. The live suite (pnpm test:live, test/live/ plus test/integration/) runs against a real API on every push to staging and main when SUPERFLOW_TEST_API_KEY and SUPERFLOW_TEST_PROJECT are set. It works inside an existing project. The admin tools can now create and delete a throwaway project, but the suite does not do that yet.
- Issues and feature requests: open an issue
- Email: eng@usesuperflow.com
- Security: see SECURITY.md