Skip to content
Engram Docs

MCP client setup

Two common client wirings: Claude Desktop spawning its own local server over stdio (the default transport), and Claude Code talking to a persistent shared server over Streamable HTTP. For the full five-agent fleet (Copilot, Cursor, Codex, Gemini), see client wiring.

Build the server first

Section titled “Build the server first”
Terminal window
pnpm build

Claude Desktop (stdio)

Section titled “Claude Desktop (stdio)”

Claude Desktop spawns the server as a subprocess. Copy the example config from the repository root:

Terminal window
cp claude_desktop_config.json.example claude_desktop_config.json

Edit it so the args value points to the absolute path of apps/mcp-server/dist/main.js in your checkout:

{
  "mcpServers": {
    "engram": {
      "command": "node",
      "args": ["/absolute/path/to/your/engram/apps/mcp-server/dist/main.js"],
      "env": {
        "DATABASE_URL": "postgresql://engram:dev_password@localhost:5432/engram",
        "DEPLOYMENT_PROFILE": "lite",
        "NODE_ENV": "production"
      }
    }
  }
}

Set "DEPLOYMENT_PROFILE" to "lite" (single-user, shown above) or "standard" (multi-tenant). Both profiles need only DATABASE_URL — Postgres is the sole backing service.

Copy the file into Claude Desktop’s config location and restart the client:

Operating system Config path
Linux ~/.config/Claude/claude_desktop_config.json
macOS ~/Library/Application Support/Claude/claude_desktop_config.json
Windows %APPDATA%\Claude\claude_desktop_config.json

Then ask the client to call the ping tool to confirm connectivity.

Claude Code (Streamable HTTP)

Section titled “Claude Code (Streamable HTTP)”

To share one persistent server across sessions (and across agents), run the server with MCP_TRANSPORT=streamable-http — see the server runbook — and register it in the repository’s .mcp.json:

{
  "mcpServers": {
    "engram": {
      "type": "http",
      "url": "http://127.0.0.1:3000/mcp",
      "headers": {
        "Authorization": "Bearer ${ENGRAM_API_KEY:-}"
      }
    }
  }
}

The ${ENGRAM_API_KEY:-} default keeps the file parseable when the key is unset. Mint a key with the steps in Provision agent API keys.

Authentication rules (read before sharing a server)

Section titled “Authentication rules (read before sharing a server)”
  • AUTH_REQUIRED defaults to false. A single-user stdio server spawned by your own client needs no key.
  • With AUTH_REQUIRED=false on an HTTP server, the tenant userId is read from the request body and is spoofable by any process that can reach the port. For that reason a multi-tenant Streamable HTTP server without AUTH_REQUIRED=true refuses to start in every NODE_ENV unless the operator explicitly sets ALLOW_UNAUTHENTICATED_HTTP=true — an acknowledged trusted-network escape hatch (for example a loopback-bound, single-operator host). Multi-tenant means the standard profile; the lite profile is single-user, so the gate does not apply to it.
  • The recommended posture for any shared server: AUTH_REQUIRED=true, one least-privilege API key per agent, and a loopback (127.0.0.1) bind. Setting AUTH_REQUIRED=true also requires a JWT_SECRET of at least 32 characters.

Verify

Section titled “Verify”

With the server running:

Terminal window
curl http://localhost:3000/health

For an HTTP server, the repository’s verification script checks the full MCP handshake and the auth gate:

Terminal window
AUTH_REQUIRED=true ./scripts/verify-engram-server.sh

Next steps

Section titled “Next steps”