pincushion-mcp
Pincushion MCP lets you manage UI feedback pins end-to-end, from local .feedback/ files or the cloud, including agent workflows, AI critiques, project setup, reporting, and team integrations.
Read, search, filter, and summarize pins by status, page, component, or full text.
Work on pins: get actionable/approved/selected pins, claim them, implement fixes, reply, approve, assign to agents, and resolve with commit/branch/PR traceability.
Run AI critique workflows: fetch pending critiques, create critique pins, post bot replies, complete critique requests, verify resolved pins, and link deploys.
Set up and configure projects: get setup instructions, inspect project context, register URLs, manage brand/critique context, and configure traceability settings.
Manage collaboration: add/list/remove members, create invite links, and generate public share reports.
Upload annotated page snapshots for share reports with numbered pin positions.
Connect and manage Slack/Teams notifications, previews, webhook integrations, and Slack DM preferences.
Allows linking pull requests in Bitbucket to resolved annotations via the prUrl parameter.
Provides configuration for Windsurf, a Codeium product, to use the MCP server for AI-native development.
Allows linking pull requests in GitHub to resolved annotations via the prUrl parameter.
Allows linking pull requests in GitLab to resolved annotations via the prUrl parameter.
Supports OpenAI Codex and other REST API clients via a REST API wrapper for tool invocation.
Enables remote sync of feedback data with a Supabase backend using sync-url and api-key flags.
Pincushion
Teammates and clients pin feedback on your live app in
Pincushion. Each pin is a work packet for your
coding agent: page URL, CSS selector, screenshot, DOM snippet, viewport and the
comment thread. This repository is the plugin marketplace for Claude Code, Codex
and Cursor and the MCP registry metadata for pincushion-mcp
(npm 1.14.0).
Requires Node.js 22.22 or newer, or Node.js 24. On older Node the server
exits at start and the Pincushion tools just don't appear. Check with
node --version. Do not put a license key in any MCP config: sign-in writes
~/.pincushion/license-key for you.
Quick start
One repository installs Pincushion in Claude Code, Codex and Cursor. Each host
gets the same skills: setup signs you in and links your repo to a project from
inside the agent, doctor checks what's missing without changing anything, and
pins, critique, implement, resolve, feedback-summary and
send-feedback do the work.
Claude Code
claude plugin marketplace add jcooley8/pincushion-plugin
claude plugin install pincushion@pincushionStart Claude Code in your app's repository and run /pincushion:setup. Then
/pincushion:pins lists open feedback and
/pincushion:critique https://your-site.example runs a Pincushion crit of that
URL. If anything looks off, run /pincushion:doctor.
Codex
codex plugin marketplace add jcooley8/pincushion-plugin
codex plugin add pincushion@pincushionStart a new Codex task in your app's repository and ask: "Set up Pincushion
for this repository." You can also install it from /plugins inside Codex.
Cursor
For a team: in the Cursor dashboard open Plugins & MCPs → Add Marketplace →
Import from Repo, enter https://github.com/jcooley8/pincushion-plugin, then
install Pincushion from Customize.
For one machine, link the plugin folder into Cursor's local plugins and reload the window (Developer: Reload Window):
git clone --depth 1 https://github.com/jcooley8/pincushion-plugin ~/.pincushion-plugin
mkdir -p ~/.cursor/plugins/local && ln -s ~/.pincushion-plugin/plugins/pincushion ~/.cursor/plugins/local/pincushionThen ask the agent: "Set up Pincushion for this repository."
To add only the MCP server, without the skills:
Add Pincushion to Cursor.
That deeplink installs npx -y pincushion-mcp over stdio and sets no license
key. Restart Cursor in your app's repository, then follow
First steps.
VS Code
code --install-extension pincushion.pincushion-feedbackOr install Pincushion Feedback from the Marketplace. Reload the window in your app's repository, then follow First steps.
To add the server without the extension, put this in .vscode/mcp.json:
{
"servers": {
"pincushion": {
"command": "npx",
"args": ["-y", "pincushion-mcp@latest"]
}
}
}Cline
Add the pincushion entry from llms-install.md to cline_mcp_settings.json. It is npx -y pincushion-mcp@latest over stdio, with no API key. Pin reads work before sign-in. The same page has the sign-in command.
Any other MCP client
Add this stdio server. Start the client in your app's repository so the server's working directory is that repo. If the client starts somewhere else, append "--project-dir" and the absolute path of the repo to args.
{
"mcpServers": {
"pincushion": {
"command": "npx",
"args": ["-y", "pincushion-mcp@latest"]
}
}
}Related MCP server: Lens
First steps
With a plugin installed, run the setup skill (above): it signs you in with a browser link and links the repository to a project without leaving the agent.
Without a plugin, run this in your app's repository:
npx -y pincushion-mcp setupSetup opens a browser, signs you in, and links the repository to a Pincushion project. Restart the client, then ask: "show my open Pincushion pins."
Before that sign-in the server still starts. get_actionable_pins, get_annotations and get_feedback_summary read pins in this repo's .feedback/ directory, and an empty workspace includes a sample pin that is not saved to your project. claim_pin, fix_and_resolve, cloud pins and critiques need the setup sign-in.
The Pincushion browser extension is optional. Pins can come from shared review links, Pincushion AI critiques, other agents and the REST API.
License
The plugin files in this repository are MIT licensed. The pincushion-mcp
package they install carries its own license, published with the package on npm.
Available Tools
39 toolsadd_agent_replyB
Add a reply to an annotation thread (e.g. to ask a clarifying question or note a finding).
Inputs: body (required), annotationId (required), author.
add_bot_replyA
Post a Pincushion AI reply to a pin's thread. Hardcodes author="Pincushion AI" and authorEmail="pincushion-bot@pincushion.io" so the Chrome extension applies bot styling. ONLY call from the /pincushion-replies flow — never as a generic reply. Refuses to post if the latest thread message is already bot-authored (defense-in-depth idempotency).
Inputs: body (required), annotationId (required).
add_memberA
Add a collaborator to a PinCushion project. Developers consume a paid seat and can implement pins. Commenters are free and unlimited. Returns an upgrade prompt if the seat limit is reached.
Inputs: role (required), email (required), projectId (required), name.
approve_pinA
Mark a pin as approved for implementation. Only approved pins should be implemented by agents. This transitions the pin from "open" to "approved" status.
Inputs: annotationId (required), approvedBy.
assign_pin_to_agentA
Assign a pin directly to your local coding agent. Promotes the pin to "ready" (if not already), marks it as pending_implementation, and drops a trigger file in .feedback/.agent-queue/ that agent-loop.mjs picks up and dispatches to Cursor / Claude Code / Codex. This is the first-class "assign to agent" action — turns a pin into agent work in one call. Workflow: assign_pin_to_agent → (agent-loop dispatches) → fix_and_resolve.
Inputs: annotationId (required), assignedBy.
claim_pending_slack_installA
LEGACY FALLBACK. Since May 2026, Slack installs auto-link to a Pincushion license when the installer's Slack email matches, and channels are subscribed via /pincushion subscribe inside Slack — no claim token needed. This tool only applies when the installer's Slack email did NOT match an active Pincushion license at install time (the user sees a claim_token on the post-install page in that case). Pass claimToken (the on-page token, valid 7 days) + projectId to attach the webhook. Calling with no claimToken returns the new flow instructions instead of an error.
Inputs: projectId (required), claimToken (required), name, events, +2 more.
claim_pinA
Claim an actionable pin before starting work on it. Transitions the pin from "pending_implementation" to "implementing" so other agents know it is being worked on. Call this before making changes, then call fix_and_resolve when done.
Inputs: annotationId (required), implementer.
complete_critique_requestA
Mark a critique_queue request as completed after the critic subagent has run on its page URLs. Pass the request id (from get_pending_critiques) and the total pin_count produced. The server scopes the update to your license — you cannot complete another tenant's request even if you know the id.
Inputs: id (required), pinCount.
configure_collaboration_integrationA
Connect a Pincushion project to Slack or Microsoft Teams using an incoming webhook. Low-noise defaults mirror Figma-style subscriptions: notify on pins marked ready, @mentions, and follow-up comments on work already being handled. Raw new-pin and resolved updates are opt-in.
Inputs: provider (required), projectId (required), webhookUrl (required), name, +5 more.
configure_projectA
Register a Pincushion project and associate it with your app's URLs. Once registered, anyone visiting those URLs with the Pincushion extension installed will automatically see the pin UI — no meta tag or manual setup needed. Pass both your local dev URL and your live/staging URL so the extension activates in all environments. Optional traceability knobs (commitTrailers, attributionComments, recordCommitSha) control how implemented pins are recorded in git and source — see each property's description. NOTE for read-only use cases: if you only need to look up brand context, URLs, or other project metadata, call get_project_context instead — configure_project mutates state (upserts the project row, syncs to cloud, creates a deploy hook, idempotently inserts the bot member).
Inputs: name (required), urls, autoCritique, brandContext, +8 more.
create_critique_pinA
Create a pin authored by Pincushion AI. ONLY call this from the pincushion-critic subagent or the /critique-latest-deploy flow — never from a regular user prompt, since the bot voice is reserved for AI-driven UI/copy/a11y feedback. Each call should produce one tasteful, high-signal pin (max 3 per page in a critique run). The body must be concrete and actionable: name the specific element + the specific problem + the suggested fix in <40 words. Forbidden: layout philosophy, business-model commentary, generic "consider improving hierarchy" advice. Always read the project's critique context (ai.critique.effectiveContext from get_project_context — falls back to brandContext when no compiled brief exists) before drafting the body so the critique is on-brand. If ai.critique.staleness is "stale" or "missing", suggest the user run /refresh-brand before continuing.
Inputs: body (required), pageUrl (required), tags, selector, +4 more.
create_invite_linkA
Generate a Figma-style shareable invite URL for a project. The recipient opens it, enters their name + email, and joins as the specified role. Returns the share URL plus expiry. Owners can mint Editor and Commenter links; Editors can mint Commenter links only. Editor links consume a paid seat on redemption.
Inputs: projectId (required), role, maxUses, expiresInDays.
create_slack_install_linkA
Generate an Add-to-Slack OAuth URL pre-bound to a project. Most users should prefer the public storefront URL (also returned, https://pincushion.io/install/slack) — since May 2026, that auto-links to a Pincushion license when the installer's Slack email matches, and channels are subscribed afterward via /pincushion subscribe inside Slack. Use this agent-flow URL only when you want the install to attach to one specific project up front.
Inputs: projectId (required), name, events, targetLabel, +1 more.
fix_and_resolveA
Resolve a pin after applying a code fix. Transitions the pin directly to "resolved" status so it disappears from the stakeholder view. No thread comment is added — the commit is the record of the fix. Pass commitSha (from git rev-parse HEAD), branchName (git branch --show-current), and prUrl (from gh pr view --json url -q .url if a PR was opened) so the Pincushion dashboard can link the pin to the implementing commit, branch, and PR.
Inputs: annotationId (required), fixDescription (required), prUrl, filePath, +3 more.
get_actionable_pinsA
Get all pins waiting for developer attention. Returns three categories: (1) "auto-agent" — pins explicitly sent to the agent via "Send to Agent" or YOLO mode; (2) "follow-up" — previously implemented pins with new user comments; (3) "review" — open reviewer comments that a developer has not yet picked up (the standard team collaboration queue). Use this as your starting point for both auto-agent workflows and manual review sessions.
Inputs: mode, projectId, mentionedUser.
get_annotationsA
Retrieve annotation pins from the .feedback/ directory. Filter by page URL, LWC component name, or status. Use this to understand what feedback exists before making changes.
Inputs: status, pageUrl, componentName.
get_component_feedbackA
Get all feedback pins targeting a specific LWC component, with a plain-language summary ready for implementation. Returns element selectors, comments, and thread history.
Inputs: componentName (required).
get_feedback_summaryA
Get a high-level rollup of all open feedback: counts by status, page, and component. Use this to plan what to address first.
Inputs: no named parameters.
get_implementation_packetA
Get a single implementation packet for one page URL. Useful when you want to batch-fix one page at a time. Returns the same shape as a single entry in implement_approved_pins.packets — pins, aggregated selectors, suggested branch, traceability config. Matches by exact URL or partial substring.
Inputs: pageUrl (required), projectId.
get_pending_critiquesA
Used by /critique-latest-deploy. Lists pending critique requests queued by the deploy-hook for the current license. Returns request id + page URLs + deploy hash. Newest-first. Free on all plans (the gating happened at enqueue time on the deploy-hook side: only Pro/Team licenses produce queue entries).
Inputs: projectId.
get_project_contextA
Read-only lookup of a project's context (name, URLs, brand context, autoCritique flag, traceability settings). Use this whenever you only need to inspect — never mutates, never touches the network. The Pincushion AI critic subagent calls this before generating any pin, since configure_project would otherwise upsert the project, sync to cloud, and create a deploy hook on a typo'd project name. Pass projectId for an exact lookup, name to look up by display name, or no arguments to list all projects in this workspace.
Inputs: name, projectId.
get_reply_candidatesA
Used by /pincushion-replies. Returns pins where Pincushion AI should respond, with each candidate tagged by trigger reason. Two triggers: (a) "mention" — the latest thread message contains @pincushion AND was authored by a human; (b) "reply-on-bot-pin" — the pin was originally authored by Pincushion AI and the latest message is from a human. Skips resolved/archived pins and any pin where the latest message is already bot-authored (idempotency). Newest-first ordering so the slash command can pace replies.
Inputs: projectId.
get_selected_pinsA
Get pins that the developer has selected for implementation from the dashboard or PINS.md checkboxes. Returns the selected pin IDs with full context (element, thread, deep link). Use this to know which pins the developer wants you to work on next.
Inputs: no named parameters.
get_setup_instructionsA
Get instructions for setting up and connecting the PinCushion browser extension to this MCP server. Includes configuration examples for Cursor, Claude Desktop, Claude Code, VS Code, Windsurf, and other agents.
Inputs: no named parameters.
get_time_to_fix_metricsA
Compute median + p25/p75 time-to-fix from resolved pins. Returns sample size + threshold flag so callers can honestly hide the metric when the dataset is too small (< 5 resolved pins). This is the marketing proof point that distinguishes Pincushion from "manage feedback" tools — agent-native means fast.
Inputs: scope, projectId.
implement_approved_pinsA
CALL THIS FIRST when approved pins exist. Returns all stakeholder-approved pins grouped into implementation packets by page URL, each containing aggregated CSS selectors, full comment threads, and a suggested git branch name. One packet = one branch / one PR. Use the selectors to grep the source code, read the thread to understand what the stakeholder wants, then implement the fix. Workflow: implement_approved_pins → claim_pin → code change → fix_and_resolve. The result exposes both packets (canonical) and pages (alias).
Inputs: projectId.
link_pin_deployA
Link a deploy URL to a resolved pin. Typically called by the deploy-hook edge function once a deploy that includes the pin's fix goes live. Stakeholders see the deploy URL on the resolved pin in the dashboard. Re-runs overwrite the previous deploy URL (latest deploy wins).
Inputs: deployUrl (required), annotationId (required), deployedAt.
list_collaboration_integrationsA
List Slack and Microsoft Teams webhook subscriptions for a Pincushion project. Webhook URLs are masked.
Inputs: projectId (required).
list_membersA
List all members of a PinCushion project with their roles, plus seat usage info.
Inputs: projectId (required).
preview_collaboration_notificationA
Preview the Slack/Teams notification shape and recommended event routing before connecting a real webhook.
Inputs: event, provider.
record_pin_verificationA
Record the outcome of Pincushion AI's post-deploy verification on a resolved pin. Called by the critic subagent after running auto-critique on a fresh deploy. Lets stakeholders see "Pincushion AI verified this fix" (or regressed/inconclusive) directly on the pin in the dashboard, closing the "did my feedback actually ship correctly?" loop.
Inputs: status (required), annotationId (required), notes, verifiedAt.
remove_collaboration_integrationB
Remove a Slack or Microsoft Teams webhook subscription from a Pincushion project.
Inputs: projectId (required), name, provider, integrationId.
remove_memberA
Remove a collaborator from a PinCushion project. Frees up the seat if they were an editor.
Inputs: email (required), projectId (required).
resolve_annotationA
Mark an annotation as resolved after addressing the feedback. Optionally add a resolution comment explaining what was changed.
Inputs: annotationId (required), comment, resolvedBy.
search_annotationsA
Full-text search across all annotation comments, selectors, component names, and tags.
Inputs: query (required).
set_slack_preferencesA
Read or update the caller's Slack DM preferences. Resolves the user via license_key → email, then applies the change across every Slack workspace the email is linked to. Call with no args to see current state. Call with mute: "1h" (or "today", "forever", "off") to silence DMs for a window. Call with eventNewPin: false (or any event_* flag) to toggle individual event types off. Same surface as the App Home toggles and /pincushion mute, accessible from the agent — useful for "mute pin DMs during this refactor" workflows.
Inputs: mute, timezone, digestMode, mutedUntil, +7 more.
update_critique_contextA
Lightweight write-only path for the layered critique-context system. Use this from /setup and /refresh-brand after the dev agent has gathered repo signals (README, theme tokens, sample copy, competitor URLs, recent resolved pins) and compiled them into a critique brief. Unlike configure_project, this does NOT create a deploy hook, sync members, or validate URLs — it just persists the compiled brief (+ signals + policy) and pushes to cloud. Identify the project by projectId or name. The compiled critiqueContext is what the AI critic actually reads at pin time; critiqueSignals + critiquePolicy are inputs retained for traceability and the next recompile.
Inputs: name, projectId, critiquePolicy, critiqueContext, +1 more.
upload_page_snapshotA
Upload a full-page screenshot that turns the public share report into an annotated page: viewers see the real page with numbered pin markers at true positions and click-to-open thread bubbles. Capture the page yourself (kill animations, scroll to force lazy loads, full-page shot, JPEG/WebP ≤5MB), resolve each open pin's element.selector to document-pixel coordinates IN THAT CAPTURE, and pass them as pinPositions. Owner/editor only. One snapshot per (project, page) — re-upload replaces it. pageUrl must match the pins' page_url verbatim.
Inputs: width (required), height (required), pageUrl (required), projectId (required), +4 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 39 tools
Each tool has a clearly distinct purpose with detailed descriptions. Even closely related tools (e.g., get_actionable_pins vs get_selected_pins, implement_approved_pins vs get_implementation_packet) are well differentiated by their specific use cases and triggers, minimizing the risk of misselection.
All tool names follow a consistent verb_noun or verb_adjective_noun pattern in snake_case. Verbs like 'get', 'create', 'add', 'remove', 'list', 'configure', 'claim', 'resolve', etc., are used predictably, making the naming intuitive and easy to parse.
With 39 tools, the count is high but justifiable given the breadth of functionality (project setup, member management, pin lifecycle, collaboration integrations, critique, metrics, sharing, etc.). Each tool serves a clear purpose, though some niche tools (e.g., claim_pending_slack_install) could potentially be consolidated.
The tool set covers the full feedback management lifecycle: project configuration, context retrieval, pin creation/state management (claim, assign, approve, resolve, verify), replies, search, reporting, collaboration integrations, metrics, and setup instructions. No obvious dead ends or missing essential operations for the domain.
Maintenance
Related MCP Connectors
Visual website feedback your coding agent applies: pin change requests on the live site over MCP.
Client feedback pinned on websites, with screenshots and errors, for coding agents to fix.
Website feedback for your coding agent: comments pinned to the exact element, with its code.
Visual feedback from your website's visitors as tasks for your coding agent.
Related MCP Servers
- FlicenseNot gradedqualityCmaintenanceHuman-to-AI code review bridge. Annotate UI elements in the browser with review comments, and AI agents read the feedback via MCP to fix code automatically — with full element context (CSS selector, styles, DOM path, accessibility info). 10 MCP tools, framework-agnostic Web Component, zero-config install via uvx.9-
- AlicenseNot gradedqualityDmaintenanceMCP server for visual feedback, video direction, and QA assertions on web pages, enabling AI agents to read, reply, and resolve annotations in real time.6MIT
- AlicenseAqualityCmaintenanceInteractive feedback layer that lets users pin comments on live web apps with auto-captured context (failing requests, console, AI metadata), and coding agents fix issues via MCP, turning pins green upon verification.1073 npmMIT
- AlicenseNot gradedqualityCmaintenanceEnables AI coding agents to pull, triage, and resolve user feedback pinned directly on live web prototypes via MCP tools.20 npm3MIT