troubleshooting.mdx

title	Troubleshooting
icon	bug
description	Debug and fix common MCP connection issues

Common Issues

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

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

To call the [Developer API](/doc/developer/api/overview) (`/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.

- 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: ```bash curl https://api.omi.me/v1/mcp/sse/info ``` - 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:

```bash
npx @modelcontextprotocol/inspector uvx mcp-server-omi
```

For local development:

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

Test the server directly:

```bash
# 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:

```bash
# 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?

Get help from the community and team Report bugs or request features