Multinex Docs
Troubleshooting

Troubleshooting

Common issues and how to fix them.

OAuth flow not completing

Symptom

The browser opens for approval but the connection never completes, or you get a "failed to authenticate" error.

Fixes

  • Make sure you're signing in at billing.multinex.ai, not a different auth provider. MemQ billing is separate from Anthropic, Cursor, or VS Code accounts.
  • Check that your browser isn't blocking popups from billing.multinex.ai.
  • If using Claude Desktop or an older client, try the mcp-remote bridge:
mcp-remote fallback
{
  "mcpServers": {
    "memq": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.multinex.ai/mcp/v1"]
    }
  }
}

Tools not appearing

Symptom

The connection seems to succeed but your AI doesn't see any MemQ tools, or only sees a subset.

Fixes

  • Restart your editor after adding the MCP config. Most editors require a restart to discover new MCP servers.
  • Verify the endpoint URL is exactly: https://mcp.multinex.ai/mcp/v1
  • Run reunion explicitly — this triggers the full handshake and tool discovery sequence.
  • Check health_check to verify the service and backends are reachable.

API key auth for CI / headless agents

Symptom

Your CI pipeline or background agent can't complete the OAuth flow because there's no browser.

Solution

Use an API key instead of OAuth. Generate one from your Billing Dashboard and pass it as a bearer token:

API Key config
{
  "mcpServers": {
    "memq": {
      "type": "http",
      "url": "https://mcp.multinex.ai/mcp/v1",
      "transport": "streamable-http",
      "headers": {
        "Authorization": "Bearer <YOUR_API_KEY>"
      }
    }
  }
}

Namespace permission errors

Symptom

You get "namespace not authorized" or "insufficient scope" errors when trying to read or write memories.

Fixes

  • Run namespace_info to check which tier and namespace you're connected to.
  • FREE tier only has access to _commons. Upgrade to BASE or higher for private namespaces.
  • BASE tier only supports one private namespace. If you need multiple, upgrade to VERIFIED.
  • TEAM namespaces must start with org:. Namespaces starting with user: are personal.

Full verification checklist

Run this sequence to verify everything is working end-to-end:

Verification sequence
# 1. Auth and handshake
reunion

# 2. Namespace and permissions
namespace_info

# 3. Service health
health_check

# 4. Write test
journal_record  (content: "Verification test")

# 5. Read test
journal_search  (query: "verification test")

# 6. Context packing
mnemosyne_context

# 7. Commons access
commons_resonance  (query: "test")

If all seven calls succeed, your MemQ installation is fully functional. If any fail, check the specific troubleshooting section above.