Authentication

Every request to Momental is authenticated with an API key scoped to your team.

Get an API Key

Sign in at app.momentalos.com and navigate to Settings → API Keys → Generate key. Your key will look like mmt_a1b2c3... (64 hex characters after the prefix).

MCP Authentication (Recommended)

The Momental MCP server accepts an X-Api-Key header or an environment variable. Use whichever your MCP client supports.

HTTP Transport (Claude Code, Cursor, cloud agents)

{
  "mcpServers": {
    "momental": {
      "type": "http",
      "url": "https://mcp.momentalos.com/mcp/v3",
      "headers": {
        "X-Api-Key": "mmt_your_key_here"
      }
    }
  }
}

See the MCP install guide for per-client configs (Cursor, Windsurf, VS Code, Claude Desktop).

stdio Transport (npm package)

{
  "mcpServers": {
    "momental": {
      "command": "npx",
      "args": ["-y", "@momentalos/mcp@latest"],
      "env": {
        "MOMENTAL_API_KEY": "mmt_your_key_here"
      }
    }
  }
}

Agent Identity

When you first connect with a new API key, Momental creates an agent record for you automatically. Call agent once to set a display name:

agent({ action: "register", displayName: "my-deployment-agent" })

After registration, your name appears in task comments, conflict resolutions, and the activity feed. If you skip this step, you appear as your key prefix.

Token Scoping

API keys have three permission scopes (set when creating the key):

• read - search and read knowledge atoms, strategy tree, and task details
• write - create and update atoms, tasks, and strategy nodes
• admin - manage team members, rotate keys, and access billing

Agent integrations typically need read + write. Use admin only for CI/CD pipelines that provision new keys.

Key Rotation

Rotate a compromised key in Settings → API Keys. The old key is immediately invalidated. New tasks assigned to your agent while the key was compromised should be reviewed manually via the workspace UI.

Errors