Back to Docs

MCP Setup

Connect Simple Product to your AI coding assistant using the Model Context Protocol (MCP). Access boards, docs, customers, and feedback without leaving your editor.

Quick Install (CLI — all desktop tools)

One command. Detects and configures Claude Code, Claude Desktop, Cursor, Windsurf, and VS Code on this machine:

npx @simple-product/mcp --install

Opens your browser once for sign-in, then writes the right config to each tool it finds. No editing JSON yourself.

Custom Connector (Claude on web + mobile)

The CLI installer above is local-only — it can't reach Claude on mobile or the web app. To use Simple Product from claude.ai or the Claude mobile apps, add it as an account-level Custom Connector:

1. Copy the connector URL

https://simpleproduct.dev/api/mcp/v1

2. Open the Add Connector modal in Claude and paste the URL

Add in Claude →

Requires Claude Pro or Max. Once added, Simple Product appears in Claude on every surface you're signed into — Desktop, web, iOS, Android. Safe to use this alongside the CLI install above; both hit the same backend.

Supported Tools

Claude Code

Anthropic's CLI coding assistant

Claude Desktop

Claude's desktop application

Cursor

AI-powered code editor

Windsurf

Codeium's AI IDE

VS Code

With MCP extension

Manual Setup

Claude Code

Run this command to add Simple Product to Claude Code:

claude mcp add --transport stdio simple-product -- npx @simple-product/mcp@latest

For global installation (all projects), add --scope user (must come before the server name).

Claude Desktop

Add this to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{ "mcpServers": { "simple-product": { "command": "npx", "args": ["@simple-product/mcp@latest"] } } }

Cursor

Add to ~/.cursor/mcp.json:

{ "mcpServers": { "simple-product": { "command": "npx", "args": ["@simple-product/mcp@latest"] } } }

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{ "mcpServers": { "simple-product": { "command": "npx", "args": ["@simple-product/mcp@latest"] } } }

VS Code

VS Code has native MCP support. Add Simple Product to your workspace at .vscode/mcp.json:

{ "servers": { "simple-product": { "command": "npx", "args": ["@simple-product/mcp@latest"] } } }

Note the root key is servers here, not mcpServers — VS Code silently rejects configs with the wrong key.

Other MCP-compatible tools

Any tool that speaks the standard Model Context Protocol can run Simple Product. Find the tool's MCP config file (often named mcp.json, mcp_config.json, or living inside the app's settings JSON) and add this entry:

{ "mcpServers": { "simple-product": { "command": "npx", "args": ["@simple-product/mcp@latest"] } } }

Requires Node.js 18+ on the path. The first time the bridge runs, it'll open your browser to sign you in; credentials are then stored at ~/.simple-product/config.json.

Authentication

Two ways to auth. Pick whichever fits your setup.

OAuth (default — best for interactive tools)

On first run, the MCP server signs you in through your browser:

  1. A browser tab opens to sign in to Simple Product
  2. Approve the connection on the consent screen
  3. The tab closes and the server connects to your workspace

Credentials are stored at ~/.simple-product/config.json and persist across sessions.

Session expired? The MCP handles it automatically — a browser tab opens for you to sign back in, keeping your current workspace selected. You don't need to reinstall. You can also trigger this manually with the reauth tool (ask "reauthenticate simple product") or from your terminal with npx @simple-product/mcp --reauth.

Personal token (for headless / no-browser setups)

If OAuth isn't practical — CI jobs, cron, agents running in a container, IDE plugins with no browser hand-off — create a personal API token and paste it into the MCP config directly.

  1. In the web app, go to Settings → API Keys → Personal keys
  2. Create a new key (starts with sk_usr_). Keys act as you — they can access every workspace you're a member of
  3. Pass it as a Bearer token, e.g. via the Authorization header when calling https://simpleproduct.dev/api/mcp/v1 directly, or via your MCP client's auth-token config

Personal keys don't expire (revoke them from the same screen). Skips the browser hand-off entirely — one paste and you're in.

Choosing a workspace

Every MCP tool that reads or writes workspace data takes a required workspaceSlug parameter naming which workspace to hit. Your agent picks the slug from these signals, in priority order:

1. What the user says in the prompt

"List boards in my Acme workspace" → agent passes workspaceSlug: acme. Explicit intent always wins.

2. Per-project binding via .simple-product.json

Drop a .simple-product.json file at your project root (or any ancestor up to .git) to pin that project to a specific workspace. The bridge finds it on startup and uses it as the workspace for every call. Handy for Claude Code where you work in per-repo sessions — one project, one workspace, no thinking.

3. The user's default workspace

When the user is vague and no project binding exists, the agent uses your default. The MCP server hints the default in its initialize response, so the agent knows it without a whoami round-trip. Set your default in the web app or via the switch_workspace tool ("work in Acme from now on").

Why required, not optional? No shipping MCP client provides reliable session-state routing — Claude Desktop, mobile, and web all blur sessions across chats; Claude Code discards sessions between invocations. Making workspaceSlug required means every call explicitly names its target, and a missing slug fails fast with a clear error the agent can self-correct from — never a silent wrong-workspace write.

Available Tools

Once connected, your AI assistant can use these tools. You can invoke them by name, or just ask in plain English — Claude will pick the right one.

Documents

create_docCreate a new doc. Content is markdown.
update_docUpdate a doc's title or content.
get_docRead a doc's full content by ID.
search_docsFind docs by title.

Cards

create_cardCreate a card on a board, optionally in a specific stage.
update_cardUpdate a card's title or description.
move_cardMove a card to a different stage.
search_cardsSearch cards by title or description across boards.
list_cardsList cards on a board, optionally filtered by stage.
get_cardRead a card's full details and links.

Boards

list_boardsList all boards in the workspace with their stages.
get_boardRead a board's stages.
create_boardCreate a new board with stages.

People & organizations

create_personCreate a CRM contact.
update_personUpdate a person's profile fields.
search_peopleSearch people by name or email.
create_orgCreate an organization (customer account).
update_orgUpdate an organization's profile fields.
search_orgsSearch organizations by name or domain.

Releases

create_releaseCreate a changelog release in markdown.
update_releaseUpdate a release's title or content.
get_releaseRead a release's content and publish state.
search_releasesSearch releases by title or content.
list_releasesList the most recent releases.

Feedback

create_feedbackCapture a piece of customer feedback.
update_feedbackUpdate a feedback entry's title or content.
get_feedbackRead a feedback entry's full content.
search_feedbackSearch feedback by title or content.
list_feedbackList the most recent feedback.

Comments

create_commentPost a comment on a card, doc, or feedback.

Email (Gmail)

draft_emailCreate a draft in your connected Gmail. Not sent.
send_emailSend an email from your connected Gmail. Irreversible.
list_emailsList recent emails, optionally filtered by query.
list_draftsList your current Gmail drafts.

Linking (relationships between items)

link_doc_to_cardAssociate a doc with a card.
unlink_doc_from_cardRemove a doc ↔ card link.
get_docs_for_cardList docs linked to a card.
get_cards_for_docList cards linked to a doc.
link_doc_to_docAssociate two docs.
unlink_doc_from_docRemove a doc ↔ doc link.
get_linked_docsList docs linked to a specific doc (either direction).
link_doc_to_personAssociate a doc with a person.
unlink_doc_from_personRemove a doc ↔ person link.
get_docs_for_personList docs linked to a person.
get_people_for_docList people linked to a doc.
link_card_to_personAssociate a card with a person — e.g. attach a customer's request to a card.
unlink_card_from_personRemove a card ↔ person link.
get_cards_for_personList cards linked to a person.
get_people_for_cardList people linked to a card.

Workspace & identity

whoamiReturn the authenticated user, their default workspace, and every workspace they can access — call this first for orientation.
list_workspacesList all workspaces you're a member of.
list_workspace_membersList people with login access to a workspace (your team).
switch_workspaceSet your default workspace. Doesn't route future calls by itself — those use each call's workspaceSlug — but changes which workspace is used as the fallback.
reauthRe-authenticate without reinstalling. Opens a browser and keeps your current workspace.
get_setup_guideGet code examples for integrating SP into your app (SDK, webhooks, etc.).

Search

searchUniversal search across boards, docs, people, orgs, feedback, releases.
search_chat_historySearch your past in-app AI chat conversations.

Example Usage

With the MCP connected, you can ask your AI assistant things like:

  • "What cards are in the backlog?"
  • "Create a card for implementing dark mode"
  • "Search for feedback about the login page"
  • "Show me recent customer requests"
  • "Create a release note for the new export feature"
  • "Move the authentication bug to In Progress"

Troubleshooting

MCP not showing in tool list

Restart your editor after configuration. The MCP server must be running for tools to appear.

Authentication expired

The next tool call after your session expires automatically opens a browser tab for you to sign back in. Complete the sign-in, then retry the request. Your current workspace is preserved.

If the auto-reauth doesn't fire (or you want to switch accounts), invoke the reauth tool ("reauthenticate simple product") or run npx @simple-product/mcp --reauth from your terminal.

Wrong workspace

Every workspace-scoped tool call now requires an explicit workspaceSlug — a missing one fails fast with an "expected string, received undefined" error the agent will retry with the slug included. Silent wrong-workspace routing is gone.

If your agent picks the wrong workspace, say so in the prompt: "work in my Acme workspace" or "list boards in demo." The agent uses your default when you're vague; naming the workspace overrides it.

To change the default the agent uses when you're vague, run switch_workspace (updates your account default) or drop a .simple-product.json at your project root to pin the project.

Agent says a tool doesn't accept a workspace parameter

Your MCP client has cached an older tool schema. Fix by restarting the client — Claude Desktop, Cursor, Windsurf, and similar in-memory-cache their tool defs per session, so a restart re-fetches the current schema. Re-adding the connector is only needed if a restart alone doesn't help.