Claude.ai (Web)

Claude.ai (web) and Claude mobile apps (iOS/Android) connect to AutoMem through a remote MCP sidecar — a separately deployed HTTPS service that bridges the MCP protocol to AutoMem’s HTTP API. This is required because cloud-based Claude cannot spawn local processes.

Unlike ChatGPT, Claude.ai supports both header-based and URL-based authentication.

---

Architecture

graph TB
    subgraph "Remote MCP (HTTP/SSE Transport)"
        CW["Claude.ai Web / Claude Mobile"]
        SIDECAR["MCP Sidecar (separate deployment) — POST /mcp / GET /mcp/sse"]
        AUTOMEM["AutoMem API :8001"]

        CW -->|"HTTPS"| SIDECAR
        SIDECAR -->|"HTTP"| AUTOMEM
    end

The sidecar service (mcp-sse-server) is included in the AutoMem server repository. It implements:

• Streamable HTTP (recommended): POST /mcp — stateless MCP-over-HTTP, MCP protocol version 2025-03-26
• SSE (legacy): GET /mcp/sse — server→client event stream, MCP protocol version 2024-11-05

Only the SSE transport keeps server-side sessions: each connection is registered in memory under a sessionId, and the client sends that ID with every POST /mcp/messages. Streamable HTTP is stateless. Every /mcp request builds a new server and transport with no session ID generator and no event store, any Mcp-Session-Id header is ignored, and the sidecar does not resume streams or replay events after a reconnect, so a Last-Event-ID header has no effect.

Source: server.js:1051-1085 (Streamable HTTP), server.js:1119-1128 (SSE sessions)

---

Prerequisites

1. A deployed AutoMem service
2. The MCP sidecar deployed and accessible over HTTPS
3. A Claude.ai account (Pro recommended for MCP features)

---

Deploy the MCP Sidecar

Required environment variables:

Variable	Purpose
AUTOMEM_API_URL	AutoMem service URL
AUTOMEM_API_TOKEN	API token for authentication
PORT	Listen port (default: 8080)

AUTOMEM_ENDPOINT is supported as a legacy alias for AUTOMEM_API_URL.

Railway deployment (recommended):

1. Deploy via Railway one-click template
2. Go to mcp-sse-server service → Settings → Networking → Generate Domain
3. Your sidecar URL will be: https://your-mcp-bridge.up.railway.app

Caution

The sidecar’s AUTOMEM_API_URL must point at the port the memory service listens on. The memory service reads PORT and falls back to 8001 only when it is unset (runtime_wiring.py:82). Keep the memory service’s PORT and the port in AUTOMEM_API_URL identical; a mismatch makes the sidecar’s tool calls fail with connection errors.

On Railway, set PORT=8001 on the memory service (see the Railway guide) and use internal DNS for AUTOMEM_API_URL: http://memory-service.railway.internal:8001

Sidecar endpoints:

Endpoint	Method	Transport	Purpose
/mcp	POST	Streamable HTTP	Stateless MCP over HTTP (recommended)
/mcp/sse	GET	SSE	Server→client event stream (legacy)
/mcp/messages?sessionId=<id>	POST	SSE	Client→server JSON-RPC (legacy)
/health	GET	HTTP	Health probe

---

Connect Claude.ai Web

1. Open Claude.ai → Settings → MCP Servers
2. Add a new server

Streamable HTTP (recommended):

https://your-mcp-bridge.up.railway.app/mcp?api_token=YOUR_AUTOMEM_TOKEN

SSE (fallback):

https://your-mcp-bridge.up.railway.app/mcp/sse?api_token=YOUR_AUTOMEM_TOKEN

---

Connect Claude Mobile (iOS/Android)

1. Open the Claude app → Settings → MCP Servers
2. Add server URL:

Streamable HTTP:

https://your-mcp-bridge.up.railway.app/mcp?api_token=YOUR_AUTOMEM_TOKEN

The mobile apps use the same MCP configuration as the web interface.

---

Authentication Options

Claude.ai supports both authentication methods:

URL-based (simpler):

https://your-mcp-bridge.up.railway.app/mcp?api_token=YOUR_TOKEN

Header-based (more secure):

• Server URL: https://your-mcp-bridge.up.railway.app/mcp
• Header: Authorization: Bearer YOUR_TOKEN

Tip

Prefer header-based authentication when the Claude.ai interface supports it — tokens in URLs appear in server logs and browser history.

Token extraction priority (sidecar getAuthToken() function):

1. Authorization: Bearer <token> header
2. X-API-Key: <token> header
3. X-API-Token: <token> header
4. ?api_key=<token> query parameter
5. ?apiKey=<token> query parameter
6. ?api_token=<token> query parameter

getAuthToken() checks only those six sources. When it finds none, the /mcp and /mcp/sse route handlers fall back to the sidecar’s AUTOMEM_API_TOKEN environment variable, and they answer 401 if that is unset too. A token sent by the client therefore takes precedence over the environment variable. The sidecar only checks that a token is present; whichever one it uses is forwarded to AutoMem as a Bearer token, which AutoMem checks against its own API token when one is configured (on every endpoint except /health, so check_database_health does not test the token).

Source: getAuthToken(), /mcp fallback, /mcp/sse fallback

---

Available Memory Tools

All six AutoMem tools are available via remote MCP:

Tool	Type	Description
store_memory	Write	Store content with tags, importance, metadata
recall_memory	Read	Hybrid search (semantic + keyword + tags + time)
associate_memories	Write	Create typed relationships between memories
update_memory	Write	Modify existing memory fields
delete_memory	Write/Destructive	Permanently remove a memory
check_database_health	Read	Check FalkorDB and Qdrant connection status

The recall_memory tool supports advanced parameters including expand_relations, expand_entities, auto_decompose, expand_min_importance, expand_min_strength, context, language, active_path, context_tags, context_types, and priority_ids.

---

Verification

Test the connection:

Check the health of the AutoMem service

Test storing and recalling:

Store a memory: I prefer concise responses without unnecessary preamble.

What are my communication preferences?

---

Migrating from SSE to Streamable HTTP

Streamable HTTP is the recommended transport. To migrate:

Before (SSE):

https://your-mcp-bridge.up.railway.app/mcp/sse?api_token=<token>

After (Streamable HTTP):

https://your-mcp-bridge.up.railway.app/mcp?api_token=<token>

Benefits of Streamable HTTP:

• Each JSON-RPC request is answered in the body of its own POST /mcp, with no GET /mcp/sse stream to open first
• No sessionId management needed: the endpoint keeps no session and ignores any Mcp-Session-Id header

Streamable HTTP on this sidecar cannot resume a stream with Last-Event-ID (see Reconnecting).

---

Troubleshooting

Claude.ai cannot connect to MCP endpoint

1. Check sidecar health: curl https://your-mcp-bridge.up.railway.app/health
2. Verify DNS resolves for your domain
3. Ensure valid TLS certificate (Railway auto-provisions)
4. Check firewall allows HTTPS (443)

401 Unauthorized

1. Verify AUTOMEM_API_TOKEN in sidecar environment variables
2. Check that the token matches between sidecar and memory service
3. Test token against an endpoint that checks it (/health does not): curl -H "Authorization: Bearer $TOKEN" "https://your-automem.up.railway.app/recall?query=test&limit=1"

SSE connection drops

The sidecar sends heartbeats every 20 seconds to maintain SSE connections. If Claude.ai drops the connection before 20 seconds:

• Check if a reverse proxy is buffering the SSE stream
• The sidecar sets anti-buffering headers (X-Accel-Buffering: no, Cache-Control: no-cache, no-transform)
• Consider switching to Streamable HTTP transport

Reconnecting (Streamable HTTP)

The sidecar does not replay missed events. Each /mcp request gets its own transport, created without an event store, so a Last-Event-ID header has no effect and there is no stream to resume. The InMemoryEventStore class in server.js is defined but never attached to a transport (server.js:223-263). A client that reconnects simply sends a new POST /mcp; the sidecar keeps no session between requests.

---

Related Platforms

Other cloud platforms using the same remote MCP sidecar:

• ChatGPT — URL auth only, Streamable HTTP or SSE
• ElevenLabs — SSE with header auth, 30s idle timeout handled by heartbeat