How do my customers authenticate to my MCP?

One principle: your API should know who's calling

An MCP behind a single shared token means every customer's AI calls your API as you — no data isolation, no attribution, no way to cut one customer off. CMD+K deployments are built the other way around: each customer connects with their own credential, and their calls reach your API as them. Your backend needs zero changes — requests look exactly like that customer calling your API directly.

The five modes

• Customers use their own API keys (recommended). Each customer opens your MCP's connect page and pastes the API key they already have with your product. We validate it against your API, store it encrypted per customer, and forward it on every tool call. Works with any API that supports keys — no code changes.
• Customers sign in with your OAuth. Same per-customer identity, via your OAuth server. Configure your authorize/token URLs and client ID in the Privacy tab; we run the full authorization-code flow (with PKCE) and refresh tokens automatically. A client secret is optional — see public clients below. Register our callback at your provider:
  Copy

  https://commandplusk.com/oauth/d/<slug>/callback

• Webhook Verify (your backend approves each user). The customer enters their email on your MCP's connect page; we POST an HMAC-signed JSON payload to a webhook you host, and your backend replies allow or deny. Use it when access is decided by your own records (active subscription, seat, role) rather than by a credential the customer holds. Note that in this mode tool calls reach your API with the workspace's stored setup token — the per-user identity is used for gating, attribution, scopes, and revocation, not as an upstream credential. Full details in Webhook Verify below.
• Shared access token (internal/team edge case). All callers use the workspace's stored token — your API cannot tell them apart. Only for internal tools or read-only public data. Not for customer-facing MCPs.
• No authentication. Anyone with the URL can call it (rate-limited). For demos and genuinely public data.

OAuth without a client secret (public / PKCE clients)

Only the authorize URL, token URL, and client ID are required to activate OAuth mode. The Client secret ref field is optional: leave it blank if your provider registered CMD+K as a public client. We always send a PKCE code_verifier with the authorization-code exchange, so a public client is secure without a secret. If you do store a secret (as a workspace secret referenced as workspace:NAME), we add client_secret to both the code exchange and refresh-token requests. Toward the AI client we advertise token_endpoint_auth_methods_supported: ["none", "client_secret_basic", "client_secret_post"], so public MCP clients work either way.

Webhook Verify

Webhook Verify hands the access decision to your backend. Nothing is validated against your API and no per-user credential is stored — instead, every connect attempt becomes one signed HTTP request to an endpoint you control, and your reply decides whether the user gets an MCP access token.

Dashboard fields

Open the deployment → Privacy tab → Authentication mode and choose Webhook Verify. Both fields are required before the deployment can be activated:

• Webhook URL — a public https:// endpoint that accepts POST (private/loopback hosts are rejected).
• Signing secret ref — a reference to a workspace secret in the form workspace:NAME. Store the raw secret under Workspace → Secrets; the same value is what your endpoint uses to verify signatures.

The card also shows your consent page URL:

https://commandplusk.com/mcp/d/<slug>/connect

What happens on connect

1. The customer enters their email and an optional subject (a stable user ID; when blank, the email is used as the subject).
2. We POST the signed payload below to your Webhook URL and wait up to 8 seconds.
3. On allowed: true we upsert the end user (keyed by deployment + subject), mint a Bearer token, and show it once on the consent page together with the gateway endpoint https://commandplusk.com/api/public/mcp/d/<slug>. The customer pastes both into Claude, Cursor, or any MCP client.
4. On allowed: false (or any error) the page shows your reason string — or a generic code such as webhook_status_401 — and no token is issued.

The request your endpoint receives

POST to your Webhook URL with these headers:

POST /cmdk/verify-user HTTP/1.1
content-type: application/json
x-cmdk-signature: t=<unix-ms>,v1=<hex(hmac_sha256)>
x-cmdk-event: mcp_deployment.verify_user
user-agent: CommandK-MCP-Gateway/1.0

And a JSON body with exactly these fields:

{
  "deployment_slug": "acme-crm",
  "subject": "user_123",
  "email": "jane@acme.com",
  "requested_scopes": ["read", "write"],
  "client_hint": "claude-desktop",
  "nonce": "8f1c…32 hex chars…",
  "timestamp": 1757318400123
}

• subject — what the customer typed, or their email when left blank. You can override it in your reply.
• requested_scopes — the scopes pre-configured for the connect link (may be empty). client_hint is a short free-text label of the MCP client, or null.
• nonce is a random 32-character hex string and timestamp is Unix time in milliseconds; the same value appears as t= in the signature header.

Verifying the signature

The signature is HMAC-SHA256(secret, `${timestamp}.${rawBody}`) hex-encoded — the t value, a literal dot, then the request body bytes exactly as sent (the same scheme Stripe uses, so existing webhook tooling can be reused). Verify against the raw body, not a re-serialized copy, and reject stale timestamps to prevent replays; we recommend a 5-minute window.

import { createHmac, timingSafeEqual } from "node:crypto";

// Express — use express.raw() so you verify the exact bytes we signed.
app.post("/cmdk/verify-user", express.raw({ type: "application/json" }), async (req, res) => {
  const header = req.get("x-cmdk-signature") ?? "";            // "t=<unix-ms>,v1=<hex>"
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const ts = Number(parts.t);
  if (!Number.isFinite(ts) || Math.abs(Date.now() - ts) > 5 * 60_000) {
    return res.status(401).json({ allowed: false, reason: "stale_signature" });
  }

  const rawBody = req.body.toString("utf8");
  const expected = createHmac("sha256", process.env.CMDK_WEBHOOK_SECRET)
    .update(`${ts}.${rawBody}`)
    .digest("hex");
  const a = Buffer.from(parts.v1 ?? "", "hex");
  const b = Buffer.from(expected, "hex");
  if (a.length !== b.length || !timingSafeEqual(a, b)) {
    return res.status(401).json({ allowed: false, reason: "bad_signature" });
  }

  const { subject, email, requested_scopes } = JSON.parse(rawBody);
  const user = await findUserByEmail(email);                    // your own lookup
  if (!user || !user.active) {
    return res.json({ allowed: false, reason: "No active account for this email" });
  }
  return res.json({
    allowed: true,
    subject: user.id,             // optional — stable ID instead of the email
    display_name: user.name,      // optional
    scopes: requested_scopes,     // optional — narrow or replace
    ttl_seconds: 7 * 24 * 3600,   // optional — 60 s … 30 days, default 24 h
  });
});

What to respond

Reply with HTTP 2xx and a JSON object. allowed is the only required field; everything else is optional:

• allowed (boolean, required) — grant or deny. A missing or non-boolean value is treated as a denial.
• subject (string) — replaces the subject we sent; use it to map the email to your stable user ID so revocation and analytics key off it.
• email (string | null), display_name (string | null) — stored on the end-user record shown in the Privacy tab.
• scopes (string[]) — when non-empty, replaces requested_scopes on the issued token.
• ttl_seconds (number) — lifetime of the issued token. Default 24 hours, clamped to 60 seconds – 30 days.
• reason (string) — shown to the customer on the consent page when allowed is false.

Any non-2xx status, a body that isn't JSON, or a timeout counts as a denial (the customer sees webhook_status_<code>, webhook_invalid_json, or webhook_unreachable).

What your customer sees

• They point their MCP client (Claude, Cursor, MCP Inspector) at your MCP URL. The first call answers with a link to your connect page.
• At
  Copy

  https://commandplusk.com/mcp/d/<slug>/connect

  they enter their email and their API key (or complete your OAuth flow, or — in Webhook Verify mode — wait for your backend's approval).
• We validate the credential against your API, then issue a personal MCP access token they paste into their client. From that moment, every tool call runs as them.

Using your hosted MCP as an assistant backend

The same hosted MCP can power a CMD+K assistant on your own site. In the assistant's "Connect your backend" step pick the hosted MCP; the assistant then mints a short-lived visitor JWT per signed-in user (the audience and signing secret shown on that connection) and sends it to your MCP URL. Our gateway accepts that JWT as the visitor's session — no connect page, no pasted token — and forwards it to your API as

Authorization: Bearer

Visibility and revocation

Every connected customer appears in the deployment's Privacy tab with last-seen time. Revoking a customer takes effect on their next call. Every tool call is logged with the (deployment, tool, customer) tuple — analytics, allowlists, and Monetize meters key off that identity.