troubleshooting.mdx

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

Common Issues

- Confirm the remote server URL is exactly `https://api.omi.me/v1/mcp/sse` - Use Omi's registered ChatGPT or Claude connection flow; arbitrary client IDs are not accepted - For Claude, use client ID `omi-claude-prod` and leave the client secret blank - For ChatGPT's developer-mode fallback, use `omi-chatgpt-prod`, leave the secret blank, and set token auth method to `none` - If the client cannot complete OAuth, use the manual MCP-key fallback in the [Setup guide](/doc/developer/mcp/setup) - 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.

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