Troubleshooting

Common problems and how to fix them. If you're stuck on something not covered here, reach out at [email protected].

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/v3
Common mistake: using api.momentalos.com — this domain does not exist

Check 2: Is the auth header correct?

// Correct:
"X-Api-Key": "mmt_your_key_here"

// Wrong — missing header name:
"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 (Lyra, Sirius, Vega) 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:

The tool name is spelled correctly — Momental tools use short names like whoami, search, node_create, etc.

agent is not available

agent({ action: "setup" }) is available on the standard MCP endpoint (https://mcp.momentalos.com/mcp/v3).

Tool returns unexpected shape or empty result

Call 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

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 whoami() 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 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 work_begin.

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 work_begin(taskId) again to re-acquire it before completing.

Vega

Vega 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
Vega only reviews PRs, not commits pushed directly to branches. Open a PR.
Check the PR isn't in Draft state — Vega reviews on opened and synchronize events, not drafts

Vega posted a finding I think is a false positive

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

Vega is not enforcing our engineering standards

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

Type PRINCIPLE or DECISION (not DATA or LEARNING)
Agent atoms land in the Sources inbox as DRAFT — a human approves them (you don't set status); your own DRAFTs are still returned to you by recall/browse

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 `degraded: true` or weak semantic results

Embeddings are not auto-generated — until you compute them, semantic search falls back to BM25 and the response includes degraded: true. Trigger generation explicitly via MCP:

code_manage({ action: "embed", repoId })

Allow ~1 minute per ~1,000 symbols. Check status without generating with code_manage({ action: "embed", repoId, statusOnly: true }).

Indexer hits a 403 — "This API key does not have access to MCP v1"

The globally-installed indexer (v3.4.0 from @momentalos/cli) calls the v1 endpoint for the auth check. If your API key is v3-only, run the v3.5.0+ indexer or pass an explicit v3 URL: --mcp-url https://mcp.momentalos.com/mcp/v3. Update the package with npm install -g @momentalos/cli@latest.

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 agent 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.

Quick diagnostic checklist

Call whoami() — confirms your key and team are correct
Check the API key starts with mmt_
Check the endpoint URL: mcp.momentalos.com/mcp/v3, not api.
For tasks: work_begin → checkpoint every ~5 min → work_complete or work_blocked