> ## 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.

# Quickstart

> Start the Cognee MCP server with Docker and test it from any MCP client.

Start the Cognee MCP server using Docker to quickly test AI memory integration.

## Prerequisites

* Docker installed and running
* OpenAI API key

## Setup Steps

<Steps>
  <Step title="Set Your API Key">
    ```bash theme={null}
    export LLM_API_KEY=your_api_key_here
    ```
  </Step>

  <Step title="Create Environment File">
    ```bash theme={null}
    echo "LLM_API_KEY=your_api_key_here" > .env
    ```
  </Step>

  <Step title="Start the Server">
    ```bash theme={null}
    docker run -e TRANSPORT_MODE=http --env-file ./.env -p 8000:8000 --rm -it cognee/cognee-mcp:main
    ```

    The server starts on port 8000 with HTTP transport mode.
  </Step>

  <Step title="Verify the Server">
    ```bash theme={null}
    curl http://localhost:8000/health
    ```

    You should see a healthy response from the server.
  </Step>
</Steps>

## Persist Data

By default, the container removes its local data when it stops. Use a bind mount or named Docker volume if you want memory to survive restarts.

```bash theme={null}
docker run -e TRANSPORT_MODE=http --env-file ./.env -p 8000:8000 \
  -v cognee_data:/app/data \
  --rm -it cognee/cognee-mcp:main
```

Replace `cognee_data` with either:

* A named Docker volume, such as `cognee_data:/app/data`
* A local directory path, such as `./cognee_data:/app/data`

## Kuzu/Ladybug JSON Extension

The default Ladybug (Kuzu) graph backend needs its JSON extension for graph queries that rely on JSON — including `recall` and temporal search. The `cognee/cognee-mcp` image pre-installs this extension at build time, so it is baked into the image even when the container has no network access at runtime. Pulling the latest image (or rebuilding it) ensures the extension is present.

If you run the MCP server in a network-restricted container that does not already contain the extension, the adapter attempts a one-time runtime `INSTALL JSON; LOAD JSON;` on startup. When it cannot install or load the extension, it logs a warning explaining that JSON-dependent queries (such as `recall` and temporal search) will otherwise fail with `Extension: json ... has not been installed`. To resolve it, give the process network access at startup, use an image that already bundles the extension, or run `INSTALL json; LOAD json;` once against the database.

## API Mode (Shared Knowledge Graph)

To connect multiple clients to a shared knowledge graph, run MCP in API mode pointing to a centralized Cognee backend:

<Steps>
  <Step title="Start Cognee Backend">
    First, start a Cognee backend instance:

    ```bash theme={null}
    docker run -e LLM_API_KEY=your_api_key_here -p 8080:8000 --rm -it cognee/cognee:main
    ```
  </Step>

  <Step title="Start MCP in API Mode">
    Start the MCP server and point it to the backend:

    ```bash theme={null}
    docker run -e TRANSPORT_MODE=http -e API_URL=http://localhost:8080 -p 8000:8000 --rm -it cognee/cognee-mcp:main
    ```

    The container rewrites `localhost` / `127.0.0.1` in `API_URL` to a host-reachable address so the MCP container can reach a backend running on your host machine. The entrypoint auto-detects the address using the following fallback order: `host.docker.internal` (Docker Desktop), then `host.lima.internal` (Colima / Lima), then the container's default gateway IP (plain Linux Docker, typically `172.17.0.1`). If none resolve it keeps `host.docker.internal` and prints guidance. This means Docker Desktop, Colima, and plain Linux Docker generally work without manual configuration. The MCP server now acts as an interface to the shared backend.
  </Step>

  <Step title="Connect Additional Clients (Optional)">
    If you need to support multiple clients, start additional MCP instances on different ports:

    ```bash theme={null}
    docker run -e TRANSPORT_MODE=http -e API_URL=http://localhost:8080 -p 8001:8000 --rm -it cognee/cognee-mcp:main
    ```

    Each client connects to its own MCP instance, but all share the same knowledge graph through the backend.
  </Step>
</Steps>

<Note>
  * The API mode requires SSE or HTTP transport
  * If `API_URL` uses `localhost` / `127.0.0.1`, the container rewrites it to the first host address it can resolve: `host.docker.internal` (Docker Desktop), then `host.lima.internal` (Colima / Lima), then the default gateway IP (plain Linux Docker, typically `172.17.0.1`)
  * If auto-detection still fails, use `--network host` (Linux) or set `API_URL` to a bridge address such as `http://172.17.0.1:8000` directly; on Colima, start the VM with `colima start --network-address`
  * Add `-e API_TOKEN=your_token` if your backend requires authentication
  * For backend authentication setup and how to obtain a Bearer token, see [Deploy REST API Server](/guides/deploy-rest-api-server#authentication)
</Note>

## Docker Compose (Production Setup)

For production deployments, use Docker Compose to run the Cognee backend and MCP server together. This avoids `localhost` mapping issues and uses Docker's internal DNS for service discovery.

```yaml docker-compose.yml theme={null}
services:
  cognee-backend:
    image: cognee/cognee:main
    container_name: cognee-backend
    restart: unless-stopped
    ports:
      - "8080:8000"
    environment:
      LLM_API_KEY: "${LLM_API_KEY}"
      LLM_PROVIDER: "${LLM_PROVIDER:-openai}"
      LLM_MODEL: "${LLM_MODEL:-openai/gpt-5-mini}"
    volumes:
      - cognee_data:/app/data
    networks:
      - cognee_internal

  cognee-mcp:
    image: cognee/cognee-mcp:main
    container_name: cognee-mcp
    restart: unless-stopped
    ports:
      - "8000:8000"
    environment:
      TRANSPORT_MODE: "http"
      API_URL: "http://cognee-backend:8000"
      LLM_API_KEY: "${LLM_API_KEY}"
      LLM_PROVIDER: "${LLM_PROVIDER:-openai}"
      LLM_MODEL: "${LLM_MODEL:-openai/gpt-5-mini}"
    depends_on:
      - cognee-backend
    networks:
      - cognee_internal

volumes:
  cognee_data:

networks:
  cognee_internal:
    driver: bridge
```

<Info>
  **Networking notes:**

  * Use the **service name** (`cognee-backend`) as the hostname in `API_URL` — Docker resolves it automatically within the same network.
  * Use the **internal port** (`8000`) in `API_URL`, not the host-mapped port (`8080`).
  * If you place a reverse proxy (Nginx, Caddy) in front, you do **not** need to set a `Host: localhost` header — the backend accepts requests on any host.
  * Add `-e API_TOKEN=your_token` to the MCP service if your backend requires authentication.
</Info>

## Troubleshooting

<Accordion title="Graph queries fail with 'Extension: json ... has not been installed'">
  The default Ladybug graph store (Kuzu) downloads a JSON extension at startup, which some graph queries (such as recall and temporal search) rely on. In a network-restricted container, that download can fail and queries surface a cryptic `Extension: json ... has not been installed` Binder error.

  The published `cognee/cognee-mcp` image now bakes this extension in at build time, so pulling and running the latest image is enough. If you build the MCP image yourself, **rebuild it** after updating to pick up this change.

  When the extension still cannot be installed (for example, an offline container built without network access), the server now logs a clear warning at startup and attempts to install and load the extension directly on its database connection. To remediate, either give the process network access at startup, pre-install the extension in your image, or run `INSTALL json; LOAD json;` once against the database.
</Accordion>

## Connect to AI Clients

After starting the server, connect it to your AI development tool:

<CardGroup cols={3}>
  <Card title="Cursor" href="/cognee-mcp/integrations/cursor" icon="code">
    AI-powered code editor with native MCP support
  </Card>

  <Card title="Claude Code" href="/cognee-mcp/integrations/claude-code" icon="bot">
    Command-line AI assistant from Anthropic
  </Card>

  <Card title="Codex" href="/cognee-mcp/integrations/codex" icon="terminal">
    OpenAI coding agent with built-in MCP support
  </Card>
</CardGroup>

<CardGroup cols={3}>
  <Card title="Cline" href="/cognee-mcp/integrations/cline" icon="terminal">
    VS Code extension for AI-assisted development
  </Card>

  <Card title="Continue" href="/cognee-mcp/integrations/continue" icon="play">
    Open-source AI coding assistant
  </Card>

  <Card title="Python Agent" href="/cognee-mcp/integrations/python-agent" icon="python">
    Build your own MCP client
  </Card>
</CardGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Tools Reference" href="/cognee-mcp/mcp-tools" icon="wrench">
    See all available MCP tools and operations
  </Card>

  <Card title="Local Setup" href="/cognee-mcp/mcp-local-setup" icon="code">
    Run from source for customization and development
  </Card>
</CardGroup>