Connect Claude Code to ops-mcp

This guide walks an Ordermatic engineer through connecting Claude Code to the ops-mcp Cloudflare Worker so AI sessions can call our customer-ops tools.

Prerequisites

Ordermatic Clerk account with membership in at least one organization
Claude Code installed and updated (DCR is required; older versions error with “Incompatible auth server: does not support dynamic client registration”)
A modern desktop browser as $BROWSER (Mac Safari/Chrome, Windows Chrome/Edge, Linux Firefox/Chrome)
Not supported in v1: SSH/headless, WSL without a browser bridge. Request a break-glass service token if you need this.

One-time setup

claude mcp add --transport http ops-mcp https://ops-mcp.ordermatic.co/mcp

Or for staging:

claude mcp add --transport http ops-mcp-staging https://ops-mcp-staging.ordermatic.co/mcp

What you’ll see:

Terminal: Connecting to ops-mcp…
Browser opens to https://app.ordermatic.co/oauth/authorize?...
If you’re already signed into Clerk: skip to step 5
Clerk sign-in page → sign in
If you’re a member of multiple orgs: org picker page → choose one
Browser shows “Connected — return to Claude Code”
Terminal: Connected to ops-mcp

You should see this complete in 8-25 seconds on a Mac with an active Clerk session, or 30-90 seconds if SSO redirect is involved.

What you can now do

Inside any Claude Code session, the model can call ops-mcp tools:

> List failed emails for the last 24h
[Claude Code calls list_failed_emails via ops-mcp]

> Send the order-received email for order abc-123
[Claude Code calls send_order_received_email with mcp:write scope]

See the INTEGRATION.md tools list for the full surface.

Switching orgs

Sessions are bound to ONE org at issuance time. To act on a different org:

Option A — Re-authenticate with a different org:

claude mcp remove ops-mcp
claude mcp add --transport http ops-mcp https://ops-mcp.ordermatic.co/mcp
# choose a different org on the picker page

Option B — Add a parallel entry:

claude mcp add --transport http ops-mcp-genfit https://ops-mcp.ordermatic.co/mcp
# choose Genfit on the picker page

Both work. Option B lets you keep multiple connections alive simultaneously.

Read vs write scope

By default, the org picker page grants mcp:read mcp:write. If you want to be extra-safe, uncheck “Grant write access” to get a read-only token.

If you need to upgrade later: claude mcp remove ops-mcp && claude mcp add ... and grant write.

Top 5 issues

1. Browser doesn’t open

Most common on remote SSH sessions or headless terminals. Claude Code needs a local browser to receive the OAuth callback.

Fix: Run from a desktop terminal. Or request a break-glass service token from platform-eng for ~24h of CLI access while you sort out the desktop side.

2. “Incompatible auth server: does not support dynamic client registration”

You’re on an old Claude Code. Upgrade and retry.

3. Org picker shows wrong orgs

You’re signed in as the wrong Clerk user, or your org memberships changed recently and Clerk’s cache hasn’t refreshed.

Fix: Sign out of Clerk in the browser, retry claude mcp add.

4. `403 insufficient_scope`

Your token is read-only and you called a write tool.

Fix: Re-auth with write access (see “Read vs write scope” above).

5. `401 token_revoked` mid-session

Someone revoked the session (you, an admin, or Clerk because your org membership changed).

Fix: Run claude mcp remove ops-mcp && claude mcp add ... to start fresh.

Verify connectivity without setting up Claude Code

pnpm mcp:doctor                      # probe /health + metadata
pnpm mcp:doctor --token <your-token> # probe /mcp tools/list

This is the fastest way to confirm the server is up and you have a valid token before debugging Claude Code config.