MemQ Troubleshooting — Common Issues & Fixes

Troubleshooting

Common issues and how to fix them.

Agent discovery checks

Symptom

An automated agent or scanner cannot discover how to connect to MemQ, even though manual MCP config works.

Fixes

Confirm the homepage returns RFC 8288 Link headers advertising rel="api-catalog", rel="service-desc", and rel="service-doc".
Confirm /.well-known/api-catalog returns an application/linkset+json response with MemQ service descriptions, docs, status, and protected-resource metadata.
Confirm /.well-known/oauth-protected-resource points to Billing Manager as the authorization server for the MemQ protected resource.
Confirm /.well-known/mcp/server-card.json lists the Streamable HTTP endpoint, supported scopes, and tool capability summary.

Discovery probe

curl -I https://multinex.ai/
curl -I https://multinex.ai/memq/
curl -L https://multinex.ai/.well-known/api-catalog
curl -L https://multinex.ai/.well-known/oauth-authorization-server
curl -L https://multinex.ai/.well-known/oauth-protected-resource
curl -L https://multinex.ai/.well-known/mcp/server-card.json

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 the discovery document at https://multinex.ai/.well-known/oauth-authorization-server. It should advertise the Billing Manager authorization endpoint, token endpoint, JWKS URI, and memq.mcp scope.
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 from your authenticated client.

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 or inactive accounts may not have private memory enabled yet. Start checkout or add a valid MemQ API key to activate private memory.
Contributor supports one private namespace. If you need multiple, upgrade to Pro.
Team namespaces are managed through your organization dashboard. Confirm the API key belongs to the right account or organization.

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. Usage and meters
memory_status

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