Skip to content

API keys & scopes

API keys authenticate every request to the Ritual MCP server. Keys are scoped and respect workspace access.

Create a key

  1. Open Integrations — or click your profile avatar (top-right) and choose Integrations.
  2. Select the Developer tab. The Connected apps and Browse catalog tabs are for other integrations.
  3. Under Ritual as an MCP server, click Create API Key.
  4. Pick a scope (start with read).
  5. Copy the key immediately — it is not shown again. Keys start with rtl_.
  6. In MCP Server Configuration, copy the Endpoint field. That URL is tied to your Ritual environment; for the standard production service it matches https://mcp.ritual.technology/mcp.

Scopes

ScopeToolsUse when
readDiscovery, exploration metadata, requirement packages, planning, recommendationsDefault for editor integrations and read-only agents.
read_writeEverything in read plus mutating toolsRequired for agents that create or update Ritual state.

Pick the narrowest scope that does the job. You can always create a new key with broader scope later.

Rate limits

The server enforces per-minute and per-day rate limits that depend on key scope. Invalid or missing keys are rejected immediately.

Rotate or revoke

In the Developer tab, revoke the existing key, then create a new one and update your client config. In-flight requests using the old key start failing immediately, so plan rotations during low-traffic windows.

Storage

Treat keys like passwords:

  • Don’t commit them to git. Use .mcp.json in the project root only if your team is comfortable sharing the key, or scope the config to user level (~/.claude.json) and keep keys in a secret manager.
  • Don’t paste keys into chat, screenshots, or shared documents.
  • If a key leaks, revoke it before doing anything else.