Skip to main content

​
Common Issues

  • OAuth clients: reconnect so the client can refresh or replace its OAuth access token
  • Manual-key clients: verify the key starts with omi_mcp_
  • Check that the header uses the Bearer prefix: Bearer omi_mcp_...
  • Generate a new key from the macOS connection card’s Manual installation section, or from Settings → Developer Settings → MCP Server → API Keys in the cross-platform app
  • Ensure the OAuth grant or MCP key has not been revoked
An omi_mcp_... key authenticates the MCP endpoints only. Two things follow:
  • Use the /v1/mcp/ REST endpoints — e.g. GET /v1/mcp/memories, GET /v1/mcp/memories/search?query=..., GET /v1/mcp/conversations, GET /v1/mcp/action-items. They accept the same key as the MCP server and return plain JSON.
  • /v1/memories and /v2/memories do not exist. Requests to them return 404 Not Found regardless of the key.
To call the Developer API (/v1/dev/...) instead, create a separate key in Settings → Developer Settings → Developer API Keys; it starts with omi_dev_. Using either key on the other’s endpoints returns a 401 that names the endpoints that key does authenticate.
  • Send an initialize request first — tools are only available after initialization
  • Check that your client supports the Streamable HTTP transport (2025-03-26)
  • Try the /v1/mcp/sse/info endpoint to verify the server is reachable:
  • Semantic search requires conversations/memories to be indexed in the vector database
  • New data may take a few minutes to be indexed after creation
  • Try broader queries — very specific queries may not match if phrased differently than the original
  • Use get_memories or get_conversations with filters as a fallback
  • The MCP server has per-user rate limits to prevent abuse
  • Wait a moment and retry
  • Reduce the frequency of tool calls in automated workflows
  • Some memories and conversations are behind the paid plan
  • Upgrade your plan to access all content
  • Locked memories still appear in list/search results with truncated content

​
Debugging Tools

Use the MCP inspector to test tools interactively:
For local development:

​
Need Help?

Discord Community

Get help from the community and team

GitHub Issues

Report bugs or request features