# Integration Guide Reviewed 2026-11-06 against v12.6.0 and current GitHub main. Python 3.11+ is required. Choose the transport your client needs. MCP clients connect over stdio or to an authenticated `/mcp` endpoint. REST clients use `/api/...`; `/mcp` is not a REST search endpoint. ## Install and connect locally ```bash python -m pip install mcp-memory-service ``` ### Claude Desktop Edit the existing configuration file and merge the server entry: - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` - Windows: `%APPDATA%\Claude\claude_desktop_config.json` - Linux: `~/.config/Claude/claude_desktop_config.json` ```json { "mcpServers": { "memory": { "command": "memory", "args": ["server"] } } } ``` Use the absolute path to the installed `memory` executable if the desktop application's PATH differs from your terminal. Restart the client and check for `memory_store` and `memory_search`. ### Claude Code ```bash claude mcp add memory -- memory server ``` MCP tools and automatic session hooks are separate integrations. For hooks, use the [current plugin guide](https://github.com/doobidoo/mcp-memory-service/blob/main/claude-hooks/PLUGIN.md) or the [legacy Python installer](https://github.com/doobidoo/mcp-memory-service/blob/main/claude-hooks/README.md), not both. See [Quality Hooks Integration](17-Quality-Hooks-Integration). ## HTTP service and authentication For a local development instance only: ```bash MCP_ALLOW_ANONYMOUS_ACCESS=true memory server --http ``` The default local URL is `http://127.0.0.1:8000`. The dashboard is at `/`; the live REST schema is at `/api/docs`. Do not assume setting a port or using an `https://` URL enables TLS. Shared deployments need API-key or OAuth authentication and trusted HTTPS. Follow [Remote MCP Setup](https://github.com/doobidoo/mcp-memory-service/blob/main/docs/remote-mcp-setup.md) for reverse-proxy and direct-TLS setups. The API key is configured on the server with `MCP_API_KEY`; REST clients can send `X-API-Key`. OAuth clients send an access token using `Authorization: Bearer ...`. ### Remote MCP clients For an already configured authenticated HTTPS deployment: ```bash claude mcp add --transport http memory-service https://memory.example.com/mcp ``` Complete the configured authentication flow. Registration alone is not a grant of write access. Browser clients such as claude.ai and ChatGPT also need the HTTPS/OAuth deployment described in the remote setup guide. ## OpenCode, Codex and agent frameworks | Client | Setup | |---|---| | OpenCode | Install the [repository's local plugin](https://github.com/doobidoo/mcp-memory-service/blob/main/opencode/README.md). Automatic hooks, the optional `/memory` command and the TUI sidebar are separate setup steps. | | Codex | Install [Codex memory hooks](https://github.com/doobidoo/mcp-memory-service/blob/main/codex/README.md) from a repository checkout after configuring the HTTP service. | | LangGraph, CrewAI, AutoGen | Use the [REST agent examples](https://github.com/doobidoo/mcp-memory-service/tree/main/docs/agents). No MCP client library is required for REST. | | Other MCP clients | Configure the `memory server` stdio command or a supported authenticated `/mcp` transport using the client's own configuration format. | ## REST: health and search Use the deployed URL and credentials. REST search accepts `n_results`; the MCP tool uses `limit`. ```bash MEMORY_BASE_URL=http://127.0.0.1:8000 MEMORY_API_KEY=replace-with-your-api-key curl --fail "$MEMORY_BASE_URL/api/health" \ -H "X-API-Key: $MEMORY_API_KEY" curl --fail -X POST "$MEMORY_BASE_URL/api/search" \ -H "X-API-Key: $MEMORY_API_KEY" -H "Content-Type: application/json" \ -d '{"query": "authentication architecture", "n_results": 5}' ``` ### Node.js client This example needs Node.js 18+ with built-in `fetch`. Set `MEMORY_BASE_URL` and `MEMORY_API_KEY` in the process environment for an authenticated deployment. Certificate verification remains enabled. ```javascript const baseUrl = process.env.MEMORY_BASE_URL || 'http://127.0.0.1:8000'; const apiKey = process.env.MEMORY_API_KEY; async function searchMemories(query, nResults = 5) { const headers = { 'Content-Type': 'application/json' }; if (apiKey) headers['X-API-Key'] = apiKey; const response = await fetch(new URL('/api/search', baseUrl), { method: 'POST', headers, body: JSON.stringify({ query, n_results: nResults }) }); if (!response.ok) throw new Error(`Memory search failed: HTTP ${response.status}`); const data = await response.json(); return data.results; } ``` REST search returns a `results` array containing entries with `memory` and `similarity_score`. It does not return a top-level `memories` array. Follow `/api/docs` for the complete response. ## Connection problems - Check the actual scheme, hostname and port. HTTP on port 8000 is not automatically HTTPS. - For certificate errors, configure a trusted certificate or CA; do not disable TLS verification globally. - For 401/403 responses, check credentials, scopes and store restrictions, not just connectivity. - For missing tools, confirm that an MCP client uses `/mcp` or stdio rather than a REST endpoint. - For hooks that do not load context, verify installation and the endpoint used by that hooks process. See [Troubleshooting](07-TROUBLESHOOTING), [Setup Guide](https://github.com/doobidoo/mcp-memory-service/blob/main/docs/setup-guide.md) and [OAuth Setup](OAuth-2.1-Setup-Guide). Earlier client-specific examples remain in the [page history](https://github.com/doobidoo/mcp-memory-service/wiki/03-Integration-Guide/_history).