Setup

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.

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:

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 the scope parameter 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.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.

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

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) — Streamable HTTP, 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:

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

Migration-only, like the uvx path above — prefer the hosted endpoint. 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.

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

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.

Getting Started

Reference

Resources

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)

Custom Backend URL

​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)

​Custom Backend URL

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)

Custom Backend URL