MCP Authentication

How the MemberPass MCP server validates incoming requests and enforces per-tool abilities.

MCP authentication piggybacks on the same Sanctum bearer tokens the REST API uses. Every request to mcp.memberpass.net must carry:

Authorization: Bearer mpt_live_<id>_<secret>

Required ability

Every MCP client must present a token carrying the mcp:full ability. Without it the server returns TOKEN_MISSING_ABILITY before any tool handler runs.

mcp:full is an opaque gate, not a write permission. Think of it as "this token is allowed to speak MCP". The real authorization lives in the per-tool ability check each tool runs on its own.

Each tool enforces one concrete ability from the catalog. A token that carries mcp:full plus project:view-any can call list_projects but will receive TOKEN_MISSING_ABILITY on list_subscribers. Grant narrowly.

Tool	Required ability
`list_projects`	`project:view-any`
`get_project`	`project:view`
`list_subscribers`	`project-user:view-any`
`list_plans`	`project-subscription-plan:view-any`
`list_access_codes`	`project-access-code:view-any`
`list_webhook_endpoints`	`webhook-endpoint:manage`
`get_activity_log`	`activity:read`

The tools reference carries the full ability mapping for every one of the 42 tools.

Team and project scope

Tokens inherit the same scope:team:<uuid> and optional scope:project:<uuid> entries the REST API uses. The MCP server runs the same tenant-resolution step, so every tool call is team-isolated exactly the same way as a REST request.

Revocation

Revoke MCP tokens from Settings → API Tokens. Revocation takes effect on the next call — there are no lingering sessions. After revocation any client still holding the token receives AUTHENTICATION_REQUIRED.

Rate limiting

Authenticated MCP calls are bucketed at 120/min per token in the mcp bucket. Hitting the limit returns RATE_LIMITED with Retry-After. Claude Desktop, Cursor, ChatGPT Desktop, and VS Code all pace their tool calls internally — exhausting this bucket in practice usually means a tight loop on the client side.

Unauthenticated traffic to the MCP host (probes, port scanners, misconfigured clients with no token attached) is bucketed separately at 5/min per IP. The tighter ceiling exists because anything reaching the server without a token is never legitimate tool use, and we want bad clients to fail fast before they consume capacity. See Rate limiting for the full bucket table.

CORS

Browser-based MCP clients (the hosted MCP Inspector, in-browser playgrounds, web extensions) issue cross-origin requests against mcp.memberpass.net. The server returns a permissive Access-Control-Allow-Origin: * so any browser origin can complete the handshake; Access-Control-Allow-Credentials is not set because we authenticate exclusively through Authorization: Bearer … and never accept cookies on this surface.

The CORS layer exposes the request/response headers a browser client needs to read:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: POST, GET, DELETE, OPTIONS
Access-Control-Allow-Headers: Authorization, Content-Type, Accept, MCP-Session-Id, MCP-Protocol-Version, Last-Event-ID
Access-Control-Expose-Headers: MCP-Session-Id, X-RateLimit-Limit, X-RateLimit-Remaining, Retry-After, WWW-Authenticate
Access-Control-Max-Age: 86400

Preflight OPTIONS requests short-circuit before authentication so a browser can complete its handshake without first owning a token. Native MCP clients (Claude Desktop, Cursor, ChatGPT Desktop, VS Code) ignore CORS entirely — these headers only matter when the caller is a browser.

Logging and auditing

Every MCP tool invocation is recorded in the activity log and is reachable through the activity:read ability (via either the REST GET /v1/activity endpoint or the get_activity_log MCP tool). Each entry identifies the invoking token so you can audit what an agent did on the creator's behalf.

REST API authentication — the same tokens, same scope entries.
Ability catalog — 65 ability strings grouped by domain.
Security model — token hygiene and threat model.