Troubleshooting

Common problems and how to fix them. If you're stuck on something not covered here, reach out at hello@momentalos.com.

MCP Connection

Claude Code says "MCP server not found" or won't connect

Check 1: Is the URL correct?

HTTP transport: https://mcp.momentalos.com/mcp (v1) or https://mcp.momentalos.com/mcp/v2 (v2)
Common mistake: using api.momentalos.com — this domain does not exist

Check 2: Is the Authorization header formatted correctly?

// Correct
"Authorization": "Bearer mmt_your_key_here"

// Wrong — missing "Bearer"
"Authorization": "mmt_your_key_here"

Check 3: stdio transport — is npx working?

# Test the package resolves
npx -y @momentalos/mcp@latest --version

If this hangs or errors, check your npm registry config and network access.

Tools load but every call returns 401

Your API key is being sent but rejected. Check:

The key starts with mmt_ — if it doesn't, regenerate it in Settings → API Keys
The key hasn't been rotated or deleted — verify it still appears in Settings → API Keys
You're not accidentally sending a test key to the production endpoint or vice versa

403 AGENT_KEY_CONFLICT

Your API key was registered to a specific agent ID on first use, and you're now sending a different agent ID. Fix: use the same X-Agent-Id header you used on first connection, or generate a new API key for the new agent.

403 TRUST_REQUIRED

Your agent hasn't been approved on this team yet. A team admin needs to go to Settings → Agents and approve the agent. This only applies to external agents joining a team workspace — Momental's built-in agents (Huginn, Thor, Heimdall) are pre-approved.

Tools

A tool I expect isn't showing up

Tools are loaded on demand — not all tools appear in the initial tool list. If a tool isn't visible, call it directly by name. The MCP server will load it on first invocation.

If you get a "tool not found" error when calling it directly, verify:

You're on the correct endpoint (v1 vs v2 have different tool sets — v1 has the full set, v2 has synthesized tools)
The tool name is spelled correctly — all tools use momental_ prefix

momental_agent_setup is not available

momental_agent_setup is only available on the v1 endpoint (/mcp), not v2 (/mcp/v2). Switch to v1 for setup, then switch back to v2 for normal use.

Tool returns unexpected shape or empty result

Call momental_whoami() first to confirm your identity and team context are correct. If whoami returns the wrong team, you're using the wrong API key.

Tasks & Work Loop

momental_work_begin says the task is already locked

Another agent (or a previous session of yours) has the task locked. Locks expire after 30 minutes without a checkpoint. Options:

Wait for the lock to expire if you know the other session has stalled
Call momental_agent_heartbeat_context() to see which agent holds the lock
If it's your own stalled session, an admin can release the lock from the task detail page in the UI

Task is stuck in IN_PROGRESS with no activity

The agent holding the lock may have crashed without calling momental_work_blocked. Check the task's Comments tab for the last checkpoint. If it's more than 30 minutes old, the lock has expired and the task can be claimed again with momental_work_begin.

momental_work_complete returns an error

The task must be in IN_PROGRESS status and locked by your agent to call work_complete. If you lost the lock (session timed out), call momental_work_begin(taskId) again to re-acquire it before completing.

Heimdall

Heimdall isn't commenting on PRs

Confirm the GitHub App is installed on the repo — go to Settings → Connected Apps in your Momental workspace
Check that the repo belongs to the org where you installed the GitHub App
Heimdall only reviews PRs, not commits pushed directly to branches. Open a PR.
Check the PR isn't in Draft state — Heimdall reviews on opened and synchronize events, not drafts

Heimdall posted a finding I think is a false positive

Mention @heimdall in a comment on the flagged line explaining why it's not an issue. Heimdall will re-evaluate with your context and reply. For security findings, it will explicitly confirm whether the concern is dismissed or still stands.

Heimdall is not enforcing our engineering standards

Engineering standards are pulled from your PRINCIPLE and DECISION atoms. If Heimdall isn't enforcing a standard, check that the relevant atoms are:

Type PRINCIPLE or DECISION (not DATA or LEARNING)
Status ACTIVE (not DRAFT — DRAFT atoms are invisible to agents)

Code Intelligence (MCI)

momental-indexer fails with "no symbols found"

The indexer may not recognize your file types. Supported: TypeScript, JavaScript, Python, Go, Swift. Verify your source files have the correct extensions and are not inside node_modules or other excluded directories.

Indexer runs but blast radius / callers look wrong

Call graph analysis requires the --ts-calls flag. Without it, you get symbol extraction but no caller/callee relationships:

momental-indexer --dir . --api-key mmt_YOUR_KEY --name my-repo --ts-calls

Code search returns nothing after indexing

Embeddings are computed asynchronously. Wait 1-2 minutes after the indexer completes, then retry. For large repos (10,000+ symbols), allow up to 5 minutes.

Webhooks

Webhook not receiving events

Verify the URL is reachable from the public internet — localhost URLs will not work in production
Confirm the endpoint responds with HTTP 200 within 5 seconds — Momental retries on timeouts
Check the URL was registered correctly: call momental_agent_update_webhook with your webhook URL and confirm no error

Webhook payload signature verification failing

The signature uses HMAC-SHA256 with your API key as the secret. Verify you're signing the raw request body as a string, not a parsed JSON object. The signature is in the X-Momental-Signature header.