Setup and authentication.

The endpoint

All MCP clients point at the same URL:

https://api.stablebaseline.io/functions/v1/cloud-serve/mcp

Auth methods

Stable Baseline accepts two credential types. Both produce the same McpClientContext server-side, so every tool behaves identically once the bearer is validated.

Option A · API key

In the Stable Baseline web app, open Settings → MCP keys and click Generate new key. Give it a descriptive name (e.g. laptop-claude) and scope it: pick the workspaces and projects this agent should be able to touch, and tick the organisation capabilities the agent needs (see below).

Send the key as a bearer token:

Authorization: Bearer sta_••••••••••

Or use the x-api-key header if your client doesn't support custom Authorization values:

x-api-key: sta_••••••••••

Option B · OAuth 2.1

OAuth is the right choice when an end user wants to sign their agent in themselves. Stable Baseline supports Dynamic Client Registration (RFC 7591), so well-behaved MCP clients can register and start the flow without any manual configuration.

OAuth endpoints

OAuth scopes

The authorization server advertises the four standard OpenID Connect scopes below, and nothing else. They identify the signed-in user. They do not decide what an agent is allowed to do.

Authorisation is decided by two things chosen on the consent screen, neither of which is an OAuth scope. First, the read, write and delete permissions per content type (documents, plans, improvements, whiteboards) and the workspaces, projects or folders they are scoped to. Second, the organisation capability toggles in the next section, which are off by default and are never granted implicitly. The consent screen and the API-key UI share one component, so a user sees the same toggles either way.

Organisation capabilities

Both auth paths surface the same seven organisation-capability toggles when the credential is created (the OAuth consent screen and the API-key UI share one component). They're mandatory for any tool that touches the corresponding domain. Without the flag, the relevant tools return accessDenied.

Capabilities are a strict ceiling, never an expansion: effective(agent) = user_role ∩ credential_grant. Ticking a flag the underlying user's role doesn't already permit doesn't grant anything. The user's authority always wins.

The estimate-confirm-deduct ritual

Every operation that spends money or credits (subscription change, cancellation, credit purchase, KG scope change, KG rebuild, seat change) uses a two-call contract instead of executing immediately. This keeps agent-driven money and credit moves auditable and reviewable.

// 1. Preview returns a server-minted token plus a human-readable summary.
const { confirmation_token, expires_at, summary } =
  await mcp.previewSubscriptionChange({ tier: "pro", seats: 5 });

// 2. Show the summary to the user, get explicit go-ahead.
//    Then exchange the token for the actual change.
const { applied } = await mcp.applySubscriptionChange({ confirmation_token });

• Single-use, atomic consume. Replaying applyX with the same token returns token_already_consumed.
• 10-minute TTL. Long enough for an agent to round-trip with the user; short enough to bound price drift.
• Stripe idempotency. The token is passed as the Stripe idempotency key, so retries are safe.
• KG inflation cap. If the actual KG ingest cost exceeds the previewed estimate by more than 10%, the apply call aborts and re-prompts.

Verify the connection

Once configured, your client should list stable-baseline under connected servers. Ask your agent to list the tools:

What Stable Baseline MCP tools are available?

You should see 180 tools across 18 categories: signup, navigation, folders, documents, diagrams, images, whiteboards, data, improvements, plans, knowledge_graph, organization, members, teams, permissions, billing, kg_admin, settings. If the catalogue is shorter, check your credential's scope and capability flags.