> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cognee.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Local Setup
> Build and run Cognee MCP from source with stdio, SSE, or HTTP transport.
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
```bash theme={null}
git clone https://github.com/topoteretes/cognee.git
cd cognee
```
Create a `.env` file with your configuration:
```bash theme={null}
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](/setup-configuration/llm-providers#provider-setup-guides) on the LLM Providers page.
First, install the [uv](https://docs.astral.sh/uv/getting-started/installation/) package manager for your operating system:
```bash theme={null}
# via Homebrew
brew install uv
# or via the standalone installer
curl -LsSf https://astral.sh/uv/install.sh | sh
```
```powershell theme={null}
# in PowerShell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```
```bash theme={null}
pip install uv
```
Then install the project dependencies. These commands are the same on every platform:
```bash theme={null}
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.
```bash theme={null}
# 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:
```bash theme={null}
# 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:
```bash theme={null}
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
Choose the transport mode based on your client requirements:
Default mode for most MCP clients. The client starts the server as a subprocess and communicates through standard input/output.
```bash theme={null}
uv run cognee-mcp
# or equivalently:
uv run cognee-mcp --transport stdio
```
Configure your MCP client to launch the server directly:
```json theme={null}
{
"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`.
```bash theme={null}
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:
```json theme={null}
{
"mcpServers": {
"cognee": {
"url": "http://localhost:8000/mcp"
}
}
}
```
Verify the server is running with the health check endpoint:
```bash theme={null}
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`.
```bash theme={null}
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:
```json theme={null}
{
"mcpServers": {
"cognee": {
"url": "http://localhost:8000/sse"
}
}
}
```
If you encounter errors on first run, reset your MCP configuration and restart.
In standalone mode the MCP server runs the full Cognee stack in-process, so it uses Cognee's standard defaults — [SQLite](/setup-configuration/relational-databases) for relational metadata, [LanceDB](/setup-configuration/vector-stores) for embeddings, and the embedded [Ladybug (Kuzu)](/setup-configuration/graph-stores) 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](/cognee-mcp/mcp-quickstart). Each linked page documents what that database stores, its default file location, and the env vars to switch providers; the [Setup Configuration overview](/setup-configuration/overview) covers `SYSTEM_ROOT_DIRECTORY` handling and the `.env` workflow.
In [API mode](#running-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](/setup-configuration/graph-stores) 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.
`--api-token` is sent to the backend as `Authorization: Bearer `. 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](/setup-configuration/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".
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:**
```bash theme={null}
uv run cognee-mcp \
--transport http \
--host 0.0.0.0 \
--port 8000 \
--api-url http://localhost:8080 \
--api-token your_token
```
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://`) 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.
```bash theme={null}
# 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.
```bash theme={null}
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](/cognee-mcp/mcp-quickstart).
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` and `minimal` both list `remember`, `recall`, `forget`; `all` lists every registered tool (those three plus `cognify_status`) and installs no search transform. An unrecognized value logs a warning and falls back to `default`. |
```bash theme={null}
# 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:
```bash theme={null}
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](/cognee-mcp/mcp-tools#tool-modes) for the per-mode tool lists and for how an agent finds and calls an unlisted tool.
By default, when a caller invokes the [`recall`](/cognee-mcp/mcp-tools) 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.
```bash theme={null}
# 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](/cognee-mcp/mcp-tools).
## Next Steps
After starting the server, configure your AI client to connect to it. See the [integrations](/cognee-mcp/integrations) section for client-specific setup instructions.
## Need Help?
Get support and connect with other developers using Cognee MCP.