MCP and OAuth API reference

CalmLens runs a remote MCP server at https://api.calmlens.com/mcp, with OAuth 2.1 sign-in, so AI assistants can work in a project for the person who approves them. Standard MCP clients discover everything here on their own; this page is for developers building a client or debugging one. To connect an existing assistant, see AI assistants.

MCP endpoint

A request without a valid key returns 401 with a WWW-Authenticate header that points at the protected resource metadata, which is how clients find the sign-in:

WWW-Authenticate: Bearer resource_metadata="https://api.calmlens.com/.well-known/oauth-protected-resource/mcp"

The server answers initialize, ping, tools/list and tools/call; notifications get 202 with no body.

Tools

Each tool runs one API endpoint with the caller's key, so the endpoint's validation, permissions and errors apply. The AI assistants guide lists the tools and their endpoints.

• Arguments. Path and query parameters are top-level arguments, named as in the API. A request body goes in body. projectId defaults to the key's project.
• Results. A tool returns the API's JSON response as text content. When the API returns an error, the result has isError: true and the error body, with its code.
• Annotations. Read-only tools set readOnlyHint and deleting tools set destructiveHint, so clients can ask before running them. Keys approved for reading only aren't offered tools that change things.

Discovery

Register a client

POST https://api.calmlens.com/oauth/register registers a public client (RFC 7591). Clients have no secret: they prove themselves with PKCE.

{
  "client_name": "My assistant",
  "redirect_uris": ["https://assistant.example/oauth/callback"]
}

The response is 201 with client_id and the registered values. Clients that never receive a key are deleted after a week; register again if yours was.

Authorize

Send the person's browser to https://calmlens.com/oauth/authorize. They sign in, see the app's name and where approving sends them, and choose a project and access.

Approval redirects to your redirect_uri with code, your state and iss (https://api.calmlens.com, RFC 9207). Declining redirects with error=access_denied.

Exchange the code

POST https://api.calmlens.com/oauth/token with a form body:

{
  "access_token": "clsk_…",
  "token_type": "Bearer",
  "scope": "read write",
  "project_id": "123e4567-e89b-42d3-a456-426614174000"
}

The access token is a project API key holding part of the approving person's access. It works as the Bearer key for /mcp and as X-Api-Key on the REST API. It has no expiry and there is no refresh token: it lasts until it's revoked, or until the person no longer holds the access they approved. A code presented a second time fails and revokes the key it issued.

The CLI signs in with the device authorization grant (RFC 8628) at POST https://api.calmlens.com/oauth/device/code, which is reserved for the CalmLens CLI; other clients get unauthorized_client.

Revoke

POST https://api.calmlens.com/oauth/revoke with a form body of token revokes that key (RFC 7009). It always returns 200, and only revokes keys issued through OAuth. People can also disconnect apps from their Portal › Profile.

Errors and limits

OAuth endpoints answer errors as { "error", "error_description" } with status 400 unless noted:

The consent page reports problems in the browser rather than redirecting: an unregistered client or redirect URI, or a resource other than CalmLens.