> ## Documentation Index
> Fetch the complete documentation index at: https://omi-jules-remove-memory-id-4505446678251647006.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Debug and fix common MCP connection issues

## Common Issues

<AccordionGroup>
  <Accordion title="OAuth sign-in or consent does not open" icon="lock">
    * 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)
  </Accordion>

  <Accordion title="Connection refused or 401 Unauthorized" icon="lock">
    * 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
  </Accordion>

  <Accordion title="Calling the REST API with an MCP key (404 or 401)" icon="code">
    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 theme={null}
    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.
  </Accordion>

  <Accordion title="No tools showing up" icon="toolbox">
    * 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 theme={null}
      curl https://api.omi.me/v1/mcp/sse/info
      ```
  </Accordion>

  <Accordion title="Search returns empty results" icon="magnifying-glass">
    * 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
  </Accordion>

  <Accordion title="Rate limit errors (429)" icon="gauge-high">
    * 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
  </Accordion>

  <Accordion title="Locked content errors (-32002)" icon="lock">
    * 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
  </Accordion>
</AccordionGroup>

***

## Debugging Tools

<Tabs>
  <Tab title="MCP Inspector" icon="magnifying-glass">
    Use the MCP inspector to test tools interactively:

    ```bash theme={null}
    npx @modelcontextprotocol/inspector uvx mcp-server-omi
    ```

    For local development:

    ```bash theme={null}
    cd path/to/servers/src/omi
    npx @modelcontextprotocol/inspector uv run mcp-server-omi
    ```
  </Tab>

  <Tab title="curl" icon="terminal">
    Test the server directly:

    ```bash theme={null}
    # 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":{}}'
    ```
  </Tab>

  <Tab title="Log Files" icon="file-lines">
    View Claude Desktop MCP logs:

    ```bash theme={null}
    # 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
    ```
  </Tab>
</Tabs>

***

## Need Help?

<CardGroup cols={2}>
  <Card title="Discord Community" icon="discord" href="http://discord.omi.me">
    Get help from the community and team
  </Card>

  <Card title="GitHub Issues" icon="github" href="https://github.com/BasedHardware/omi/issues">
    Report bugs or request features
  </Card>
</CardGroup>