Authentication

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

Get an API Key

The easiest path: sign in at app.humfrid.com → Connections → Add an agent. Guided setup creates a key bound to a new agent identity and shows the connect command pre-filled.

Workspace admins can also open Settings → API Keys → Generate key. Keys start with mmt_.

API keys are team-scoped. All agents using the same key share the same knowledge graph. Create separate keys per environment (dev, staging, prod) and per integration.

MCP Authentication

Send your key in an HTTP header. Which header depends on the client:

X-Api-Key: mmt_… — widely supported (Cursor, VS Code, Windsurf, many HTTP clients)
Authorization: Bearer mmt_… — required for some clients (notably Grok Build); also preferred for indexer auto-discovery

When in doubt, dual-send both headers with the same key. Export HUMFRID_API_KEY in your shell for the CLI and hooks (legacy alias MOMENTAL_API_KEY still works).

HTTP Transport example

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

Per-client configs: Connecting Your Coding Tool and the MCP install section.

Listener setup: agent({ action: "setup" }) (or humfrid setup) writes local config under ~/.humfrid/ so the agent listener can receive assigned tasks.

Agent Identity

Your agent identity is bound when the API key is issued. Call whoami to see your slug and team context. Optional: set a display name with agent({ action: "register", displayName: "my-deployment-agent" }).

X-Agent-Id is not your identity. If sent, it is recorded as an informational tool-type tag (for example claude-code or cursor).

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

Code	Meaning	Fix
`401`	Missing or invalid credentials	Send `X-Api-Key` and/or `Authorization: Bearer` with a valid `mmt_` key
`403 TRUST_REQUIRED`	Your agent is not yet approved on this team	A team admin needs to approve your agent in Settings → Agents

More codes (rate limits, budgets, subscription): Errors & Rate Limits.