> ## Documentation Index > Fetch the complete documentation index at: https://docs.omi.me/llms.txt > Use this file to discover all available pages before exploring further. # Setup > Connect your AI assistant to the Omi MCP server ## Choose a setup method Omi supports four setup paths: | Method | Authentication | Best for | | - | - | - | | Omi's guided connection | OAuth for ChatGPT and Claude; a generated MCP key for local clients | The current Omi macOS app (recommended) | | Hosted server with OAuth | Browser sign-in and consent; no key to copy | Supported cloud clients | | Hosted server with an MCP key | `Authorization: Bearer omi_mcp_...` | Clients that accept custom headers | | Local stdio server | An MCP key passed to `mcp-server-omi` | Clients that require a local process or a self-hosted backend | OAuth and MCP keys grant access to the same hosted endpoint. OAuth is the default for the new cloud-connector UI; manual MCP keys remain available as a fallback. Cleanup capabilities that hide retained data, such as `people.cleanup`, are never added to a default or legacy MCP key. They must be requested explicitly when the OAuth grant or key is created. ## Connect from the Omi macOS app (Recommended) On the Omi home screen, find **Use omi memory anywhere**, choose a destination, and follow the connection card: * **ChatGPT:** choose **ChatGPT / Codex**, then add Omi from its approved ChatGPT listing. ChatGPT opens Omi's OAuth consent flow; you do not need to create or paste a key. * **Claude:** choose **Claude / Claude Code**, then **Claude (cloud)**. Omi opens Claude's custom-connector flow with the registered public OAuth client. * **Claude Code, Codex, OpenClaw, and Hermes:** Omi generates an MCP connection key and offers guided local setup. Expand **Manual installation** to copy the server URL, key, command, or configuration yourself. * **ChatGPT custom app:** expand **Developer-mode fallback** only if your workspace cannot use the approved directory listing. OAuth grants can be reviewed or revoked from the connected client. Revoking an MCP key is separate; use the Developer settings described below. *** ## Hosted Server with OAuth Use the hosted server URL as the remote MCP URL: ```text theme={null} https://api.omi.me/v1/mcp ``` The endpoint speaks **Streamable HTTP** (MCP `2026-07-28`; older protocol versions remain supported) and advertises OAuth metadata at: ```text theme={null} https://api.omi.me/.well-known/oauth-protected-resource/v1/mcp https://api.omi.me/.well-known/oauth-authorization-server ``` `https://api.omi.me/v1/mcp/sse` is a permanent compatibility alias of the same endpoint (older configs and OAuth metadata keep working). New setups should always use the canonical `/v1/mcp` URL above. OAuth uses browser sign-in, explicit consent, authorization code + PKCE, and refresh tokens. Omi provides registered public clients for its ChatGPT and Claude setup flows. A generic MCP client that supports **Client ID Metadata Documents** can also identify itself with an HTTPS `client_id` URL (PKCE); dynamic client registration is not offered. Omitting the `scope` parameter grants all available read scopes — writes are never included by default. The preferred path is **Omi → Use omi memory anywhere → ChatGPT / Codex → ChatGPT (cloud)**. Add Omi from the directory page and approve the OAuth consent screen. For the advanced developer-mode fallback, use: * **Connection / server URL:** `https://api.omi.me/v1/mcp` * **Authentication:** OAuth * **OAuth Client ID:** `omi-chatgpt-prod` * **OAuth Client Secret:** leave blank * **Token auth method:** `none` * **Authorization URL:** `https://api.omi.me/authorize` * **Token URL:** `https://api.omi.me/token` In Claude, open **Customize → Connectors → Add custom connector**, then use: * **Name:** Omi Memory * **Remote MCP server URL:** `https://api.omi.me/v1/mcp` * **Advanced settings** (only if asked): OAuth Client ID `omi-claude-prod`, OAuth Client Secret **leave blank** Click **Add**, then **Connect**, and approve Omi's OAuth consent screen. The Omi macOS app exposes the same flow under **Use omi memory anywhere → Claude / Claude Code → Claude (cloud)**. *** ## Manual MCP-key fallback Use a manual key for clients that support a bearer header but cannot use Omi's registered OAuth flows. In the current macOS UI, open **Use omi memory anywhere**, choose Claude Code, Codex, OpenClaw, or Hermes, and expand **Manual installation**. Omi generates the connection key and shows a masked **Your key** row with a **Copy** button. You can also use the cross-platform Omi app: open **Settings → Developer Settings**, scroll to **MCP Server**, and create a key in its **API Keys** list. The complete `omi_mcp_...` value is shown only when it is created, so copy and store it then. Your key will look like: `omi_mcp_...` MCP keys are distinct from Developer API keys. An `omi_mcp_...` key authenticates the hosted MCP endpoint and `/v1/mcp/...` REST routes. An `omi_dev_...` key authenticates `/v1/dev/...` routes and will not authenticate MCP. Use the following connection details: * **Server URL:** `https://api.omi.me/v1/mcp` * **Authorization:** `Bearer omi_mcp_...` (your generated key) * **Transport:** Streamable HTTP (MCP `2026-07-28`; older protocol versions supported) *** ## Manual hosted-client configuration Claude Desktop adds remote MCP servers through the Connectors UI — not a config file. Open **Settings → Connectors → Add custom connector**, then use: * **Name:** Omi Memory * **Remote MCP server URL:** `https://api.omi.me/v1/mcp` * **Advanced settings** (only if asked): OAuth Client ID `omi-claude-prod`, OAuth Client Secret **leave blank** Click **Add**, then **Connect**, and approve Omi's OAuth consent screen. `claude_desktop_config.json` only launches local stdio `command` servers — it cannot hold a hosted HTTP entry. For a manual-key local path use the [deprecated local stdio fallback](#local-stdio-server-with-uvx-or-python-deprecated). Add the hosted server at user scope: ```bash theme={null} claude mcp add --scope user --transport http omi-memory \ https://api.omi.me/v1/mcp \ --header "Authorization: Bearer omi_mcp_YOUR_KEY_HERE" ``` Equivalently, add the entry to `~/.claude.json` directly: ```json theme={null} { "mcpServers": { "omi": { "type": "http", "url": "https://api.omi.me/v1/mcp", "headers": { "Authorization": "Bearer omi_mcp_YOUR_KEY_HERE" } } } } ``` Add a native remote entry to your `mcp.json` (project `.cursor/mcp.json` or global `~/.cursor/mcp.json`) — Streamable HTTP, no SSE transport selection: ```json theme={null} { "mcpServers": { "omi": { "url": "https://api.omi.me/v1/mcp", "headers": { "Authorization": "Bearer omi_mcp_YOUR_KEY_HERE" } } } } ``` Add a native HTTP entry to `~/.codex/config.toml` — no `mcp-remote` bridge: ```toml theme={null} [mcp_servers.omi] url = "https://api.omi.me/v1/mcp" http_headers = { Authorization = "Bearer omi_mcp_YOUR_KEY_HERE" } ``` To keep the key out of the file, Codex also supports `bearer_token_env_var = "OMI_MCP_API_KEY"` (requires that env var to be set wherever Codex runs). Restart Codex after saving the file. Add to your project's `opencode.json` (or `~/.config/opencode/opencode.json` globally): ```json theme={null} { "$schema": "https://opencode.ai/config.json", "mcp": { "omi": { "type": "remote", "url": "https://api.omi.me/v1/mcp", "enabled": true, "headers": { "Authorization": "Bearer {env:OMI_MCP_API_KEY}" } } } } ``` Store your key in a local `.env` file (or export `OMI_MCP_API_KEY` in your environment): ```bash theme={null} OMI_MCP_API_KEY=omi_mcp_YOUR_KEY_HERE ``` Be sure to use an MCP key from one of the locations in [Manual MCP-key fallback](#manual-mcp-key-fallback). It starts with `omi_mcp_`. Developer API keys (`omi_dev_...`) only authenticate Developer API endpoints and will return `401 Unauthorized` here. Poke MCP Setup Enter the server URL and API key in Poke's MCP connection settings. The Omi macOS app provides the current command or configuration under each client's **Manual installation** disclosure. Copy it there so the generated key is inserted without retyping it. Any MCP client that supports **Streamable HTTP** and custom authorization headers can use the manual-key path. With the `2026-07-28` protocol there is no initialize handshake or session ID — each request carries the protocol version and client identity in `_meta`, plus the `MCP-Protocol-Version` / `Mcp-Method` headers. Discovery starts with `server/discover`: ```bash theme={null} POST https://api.omi.me/v1/mcp Authorization: Bearer omi_mcp_YOUR_KEY_HERE Content-Type: application/json MCP-Protocol-Version: 2026-07-28 Mcp-Method: server/discover { "jsonrpc": "2.0", "id": 1, "method": "server/discover", "params": {}, "_meta": { "io.modelcontextprotocol/protocolVersion": "2026-07-28", "io.modelcontextprotocol/clientCapabilities": {}, "io.modelcontextprotocol/clientInfo": {"name": "my-client", "version": "1.0"} } } ``` Older handshake clients still work: send an `initialize` request with your `protocolVersion` (e.g. `2025-03-26`) and the server answers it in that protocol revision — no `Mcp-Session-Id` management or GET stream is required. *** ## Local stdio server with uvx or Python (deprecated) The local `mcp-server-omi` package is **deprecated** — the hosted endpoint above is the supported path for every client that accepts a remote URL. Keep this section only for clients that genuinely require a local stdio process or a self-hosted backend. Run the MCP server locally over the standard input/output transport. `uvx` (which ships with [uv](https://docs.astral.sh/uv/)) downloads and runs the published package without a separate installation. Python 3.11.6 or newer is required. Add this to your MCP client's local-server configuration: ```json theme={null} { "mcpServers": { "omi": { "command": "uvx", "args": ["mcp-server-omi"], "env": { "OMI_API_KEY": "omi_mcp_YOUR_KEY_HERE" } } } } ``` Install [uv](https://docs.astral.sh/uv/getting-started/installation/) first. The `OMI_API_KEY` value can also be supplied with each tool call. Install the package in a Python 3.11.6+ environment: ```bash theme={null} pip install mcp-server-omi ``` Then configure your MCP client to launch the local server: ```json theme={null} { "mcpServers": { "omi": { "command": "mcp-server-omi", "env": { "OMI_API_KEY": "omi_mcp_YOUR_KEY_HERE" } } } } ``` Generate the MCP key using either location in [Manual MCP-key fallback](#manual-mcp-key-fallback). Developer API keys that start with `omi_dev_` will not authenticate MCP requests. *** ## Local stdio server with Docker (deprecated) Migration-only, like the uvx path above — prefer the hosted endpoint. If you must run the MCP server locally: Generate an MCP key using either location in [Manual MCP-key fallback](#manual-mcp-key-fallback). Install Docker. We recommend [OrbStack](https://orbstack.dev/) for macOS. Add to your `claude_desktop_config.json`: ```json theme={null} { "mcpServers": { "omi": { "command": "docker", "args": ["run", "--rm", "-i", "-e", "OMI_API_KEY=omi_mcp_YOUR_KEY_HERE", "omiai/mcp-server"] } } } ``` The same Docker command can be used by any MCP client that supports local stdio servers. If you prefer to keep the key out of the configuration file, pass it through the `OMI_API_KEY` environment variable: ```bash theme={null} docker run --rm -i \ -e OMI_API_KEY="omi_mcp_YOUR_KEY_HERE" \ omiai/mcp-server ``` The API key can also be provided with each tool call. If not provided, the server uses the `OMI_API_KEY` environment variable as a fallback. *** ## Custom Backend URL Only applies to the **local `mcp-server-omi` package** above when self-hosting the Omi backend. The package appends REST segments (`memories`, `conversations/...`) directly, so the value **must end with `/v1/mcp/`**: ```bash theme={null} export OMI_API_BASE_URL="https://your-backend-url.com/v1/mcp/" ``` This is the *REST base* for the self-hosted package — distinct from the hosted MCP endpoint remote clients connect to (`https://api.omi.me/v1/mcp`, no trailing slash). Only needed for self-hosted Omi instances. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.