Quickstart: Claude

Connect the SuprSend MCP server to Claude Code or Claude Desktop.

Not sure which one you’re using? Claude Code runs in your terminal or IDE and is invoked with the claude command. Claude Desktop is the standalone chat app downloaded from claude.ai/download. Setup is different for each — pick the matching tab below.

Claude Code

1. Install Claude Code

   Claude Code is distributed as an npm package and requires Node.js 18+.

   npm install -g @anthropic-ai/claude-code
   

   Run claude once and complete the one-time browser login it prompts.

2. Get a service token

   Go to Dashboard → Account Settings → Service Tokens and generate a token for the workspace you want to expose.

   Service tokens grant full workspace access. Store the token as an environment variable — never commit it to version control or share it via screenshot or screen recording. Rotate immediately if exposed.

3. Register the MCP server

   The SuprSend MCP server runs through the SuprSend CLI via npx — no install step, always the latest version. Requires Node.js 18+.

   Add the server with one command in your regular terminal (not inside a running claude session):

   claude mcp add suprsend \
     --scope user \
     --env SUPRSEND_SERVICE_TOKEN=your_token_here \
     -- npx -y suprsend -w staging start-mcp-server
   

   This writes the configuration to ~/.claude.json. The flags:

   • --scope user makes the server available across all your projects. Use --scope project if you want to commit an .mcp.json file for your team.
   • --env injects your token into the spawned process so it doesn’t appear in your shell history.
   • -w staging runs against your staging workspace. Switch to -w production only after you’ve confirmed everything works and scoped tools appropriately.

   Prefer a managed install over npx? Install the CLI via Homebrew, binary, or source build, then replace npx -y suprsend with suprsend in the command above.

4. Verify the connection

   From your terminal:

   claude mcp list
   

   You should see suprsend listed as connected. Then start a Claude Code session and check the tools are available:

   cd ~/any-project
   claude
   

   Inside the session, type /mcp. You should see suprsend with its tool count. Try a read-only prompt to confirm the loop works end-to-end:

   Search the SuprSend docs for how preference categories work.
   

   Claude will ask permission before the first tool call — approve it, and you’re done.

Claude Desktop

1. Install Claude Desktop

   Download Claude Desktop from claude.ai/download (available for macOS and Windows). Sign in with your Claude account.

2. Get a service token

   Go to Dashboard → Account Settings → Service Tokens and generate a token for the workspace you want to expose.

   Service tokens grant full workspace access. Store the token as an environment variable — never commit it to version control or share it via screenshot or screen recording. Rotate immediately if exposed.

3. Add the MCP configuration

   The SuprSend MCP server runs through the SuprSend CLI via npx — no install step, always the latest version. Requires Node.js 18+.

   1. Open Claude Desktop.
   2. Go to Settings → Developer.
   3. Click Edit Config under Local MCP Servers.
   4. Add the following to the JSON:

   {
     "mcpServers": {
       "suprsend": {
         "command": "npx",
         "args": ["-y", "suprsend", "-w", "staging", "start-mcp-server"],
         "env": {
           "SUPRSEND_SERVICE_TOKEN": "your_token_here"
         }
       }
     }
   }
   

   5. Save the file and fully quit and restart Claude Desktop (⌘Q on macOS, or right-click the tray icon → Quit on Windows — closing the window isn’t enough).

   Prefer a managed install over npx? Install the CLI via Homebrew, binary, or source build, then use "command": "suprsend" with "args": ["-w", "staging", "start-mcp-server"].

4. Verify the connection

   After restart, open a new conversation in Claude Desktop. Look for the tools icon (hammer) in the input area — clicking it should list SuprSend’s tools.

   Try a read-only prompt:

   Search the SuprSend docs for how preference categories work.
   

   Claude will ask permission before the first tool call. Approve it, and you’re done.

Restricting which tools Claude can access

By default the SuprSend MCP server exposes all user, object, tenant, workflow-listing, and documentation tools. Event-triggering and workflow-triggering tools are disabled by default for safety — you opt in explicitly per slug.

Scope this down further with the --tools, --workflows, and --events flags. Add them to your args (Claude Desktop) or after start-mcp-server in your claude mcp add command (Claude Code).

Docs-only mode — the safest configuration, read-only documentation lookups:

npx -y suprsend start-mcp-server --tools=documentation.*

Read-only platform access — fetch users, objects, and tenants without write capability:

npx -y suprsend start-mcp-server --tools=users.get,objects.get,tenants.get

Allow workflow triggering for specific slugs:

npx -y suprsend start-mcp-server --workflows=order-confirmed,welcome-email

See the Tool List for available identifiers.

Troubleshooting

spawn npx ENOENT on Windows

Windows doesn’t invoke npx through a shell by default. Wrap the command in cmd /c.

For Claude Desktop:

{
  "command": "cmd",
  "args": ["/c", "npx", "-y", "suprsend", "-w", "staging", "start-mcp-server"]
}

For Claude Code:

claude mcp add suprsend --scope user --env SUPRSEND_SERVICE_TOKEN=... -- cmd /c npx -y suprsend -w staging start-mcp-server

Server shows disconnected or failed

Run claude mcp get suprsend (Claude Code) to see the underlying error. Common causes:

• Wrong workspace: confirm -w staging vs -w production matches the workspace the token was generated in.
• Invalid or expired token: regenerate from the SuprSend dashboard and re-add.
• Stale npx cache after a CLI release: pin suprsend@latest in args, or clear with npx clear-npx-cache.

Tools don't appear after restart

Claude Desktop: ensure you fully quit the app (⌘Q on macOS, Quit from the tray on Windows). MCP servers only reload on a full restart — closing the window isn’t enough.

Claude Code: run /mcp inside the session to force a reconnect. If the server is still missing, run claude mcp list from your regular terminal to confirm it’s registered. If it isn’t, re-run claude mcp add.

Tool List

All available tools and how to scope them.

Prompt Cheatsheet

Ready-to-use prompts to get started fast.