Local Setup - Cognee Documentation

Build and run Cognee MCP from source to access advanced customization, multiple transport options, and the latest development features, including the current memory-oriented MCP tools.

Advantages of Local Setup

Full Control: Customize server configuration, add providers, and modify behavior
Latest Features: Access development features before they reach Docker releases
Multiple Transports: Choose stdio, SSE, or HTTP transport modes
Current Tool Surface: Use remember, recall, and forget alongside compatibility tools
Development Ready: Debug, modify, and contribute to the codebase

Setup Steps

Clone Repository

git clone https://github.com/topoteretes/cognee.git
cd cognee

Create Environment File

Create a .env file with your configuration:

LLM_API_KEY="your-openai-api-key"

No API key? If your MCP host grants the sampling capability, set LLM_PROVIDER="mcp-sampling" and omit LLM_API_KEY — Cognee delegates completions to the host’s own model. You still need an embedding provider for vector search, and host support varies. See MCP Sampling on the LLM Providers page.

Install Dependencies

First, install the uv package manager for your operating system:

macOS / Linux
Windows
Any (pip)

# via Homebrew
brew install uv

# or via the standalone installer
curl -LsSf https://astral.sh/uv/install.sh | sh

# in PowerShell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

pip install uv

Then install the project dependencies. These commands are the same on every platform:

cd cognee-mcp
uv sync --dev --all-extras --reinstall

When to re-run uv sync. Re-run it after pulling new commits, switching branches, or updating Cognee — anytime pyproject.toml or uv.lock may have changed. For routine refreshes, use uv sync --dev --all-extras; keep --reinstall for the first install or when your environment looks stale or broken.

Activate and Run

# Run with default stdio transport
uv run cognee-mcp

Running in API Mode

To connect the MCP server to an existing Cognee backend instead of running standalone:

# Start MCP in HTTP or SSE mode pointing to the backend
uv run cognee-mcp --transport http --api-url http://localhost:8080

# Optional: add an auth token if the backend requires it
uv run cognee-mcp --transport http --api-url http://localhost:8080 --api-token your_backend_token

When --api-url is provided, the MCP server acts as an interface to the centralized backend. This allows multiple MCP instances and clients to share the same knowledge graph. You can also pass these as command-line arguments:

uv run cognee-mcp --transport http --api-url http://localhost:8080 --api-token your_token

The source-run uv run cognee-mcp entrypoint reads --api-url and --api-token flags. The API_URL and API_TOKEN environment variables are used by the Docker entrypoint wrapper, not by the source runner directly.

Use cases:

Team collaboration with shared memory
Multiple AI clients accessing consistent data
Centralized knowledge graph management

Further details

Transport Modes

Choose the transport mode based on your client requirements:

stdio (default)
HTTP
SSE

Default mode for most MCP clients. The client starts the server as a subprocess and communicates through standard input/output.

uv run cognee-mcp
# or equivalently:
uv run cognee-mcp --transport stdio

Configure your MCP client to launch the server directly:

{
  "mcpServers": {
    "cognee": {
      "command": "uv",
      "args": [
        "--directory", "/absolute/path/to/cognee-mcp",
        "run", "cognee-mcp"
      ]
    }
  }
}

Replace /absolute/path/to/cognee-mcp with the actual path to your cloned cognee-mcp directory.

HTTP transport mode. The server starts on http://127.0.0.1:8000 and exposes a Streamable HTTP endpoint at /mcp.

uv run cognee-mcp --transport http
# Custom host/port:
uv run cognee-mcp --transport http --host 0.0.0.0 --port 9000

Configure your MCP client to connect to the HTTP endpoint:

{
  "mcpServers": {
    "cognee": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

Verify the server is running with the health check endpoint:

curl http://localhost:8000/health

Server-Sent Events transport mode. The server starts on http://127.0.0.1:8000 and exposes an SSE endpoint at /sse.

uv run cognee-mcp --transport sse
# Custom host/port:
uv run cognee-mcp --transport sse --host 0.0.0.0 --port 9000

Configure your MCP client to connect to the SSE endpoint:

{
  "mcpServers": {
    "cognee": {
      "url": "http://localhost:8000/sse"
    }
  }
}

If you encounter errors on first run, reset your MCP configuration and restart.

Default databases (and how to change them)

In standalone mode the MCP server runs the full Cognee stack in-process, so it uses Cognee’s standard defaults — SQLite for relational metadata, LanceDB for embeddings, and the embedded Ladybug (Kuzu) engine for the knowledge graph. All three live as files under SYSTEM_ROOT_DIRECTORY, so no external database service is required, and the same defaults apply to the Docker image from the Quickstart. Each linked page documents what that database stores, its default file location, and the env vars to switch providers; the Setup Configuration overview covers SYSTEM_ROOT_DIRECTORY handling and the .env workflow.In API mode these settings are irrelevant to the MCP process — the backend it points at owns the databases, so configure them there instead.Two MCP-specific notes:

The embedded Ladybug/Kuzu graph store uses file-based locking, so several MCP server processes sharing one SYSTEM_ROOT_DIRECTORY — for example separate editor windows each spawning their own stdio server — contend for the same graph file. Neo4j is the recommended upgrade path for that setup.
The cognee-mcp package already depends on cognee[postgres-binary,docs,neo4j], so the Neo4j and Postgres/PGVector drivers ship with it — switching providers needs only the environment variables, not the extra installs the setup pages mention.

Switching providers does not migrate existing memory — re-run your ingestion (remember) against the new backend to repopulate it.

Token lifetime for long-running MCP servers

--api-token is sent to the backend as Authorization: Bearer <token>. When the backend has REQUIRE_AUTHENTICATION=true, the token returned by POST /api/v1/auth/login is a JWT whose lifetime is controlled by JWT_LIFETIME_SECONDS on the backend (default: 3600 — one hour). Once it expires, the MCP server’s requests start failing with 401 Unauthorized until you restart it with a fresh token. The MCP server does not automatically re-authenticate.For deployments where the MCP server runs longer than the JWT lifetime (e.g., MCP and the API hosted as separate services on Railway, Fly.io, ECS, or similar), use one of these patterns:

Extend the JWT lifetime on the backend. Set JWT_LIFETIME_SECONDS to a value that comfortably exceeds your MCP uptime and restart the backend. See Security — JWT token settings for the full settings.
Run the MCP server unauthenticated against a backend that does not require auth. If the MCP server and the API are co-located on a private network (same VPC, internal Railway/Fly project network, sidecar container), set REQUIRE_AUTHENTICATION=false (and ENABLE_BACKEND_ACCESS_CONTROL=false) on the backend and omit --api-token. Do not expose the backend publicly in this mode.
Restart the MCP server on a schedule with a freshly minted token. Re-run POST /api/v1/auth/login, capture access_token, and pass it on the next uv run cognee-mcp (or container restart). This is a workaround, not a substitute for a longer JWT_LIFETIME_SECONDS.

The MCP server has no built-in token refresh, so changing JWT_LIFETIME_SECONDS on the backend (or removing the auth requirement entirely on a private network) is the recommended fix for “the MCP server stops working after an hour”.

Server Arguments Reference

All available arguments for uv run cognee-mcp:

Argument	Default	Description
`--transport`	`stdio`	Transport protocol: `stdio`, `http`, or `sse`
`--host`	`127.0.0.1`	Host to bind the server to (HTTP/SSE only)
`--port`	`8000`	Port to bind the server to (HTTP/SSE only)
`--path`	`/mcp`	URL path for the HTTP endpoint
`--log-level`	`info`	Log verbosity: `debug`, `info`, `warning`, or `error`
`--no-migration`	off	Skip database migrations on startup
`--tool-mode`	`default`	How many tools appear in `tools/list`: `default`, `minimal`, or `all`. Overrides `COGNEE_MCP_TOOL_MODE`
`--api-url`	—	URL of a running Cognee backend (enables API mode)
`--api-token`	—	Auth token for the backend API (if required)
`--serve-url`	—	Cognee Cloud or remote instance URL used with `cognee.serve()`
`--serve-api-key`	—	API key for the `--serve-url` instance

Example with all options:

uv run cognee-mcp \
  --transport http \
  --host 0.0.0.0 \
  --port 8000 \
  --api-url http://localhost:8080 \
  --api-token your_token

Transport Security (DNS Rebinding & CORS)

The HTTP and SSE transports validate the Host and Origin headers on every request to protect against DNS rebinding attacks. By default, only loopback addresses (127.0.0.1, localhost, [::1]) are accepted. If you bind the server to 0.0.0.0 or a LAN IP — for example, to access it from another machine over SSH or a private network — you must whitelist the hosts you connect with, or requests will be rejected.

Variable	Default	Description
`MCP_ALLOWED_HOSTS`	—	Comma-separated extra `Host` header patterns to accept (e.g. `192.168.1.50:,myserver.local:`). Each entry must include the `:*` port glob. Matching `Origin` values (`http://<host>`) are added automatically.
`MCP_DISABLE_DNS_REBINDING_PROTECTION`	`false`	Set to `true` to disable all `Host`/`Origin` validation. Use only in trusted networks (LAN, Docker, VPN) where you control all clients.
`MCP_CORS_ALLOW_ORIGINS`	`http://localhost:3000`	Comma-separated origins allowed by the CORS middleware on the HTTP and SSE endpoints.

Local development (default): No configuration needed. The server binds to 127.0.0.1 and accepts requests from the loopback defaults.Remote deployment — strict (recommended): Run the MCP server on a remote box and connect from a local AI client. Whitelist the hostname your client uses to reach the MCP server, and set CORS to the browser or app origins that will call it.

# On the remote machine
export MCP_ALLOWED_HOSTS="myserver.local:*,192.168.1.50:*"
export MCP_CORS_ALLOW_ORIGINS="http://localhost:3000,https://chat.example.com"
uv run cognee-mcp --transport http --host 0.0.0.0 --port 8000

In this example, MCP_ALLOWED_HOSTS covers the MCP server hostnames clients connect to, while MCP_CORS_ALLOW_ORIGINS covers the calling page or app origins.Remote deployment — permissive: Disable protection entirely on a trusted private network. This skips both Host and Origin validation.

export MCP_DISABLE_DNS_REBINDING_PROTECTION=true
uv run cognee-mcp --transport http --host 0.0.0.0 --port 8000

Only disable DNS rebinding protection on networks you fully control. With protection off, any website your browser visits could issue requests against the MCP server.

These variables can also be set in your .env file alongside LLM_API_KEY and other configuration. They apply equally to source runs (uv run cognee-mcp) and the Docker image used in the Quickstart.

Tool modes

The server does not put its whole tool catalog in tools/list. By default it lists a small set and makes the rest discoverable through the search_tools / call_tool pair, which keeps the per-turn tool payload small for connected agents. Tools left out of the list stay registered and callable directly by name.

Variable	Default	Description
`COGNEE_MCP_TOOL_MODE`	`default`	Which tools appear in `tools/list`. `default` lists `remember`, `recall`, `forget` and the three workspace UI entry tools; `minimal` lists only `remember`, `recall`, `forget`; `all` lists every registered tool and installs no search transform. An unrecognized value logs a warning and falls back to `default`.

# List only the memory API; everything else via search_tools
export COGNEE_MCP_TOOL_MODE=minimal

# Restore the previous flat tool listing
export COGNEE_MCP_TOOL_MODE=all

The same choice can be made per process with the --tool-mode argument, which takes precedence over the environment variable:

uv run cognee-mcp --tool-mode all

The mode is resolved when the MCP server process starts, so changes only take effect after you restart the server (or redeploy the container). If an integration or script depends on the full flat tools/list response, use all. See the Tools Reference for the per-mode tool lists and for how an agent finds and calls an unlisted tool.

Default recall synthesis prompt

By default, when a caller invokes the recall tool without a system_prompt, the request uses Cognee’s built-in synthesis prompt. You can set an opt-in, server-side default so that every recall that omits system_prompt uses a synthesis policy you define once — useful when a single Cognee instance is shared as long-term memory across several MCP clients.Provide the default with exactly one of these environment variables:

Variable	Default	Description
`COGNEE_MCP_RECALL_SYSTEM_PROMPT`	—	Inline prompt text used as the default synthesis prompt for `recall`.
`COGNEE_MCP_RECALL_SYSTEM_PROMPT_FILE`	—	Path to a UTF-8 file whose contents are used as the default synthesis prompt. Read once per `recall` call.

COGNEE_MCP_RECALL_SYSTEM_PROMPT takes precedence over COGNEE_MCP_RECALL_SYSTEM_PROMPT_FILE when both are set. If the file cannot be read, the server logs a warning and falls back as if the default were not configured.Precedence for the prompt used by recall is: explicit caller system_prompt > server-side env/file default > backend default. When neither variable is set (or both resolve to empty), behavior is unchanged and no default system_prompt is added.

# Inline
export COGNEE_MCP_RECALL_SYSTEM_PROMPT="Answer concisely and cite the source memory."

# Or from a file
export COGNEE_MCP_RECALL_SYSTEM_PROMPT_FILE=/etc/cognee/recall_prompt.txt

The default is resolved from the environment inside the MCP server process, so changes only take effect after you restart the server (or redeploy the container). Treat the prompt content as configuration — if it contains sensitive instructions, manage it with your existing secrets practices rather than committing it to source control.

The preferred MCP workflow is to use remember, recall, and forget. For the full tool catalog and how much of it appears in tools/list, see the Tools Reference.

Next Steps

After starting the server, configure your AI client to connect to it. See the integrations section for client-specific setup instructions.

Need Help?

Join Our Community

Get support and connect with other developers using Cognee MCP.

​Advantages of Local Setup

​Setup Steps

​Running in API Mode

​Further details

​Next Steps

​Need Help?

Join Our Community

Advantages of Local Setup

Setup Steps

Running in API Mode

Further details

Next Steps

Need Help?