Skip to content
LaunchHelm
Documentation — MCP

MCP

The service exposes a Model Context Protocol endpoint at https://launchhelm.com/mcp for agent clients (Claude Code, Cursor, etc.).

Authentication

Two ways in — pick the one your client supports:

  • OAuth (sign-in flow). Clients that support the MCP authorization spec discover everything they need from the endpoint itself: they register dynamically, open your browser to a LaunchHelm consent page, and receive a token scoped to the choices you make there. No keys to copy. Connected apps appear under Settings → API keys and can be disconnected any time.
  • API key. Clients that only take a static header use a user API key minted under Settings → API keys. The worker credential an SDK derives for its session doesn't work, and neither does a browser session.

Access levels:

  • Read only lets the agent browse projects, runs, metrics, activity, and controls history, but change nothing. Good default for analysis.
  • Full access lets the agent do anything you can in that scope — required for submitting controls, approving alert actions, running workflows, and investigations.

Either can be limited to one project. API keys are shown once; OAuth connections ask for the level and project on the consent page. Consent can narrow what the client asked for — a client requesting Full access can be granted Read only — but never widen it.

Connecting with OAuth

Add the server to an OAuth-capable MCP client with just the URL:

claude mcp add --transport http launchhelm https://launchhelm.com/mcp

The first connection opens a browser: sign in, pick the organization, the access level, and optionally one project. The client then holds a short-lived token it refreshes itself — nothing else to manage.

For native clients (RFC 8252), a registered loopback redirect URI (http://localhost, http://127.0.0.1, http://[::1]) matches any port at authorization time, so a client may pick a fresh port for each sign-in; the path and query must still match. When authorization fails — an unsupported response_type, an invalid scope, bad PKCE parameters — the error returns to the client's redirect URI as error, error_description, and state query parameters instead of an in-page JSON error.

What agents see

Every connection can describe itself: launchhelm.get_context returns the organization and project the credential can access, the access level (full, read, or custom), and its actions. Agents should call it first.

organization_id is optional on every other tool: it defaults to the organization the API key or OAuth connection belongs to, which is the only organization a credential can reach anyway. If a key's access does not resolve to a single organization, tools report organization_id is required for this key instead of guessing.

Expired or invalid tokens are answered with a WWW-Authenticate: Bearer … error="invalid_token" challenge. OAuth clients refresh the token and, if the connection was revoked, run the sign-in flow again.

Connecting with an API key

For clients that need a static credential, send the key in an Authorization: Bearer header:

claude mcp add --transport http launchhelm https://launchhelm.com/mcp \
  --header "Authorization: Bearer <user-api-key>"

Scoping and revocation

Both credentials act as you — anything the app lets your account do in that scope, the endpoint permits. API keys live in the client's credential store, not shell history or committed dotfiles. OAuth tokens are bound to this endpoint and are refused anywhere else; the connection dies immediately when you disconnect it under Settings → API keys → Connected apps, or when the client's refresh window (30 days idle) runs out.