Skip to content

setup.mdx

Latest commit

 

History

History
363 lines (286 loc) · 11 KB

setup.mdx

File metadata and controls

363 lines (286 loc) · 11 KB
Raw
title Setup
icon gear
description 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.

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

The endpoint supports MCP Streamable HTTP (2025-03-26) and advertises OAuth metadata at:

https://api.omi.me/.well-known/oauth-protected-resource/v1/mcp/sse
https://api.omi.me/.well-known/oauth-authorization-server

OAuth uses browser sign-in, explicit consent, authorization code + PKCE, and refresh tokens. Omi currently provides registered public clients for its ChatGPT and Claude setup flows. A generic MCP client cannot invent a client ID; if it is not one of those supported flows, use an MCP key instead.

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/sse`
- **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/sse`
- **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_...`

<Note>
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.
</Note>
Use the following connection details: 
- **Server URL:** `https://api.omi.me/v1/mcp/sse`
- **Authorization:** `Bearer omi_mcp_...` (your generated key)
- **Transport:** Streamable HTTP (MCP `2025-03-26`)

Manual hosted-client configuration

Claude's cloud connector supports OAuth as described above. For a manual-key fallback, add this to `claude_desktop_config.json`: 
```json
{
  "mcpServers": {
    "omi": {
      "url": "https://api.omi.me/v1/mcp/sse",
      "headers": {
        "Authorization": "Bearer omi_mcp_YOUR_KEY_HERE"
      }
    }
  }
}
```

**Config file location:**
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows PowerShell: `$env:APPDATA\Claude\claude_desktop_config.json`
- Windows cmd: `%APPDATA%\Claude\claude_desktop_config.json`

Claude Code can be configured at user scope instead:

```bash
claude mcp add --scope user --transport http omi-memory \
  https://api.omi.me/v1/mcp/sse \
  --header "Authorization: Bearer omi_mcp_YOUR_KEY_HERE"
```
Go to **Cursor Settings → MCP** and add a new server: 
- **Name:** Omi
- **Transport:** SSE
- **URL:** `https://api.omi.me/v1/mcp/sse`
- **Headers:** `Authorization: Bearer omi_mcp_YOUR_KEY_HERE`
Add this to `~/.codex/config.toml`: 
```toml
[mcp_servers.omi-memory]
command = "npx"
args = ["-y", "mcp-remote", "https://api.omi.me/v1/mcp/sse", "--header", "Authorization: Bearer omi_mcp_YOUR_KEY_HERE"]
```

Restart Codex after saving the file.
Add to your project's `opencode.json` (or `~/.config/opencode/opencode.json` globally): 
```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "omi": {
      "type": "remote",
      "url": "https://api.omi.me/v1/mcp/sse",
      "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
OMI_MCP_API_KEY=omi_mcp_YOUR_KEY_HERE
```

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

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: 
```bash
# Endpoint
POST https://api.omi.me/v1/mcp/sse

# Headers
Authorization: Bearer omi_mcp_YOUR_KEY_HERE
Content-Type: application/json
Accept: text/event-stream  # for SSE responses

# Body (JSON-RPC 2.0)
{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {}}
```

Local stdio server with uvx or Python

Run the MCP server locally over the standard input/output transport. uvx 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
{
  "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
pip install mcp-server-omi
```

Then configure your MCP client to launch the local server:

```json
{
  "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

If you prefer to 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
{
  "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

If you are self-hosting the Omi backend:

export OMI_API_BASE_URL="https://your-backend-url.com"
Only needed for self-hosted Omi instances. The default URL points to the official Omi API.