Setup

Fastest path: copy a prompt for your agent

Open the Developers page in the Omi web app (app.omi.me/developers), also reachable from Settings → Advanced → Connect an Agent on macOS and Settings → Connect an Agent on mobile. It offers one copy-paste prompt per path; paste it into Claude Code, Codex, Cursor, ChatGPT, OpenClaw, Hermes, or any other agent and the agent configures itself and verifies the connection (MCP tools/list, then one read-only call).

Prompt	Secret in the prompt
MCP with sign-in (recommended)	None — the agent adds the server URL and you approve OAuth in your browser
MCP with an API key	A one-time encrypted link, never the key
Developer API	A one-time encrypted link, never the key

Hand a key to an agent without pasting it

After you create a key there, choose Send to My Agent Securely. Omi encrypts the key in your browser and stores only the ciphertext in ZK Relay as a one-time share that expires after one hour or its first reveal. The copy-paste prompt then contains only the share’s agent link (https://zkr.scalingforever.com/a/<id>#v1.<key>.<token>), never the raw key. The decryption key and access token live in the link’s # fragment, which is never sent to any server. Your agent installs the zkr receiver if needed (see llms.txt), runs zkr receive --link-stdin --output <relative-path>, moves the value into its own secret store or environment variable, and deletes the file. If the link was already opened or has expired, create a new one. Show the key instead remains available when you would rather store the key yourself.

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

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 Developers page on the web.

Hosted Server with OAuth

Use the hosted server URL as the remote MCP URL:

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:

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 scope grants all available read scopes. Writes are never included by default.

ChatGPT
Claude

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.

Find or create an MCP key

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.On the web, open app.omi.me/developers and choose Create MCP Key & Prompt (or Create Key under MCP). You can also use the mobile app: open Settings → Developer Settings, scroll to MCP Server, and create a key in its API Keys list. Omi shows the full omi_mcp_... value only once, when you create it. Copy and store it then.Keys start with 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.

Configure Your Client

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 in the Connectors UI, not in 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.

Add the hosted server at user scope:

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:

{
  "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). It uses Streamable HTTP and needs no SSE transport selection:

{
  "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 is needed:

[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):

{
  "$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):

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. It starts with omi_mcp_. Developer API keys (omi_dev_...) only authenticate Developer API endpoints and will return 401 Unauthorized here.

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:

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. Use it only for clients that require a local stdio process.

Run the MCP server locally over the standard input/output transport. uvx (which ships with uv) downloads and runs the published package without a separate installation. Python 3.11.6 or newer is required.

uvx
Python

Add this to your MCP client’s local-server configuration:

{
  "mcpServers": {
    "omi": {
      "command": "uvx",
      "args": ["mcp-server-omi"],
      "env": {
        "OMI_API_KEY": "omi_mcp_YOUR_KEY_HERE"
      }
    }
  }
}

Install uv first. The OMI_API_KEY value can also be supplied with each tool call.

Install the package in a Python 3.11.6+ environment:

pip install mcp-server-omi

Then configure your MCP client to launch the local server:

{
  "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. Developer API keys that start with omi_dev_ will not authenticate MCP requests.

Local stdio server with Docker (deprecated)

This path is for migration only, like the uvx path above. Use the hosted endpoint when you can. If you must run the MCP server locally:

Generate an API Key

Generate an MCP key using either location in Manual MCP-key fallback.

Install Docker

Install Docker. We recommend OrbStack for macOS.

Configure Claude Desktop

Add to your claude_desktop_config.json:

{
  "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:

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.

Apps

Developer API

MCP

CLI

SDKs

Third-party wearables

Fastest path: copy a prompt for your agent

Hand a key to an agent without pasting it

Choose a setup method

Connect from the Omi macOS app (Recommended)

Hosted Server with OAuth

Manual MCP-key fallback

Manual hosted-client configuration

Local stdio server with uvx or Python (deprecated)

Local stdio server with Docker (deprecated)

​Fastest path: copy a prompt for your agent

​Hand a key to an agent without pasting it

​Choose a setup method

​Connect from the Omi macOS app (Recommended)

​Hosted Server with OAuth

​Manual MCP-key fallback

​Manual hosted-client configuration

​Local stdio server with uvx or Python (deprecated)

​Local stdio server with Docker (deprecated)

Fastest path: copy a prompt for your agent

Hand a key to an agent without pasting it

Choose a setup method

Connect from the Omi macOS app (Recommended)

Hosted Server with OAuth

Manual MCP-key fallback

Manual hosted-client configuration

Local stdio server with uvx or Python (deprecated)

Local stdio server with Docker (deprecated)