Troubleshooting

Common Issues

Connection refused or 401 Unauthorized

Verify your API key starts with omi_mcp_
Check that the Authorization header uses Bearer prefix: Bearer omi_mcp_...
Generate a new key in the Omi app: Settings → Developer → MCP
Ensure the key hasn’t been revoked

Calling the REST API with an MCP key (404 or 401)

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.

curl -H "Authorization: Bearer omi_mcp_YOUR_KEY" \
  "https://api.omi.me/v1/mcp/memories?limit=5"

To call the Developer API (/v1/dev/...) instead, create a separate key in Settings → Developer → Create Key; it starts with omi_dev_. Using either key on the other’s endpoints returns a 401 that names the endpoints that key does authenticate.

No tools showing up

Send an initialize request first — tools are only available after initialization
Check that your client supports the Streamable HTTP transport (2025-03-26 spec)
Try the /v1/mcp/sse/info endpoint to verify the server is reachable:
curl https://api.omi.me/v1/mcp/sse/info

Search returns empty results

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

Rate limit errors (429)

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

Locked content errors (-32002)

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

MCP Inspector
curl
Log Files

Use the MCP inspector to test tools interactively:

npx @modelcontextprotocol/inspector uvx mcp-server-omi

For local development:

cd path/to/servers/src/omi
npx @modelcontextprotocol/inspector uv run mcp-server-omi

Test the server directly:

# Check server info
curl https://api.omi.me/v1/mcp/sse/info

# Initialize a session
curl -X POST https://api.omi.me/v1/mcp/sse \
  -H "Authorization: Bearer omi_mcp_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'

# List tools (use the Mcp-Session-Id from the initialize response)
curl -X POST https://api.omi.me/v1/mcp/sse \
  -H "Authorization: Bearer omi_mcp_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Mcp-Session-Id: SESSION_ID_HERE" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

View Claude Desktop MCP logs:

# macOS
tail -n 20 -f ~/Library/Logs/Claude/mcp-server-omi.log

# Windows PowerShell
Get-Content "$env:APPDATA\Claude\logs\mcp-server-omi.log" -Tail 20 -Wait

Need Help?

Discord Community

Get help from the community and team

GitHub Issues

Report bugs or request features

Examples

⌘I

Getting Started

Reference

Resources

Troubleshooting

Common Issues

Debugging Tools

Need Help?

Discord Community

GitHub Issues

​Common Issues

​Debugging Tools

​Need Help?

Discord Community

GitHub Issues

Common Issues

Debugging Tools

Need Help?