Model Context Protocol (MCP) Server
Relevant source files
The following files were used as context for generating this wiki page:
The Model Context Protocol (MCP) Server is a critical infrastructure component within the Omi ecosystem that allows Large Language Models (LLMs) and external AI agents to securely interact with a user's personal memory bank. By implementing the MCP specification, Omi provides a standardized interface for reading, searching, and manipulating "Memories" (known facts about the user) and "Conversations" (transcripts and structured summaries of interactions).
The system supports multiple transport layers, including a local Python-based server for desktop integration (e.g., Claude Desktop) and a pre-hosted Streamable HTTP (SSE) transport for cloud-to-cloud connections. It bridges the gap between raw data storage in databases like Firestore/Pinecone and agentic workflows, enabling AI assistants to ground their responses in a user's specific life context.
Sources: mcp/README.md, backend/routers/mcp_sse.py:16-25, AGENTS.md:120-130
Architecture and Transport Layers
The Omi MCP implementation consists of two primary deployment models designed to cater to different client environments.
Local Python Server
The standalone mcp-server-omi package is designed for local execution. It is typically run via uv or docker and communicates using JSON-RPC over standard I/O. This mode is primary for desktop applications like Claude Desktop, where the user runs the agent locally.
Sources: mcp/README.md, mcp/maintain.README.md:4-15
Pre-hosted SSE Server
The backend implements the MCP 2025-03-26 Streamable HTTP Transport specification. This allows clients to connect to a central Omi endpoint without managing a local server instance. This implementation is stateless, with every request scoped via a bearer token.
Sources: backend/routers/mcp_sse.py:18-30
The diagram illustrates the flow from different client types through the appropriate transport layer to the core Omi backend services.
Sources: mcp/README.md, backend/routers/mcp_sse.py:840-860, mcp/maintain.README.md:20-25
Security and Authentication
The MCP server enforces strict security through two main authentication mechanisms managed via the Omi app's developer settings.
Authentication Methods
- API Keys: Users generate keys in
Settings > Developer > MCP. These keys use theomi_mcp_prefix and are provided via theAuthorization: Bearer <key>header. - OAuth2: A provider-neutral OAuth implementation supporting standard
authorizeandtokenendpoints. It utilizes PKCE S256 for public clients and supports confidential clients for integrations like ChatGPT.
Sources: backend/routers/mcp_sse.py:126-150, web/app/src/components/settings/SettingsPage.tsx:1120-1150, desktop/macos/Desktop/Sources/MemoryExportService.swift:30-50
Permission Scopes
Access is governed by specific scopes defined in the backend.
| Scope | Permission Description |
|---|---|
memories.read | Read Omi memories and user profile |
memories.write | Create, edit, and delete Omi memories |
conversations.read | Search and read Omi conversations |
action_items.read | Read Omi action items |
action_items.write | Manage Omi action items |
chat.read | Read Omi chat history |
Sources: backend/routers/mcp_sse.py:173-195
Available Tools
The MCP server exposes a suite of tools that LLMs can call to interact with user data.
Memory Management Tools
get_memories: Retrieves a list of user memories with filtering by category and reviewed state.search_memories: Performs semantic search across memories using vector embeddings.create_memory: Adds a new fact to the user's memory bank.edit_memory/delete_memory: Updates or removes existing memory entries.
Sources: mcp/README.md, backend/routers/mcp_sse.py:220-300
Conversation and Context Tools
get_conversations: Lists metadata for past voice/chat interactions.get_conversation_by_id: Retrieves the full transcript and structured summary of a specific session.get_user_profile: Returns Omi's high-level summary of the user's identity and preferences.get_screen_activity: Accesses desktop activity logs (Rewind data) for high-signal temporal context.
Sources: backend/routers/mcp_sse.py:305-430, mcp/README.md
Action Item and Goal Tools
get_action_items: Fetches tasks extracted from conversations.create_action_item/update_action_item: Allows the agent to manage the user's to-do list.get_goals: Retrieves the user's stated long-term objectives.
Sources: backend/routers/mcp_sse.py:360-405
Data Flow for Tool Execution
When a tool is called via the SSE transport, the backend follows a structured execution path to ensure data integrity and authorization.
The sequence demonstrates the multi-stage validation process before data is retrieved from the underlying storage.
Sources: backend/routers/mcp_sse.py:465-480, 848-870, 920-950
Integration with External Clients
Claude Desktop Configuration
To integrate Omi with Claude Desktop, users modify the claude_desktop_config.json file. The server can be run as a Docker container or a direct Python module.
"mcpServers": {
"omi": {
"command": "docker",
"args": ["run", "--rm", "-i", "-e", "OMI_API_KEY=your_key", "omiai/mcp-server"]
}
}
Sources: mcp/README.md, web/app/src/components/settings/SettingsPage.tsx:1100-1115
Cloud Connector Setup
For web-based agents (e.g., Claude.ai or ChatGPT), Omi provides a "Guided Setup" that uses the SSE endpoint. The MemoryExportService in the desktop app generates specific instructions and copy-paste payloads for Name, Server URL, Client ID, and Auth/Token endpoints.
Sources: desktop/macos/Desktop/Sources/MemoryExportService.swift:180-220, web/app/src/components/settings/SettingsPage.tsx:1160-1230
Summary
The Omi MCP Server serves as the interoperability layer for the "2nd brain" architecture. It provides a secure, scoped, and standardized way for any AI model to access a user's life context—ranging from transcripts of yesterday's meetings to long-term personal goals. By supporting both local and pre-hosted transports, Omi ensures that personal context is available wherever the user's AI agents are running, while maintaining strict user control over data access and visibility.
Sources: mcp/README.md, backend/routers/mcp_sse.py:16-30, README.md:1-10