The stable command surface for launch.
Pincushion exposes a hosted MCP URL for cloud-synced pins, plus a local CLI, slash-command prompts, MCP tools, and a local health endpoint for repo-aware workflows.
CLI usage
npx pincushion-mcp [--project-dir /path/to/project]
[--sync-url https://...]
[--api-key KEY]
[--license-key KEY]
[--cloud-sync]
[--rest --port 3456]--rest --port 3456 exposes a local health check and bridge for tools that cannot speak MCP directly. That localhost bridge is separate from the hosted Streamable HTTP endpoint below.
Remote MCP URL
https://pincushion.io/api/mcpThe remote endpoint uses Streamable HTTP and requires Authorization: Bearer <PINCUSHION_LICENSE_KEY>, x-license-key, or ?token=<PINCUSHION_LICENSE_KEY> for clients that only accept a URL. Run npx pincushion-mcp remote-url after login to generate that URL without hunting for the raw key. Treat tokenized URLs as secrets. It supports cloud-backed pin reads, critique pins, page snapshots, share reports, and thread/status updates. Use npx pincushion-mcp --project-dir . --cloud-sync when the agent needs local files, git history, likely-file inference, or the localhost browser bridge.
Slash commands
These are the built-in prompt surfaces shipped for MCP-aware IDEs.
| Command | Purpose |
|---|---|
| /pins | Show all open feedback pins grouped by page. |
| /my-pins @username | Filter pins where a given user has been @mentioned. |
| /resolve <pin-id> | Claim and resolve a feedback pin. |
| /feedback-summary | Return a project-wide feedback overview. |
| /setup | Register project URLs so the extension auto-activates. |
| /critique <url> | Run the IDE critic on a visible page and drop up to 3 Pincushion AI pins. A shareable annotated report is created by chaining critique pins, a page snapshot, and create_share_report. |
| /implement | Pull stakeholder-approved pins, create branches, and implement them. |
Supported MCP tools
This is the launch-ready public surface exposed by pincushion-mcp.
| Tool | Purpose |
|---|---|
| get_annotations | List feedback pins from the local .feedback directory with filters. |
| search_annotations | Full-text search across comments, selectors, component names, and tags. |
| get_feedback_summary | Roll up open feedback counts by status, page, and component. |
| get_component_feedback | Summarize feedback targeting a specific component. |
| get_actionable_pins | Return the developer queue for review, follow-up, and auto-agent modes. |
| implement_approved_pins | Fetch the stakeholder-approved work queue, grouped into implementation packets (one packet per page URL with aggregated selectors + pin count). |
| create_critique_pin | Create one Pincushion AI-authored critique pin after the client agent has inspected the page. The remote alias critique calls the same tool. |
| upload_page_snapshot | Upload the JPEG/WebP full-page screenshot and pin marker coordinates used by annotated public reports. Remote MCP clients pass imageB64. |
| create_share_report | Mint the public read-only report link at pincushion.io/r/<token>, optionally scoped to one exact page URL. |
| get_implementation_packet | Get a single implementation packet for one page URL — used to batch-fix one page at a time. |
| claim_pin | Mark an approved pin as being worked on. |
| approve_pin | Move a pin from open to approved. |
| assign_pin_to_agent | Dispatch a pin straight to your local coding agent via the .feedback/.agent-queue/ trigger file. Auto-promotes the pin to ready + marks pending_implementation. |
| fix_and_resolve, resolve_annotation | Close the loop after the fix lands. fix_and_resolve accepts optional commitSha, branchName, and prUrl so the dashboard can show "Resolved in PR #142". |
| link_pin_deploy | Link a deploy URL to a resolved pin (typically called by the deploy-hook). Stakeholders see "Deployed to <url>" on the pin. Pro/Team feature when auto-triggered by the deploy-hook. |
| record_pin_verification | Record Pincushion AI's post-deploy verdict (verified / regressed / inconclusive) on a resolved pin. Pro/Team feature when run via the deploy-triggered critique queue. |
| get_time_to_fix_metrics | Compute median + p25/p75 time-to-fix for resolved pins. Pro/Team only for the full payload — Free tier sees sample size + upgrade hint (minimum 5 pins regardless). |
| add_agent_reply | Add a thread reply without resolving the pin. |
| configure_project | Associate project URLs with the extension activation rules. |
| get_setup_instructions | Return launch-ready connection instructions for supported IDEs. |
Local health endpoint
npx pincushion-mcp --rest --port 3456
curl http://localhost:3456/healthUse the health endpoint to verify that the local bridge is alive. It is the only HTTP endpoint documented here. Tool invocation over HTTP remains an internal transport detail for MCP clients, not a public integration contract.