topoteretes · Vasilije1990 · Oct 12, 2025 · Oct 8, 2025 · Oct 8, 2025 · Oct 9, 2025
diff --git a/cognee-mcp/Dockerfile b/cognee-mcp/Dockerfile
@@ -65,6 +65,9 @@ ENV PYTHONUNBUFFERED=1
 ENV MCP_LOG_LEVEL=DEBUG
 ENV PYTHONPATH=/app
 
+# Add labels for API mode usage
+LABEL org.opencontainers.image.description="Cognee MCP Server with API mode support"
+
 # Use the application name from pyproject.toml for normal operation
 # For testing, we'll override this with a direct command
 ENTRYPOINT ["/app/entrypoint.sh"]
diff --git a/cognee-mcp/README.md b/cognee-mcp/README.md
@@ -38,7 +38,8 @@ Build memory for Agents and query from any client that speaks MCP – in your t
 ## ✨ Features
 
 - Multiple transports – choose Streamable HTTP --transport http (recommended for web deployments), SSE --transport sse (real‑time streaming), or stdio (classic pipe, default)
-- Integrated logging – all actions written to a rotating file (see get_log_file_location()) and mirrored to console in dev
+- **API Mode** – connect to an already running Cognee FastAPI server instead of using cognee directly (see [API Mode](#-api-mode) below)
+- Integrated logging – all actions written to a rotating file (see get_log_file_location()) and mirrored to console in dev
 - Local file ingestion – feed .md, source files, Cursor rule‑sets, etc. straight from disk
 - Background pipelines – long‑running cognify & codify jobs spawn off‑thread; check progress with status tools
 - Developer rules bootstrap – one call indexes .cursorrules, .cursor/rules, AGENT.md, and friends into the developer_rules nodeset
@@ -91,7 +92,7 @@ To use different LLM providers / database configurations, and for more info chec
 
 ## 🐳 Docker Usage
 
-If you’d rather run cognee-mcp in a container, you have two options:
+If you'd rather run cognee-mcp in a container, you have two options:
 
 1. **Build locally**
    1. Make sure you are in /cognee root directory and have a fresh `.env` containing only your `LLM_API_KEY` (and your chosen settings).
@@ -128,6 +129,64 @@ If you’d rather run cognee-mcp in a container, you have two options:
 - ✅ Direct: `python src/server.py --transport http`
 - ❌ Direct: `-e TRANSPORT_MODE=http` (won't work)
 
+### **Docker API Mode**
+
+To connect the MCP Docker container to a Cognee API server running on your host machine:
+
+#### **Simple Usage (Automatic localhost handling):**
+```bash
+# Start your Cognee API server on the host
+python -m cognee.api.client
+
+# Run MCP container in API mode - localhost is automatically converted!
+docker run \
+  -e TRANSPORT_MODE=sse \
+  -e API_URL=http://localhost:8000 \
+  -e API_TOKEN=your_auth_token \
+  -p 8001:8000 \
+  --rm -it cognee/cognee-mcp:main
+```
+**Note:** The container will automatically convert `localhost` to `host.docker.internal` on Mac/Windows/Docker Desktop. You'll see a message in the logs showing the conversion.
+
+#### **Explicit host.docker.internal (Mac/Windows):**
+```bash
+# Or explicitly use host.docker.internal
+docker run \
+  -e TRANSPORT_MODE=sse \
+  -e API_URL=http://host.docker.internal:8000 \
+  -e API_TOKEN=your_auth_token \
+  -p 8001:8000 \
+  --rm -it cognee/cognee-mcp:main
+```
+
+#### **On Linux (use host network or container IP):**
+```bash
+# Option 1: Use host network (simplest)
+docker run \
+  --network host \
+  -e TRANSPORT_MODE=sse \
+  -e API_URL=http://localhost:8000 \
+  -e API_TOKEN=your_auth_token \
+  --rm -it cognee/cognee-mcp:main
+
+# Option 2: Use host IP address
+# First, get your host IP: ip addr show docker0
+docker run \
+  -e TRANSPORT_MODE=sse \
+  -e API_URL=http://172.17.0.1:8000 \
+  -e API_TOKEN=your_auth_token \
+  -p 8001:8000 \
+  --rm -it cognee/cognee-mcp:main
+```
+
+**Environment variables for API mode:**
+- `API_URL`: URL of the running Cognee API server
+- `API_TOKEN`: Authentication token (optional, required if API has authentication enabled)
+
+**Note:** When running in API mode:
+- Database migrations are automatically skipped (API server handles its own DB)
+- Some features are limited (see [API Mode Limitations](#-api-mode))
+
 
 ## 🔗 MCP Client Configuration
 
@@ -255,6 +314,76 @@ You can configure both transports simultaneously for testing:
 
 **Note:** Only enable the server you're actually running to avoid connection errors.
 
+## 🌐 API Mode
+
+The MCP server can operate in two modes:
+
+### **Direct Mode** (Default)
+The MCP server directly imports and uses the cognee library. This is the default mode with full feature support.
+
+### **API Mode**
+The MCP server connects to an already running Cognee FastAPI server via HTTP requests. This is useful when:
+- You have a centralized Cognee API server running
+- You want to separate the MCP server from the knowledge graph backend
+- You need multiple MCP servers to share the same knowledge graph
+
+**Starting the MCP server in API mode:**
+```bash
+# Start your Cognee FastAPI server first (default port 8000)
+cd /path/to/cognee
+python -m cognee.api.client
+
+# Then start the MCP server in API mode
+cd cognee-mcp
+python src/server.py --api-url http://localhost:8000 --api-token YOUR_AUTH_TOKEN
+```
+
+**API Mode with different transports:**
+```bash
+# With SSE transport
+python src/server.py --transport sse --api-url http://localhost:8000 --api-token YOUR_TOKEN
+
+# With HTTP transport
+python src/server.py --transport http --api-url http://localhost:8000 --api-token YOUR_TOKEN
+```
+
+**API Mode with Docker:**
+```bash
+# On Mac/Windows (use host.docker.internal to access host)
+docker run \
+  -e TRANSPORT_MODE=sse \
+  -e API_URL=http://host.docker.internal:8000 \
+  -e API_TOKEN=YOUR_TOKEN \
+  -p 8001:8000 \
+  --rm -it cognee/cognee-mcp:main
+
+# On Linux (use host network)
+docker run \
+  --network host \
+  -e TRANSPORT_MODE=sse \
+  -e API_URL=http://localhost:8000 \
+  -e API_TOKEN=YOUR_TOKEN \
+  --rm -it cognee/cognee-mcp:main
+```
+
+**Command-line arguments for API mode:**
+- `--api-url`: Base URL of the running Cognee FastAPI server (e.g., `http://localhost:8000`)
+- `--api-token`: Authentication token for the API (optional, required if API has authentication enabled)
+
+**Docker environment variables for API mode:**
+- `API_URL`: Base URL of the running Cognee FastAPI server
+- `API_TOKEN`: Authentication token (optional, required if API has authentication enabled)
+
+**API Mode limitations:**
+Some features are only available in direct mode:
+- `codify` (code graph pipeline)
+- `cognify_status` / `codify_status` (pipeline status tracking)
+- `prune` (data reset)
+- `get_developer_rules` (developer rules retrieval)
+- `list_data` with specific dataset_id (detailed data listing)
+
+Basic operations like `cognify`, `search`, `delete`, and `list_data` (all datasets) work in both modes.
+
 ## 💻 Basic Usage
 
 The MCP server exposes its functionality through tools. Call them from any MCP client (Cursor, Claude Desktop, Cline, Roo and more).

diff --git a/cognee-mcp/entrypoint.sh b/cognee-mcp/entrypoint.sh
@@ -14,61 +14,94 @@ HTTP_PORT=${HTTP_PORT:-8000}
 echo "Debug port: $DEBUG_PORT"
 echo "HTTP port: $HTTP_PORT"
 
-# Run Alembic migrations with proper error handling.
-# Note on UserAlreadyExists error handling:
-# During database migrations, we attempt to create a default user. If this user
-# already exists (e.g., from a previous deployment or migration), it's not a
-# critical error and shouldn't prevent the application from starting. This is
-# different from other migration errors which could indicate database schema
-# inconsistencies and should cause the startup to fail. This check allows for
-# smooth redeployments and container restarts while maintaining data integrity.
-echo "Running database migrations..."
+# Check if API mode is enabled
+if [ -n "$API_URL" ]; then
+    echo "API mode enabled: $API_URL"
+    echo "Skipping database migrations (API server handles its own database)"
+else
+    echo "Direct mode: Using local cognee instance"
+    # Run Alembic migrations with proper error handling.
+    # Note on UserAlreadyExists error handling:
+    # During database migrations, we attempt to create a default user. If this user
+    # already exists (e.g., from a previous deployment or migration), it's not a
+    # critical error and shouldn't prevent the application from starting. This is
+    # different from other migration errors which could indicate database schema
+    # inconsistencies and should cause the startup to fail. This check allows for
+    # smooth redeployments and container restarts while maintaining data integrity.
+    echo "Running database migrations..."
 
-MIGRATION_OUTPUT=$(alembic upgrade head)
-MIGRATION_EXIT_CODE=$?
+    MIGRATION_OUTPUT=$(alembic upgrade head)
+    MIGRATION_EXIT_CODE=$?
 
-if [[ $MIGRATION_EXIT_CODE -ne 0 ]]; then
-    if [[ "$MIGRATION_OUTPUT" == *"UserAlreadyExists"* ]] || [[ "$MIGRATION_OUTPUT" == *"User [email protected] already exists"* ]]; then
-        echo "Warning: Default user already exists, continuing startup..."
-    else
-        echo "Migration failed with unexpected error."
-        exit 1
+    if [[ $MIGRATION_EXIT_CODE -ne 0 ]]; then
+        if [[ "$MIGRATION_OUTPUT" == *"UserAlreadyExists"* ]] || [[ "$MIGRATION_OUTPUT" == *"User [email protected] already exists"* ]]; then
+            echo "Warning: Default user already exists, continuing startup..."
+        else
+            echo "Migration failed with unexpected error."
+            exit 1
+        fi
     fi
-fi
 
-echo "Database migrations done."
+    echo "Database migrations done."
+fi
 
 echo "Starting Cognee MCP Server with transport mode: $TRANSPORT_MODE"
 
 # Add startup delay to ensure DB is ready
 sleep 2
 
+# Build API arguments if API_URL is set
+API_ARGS=""
+if [ -n "$API_URL" ]; then
+    # Handle localhost in API_URL - convert to host-accessible address
+    if echo "$API_URL" | grep -q "localhost" || echo "$API_URL" | grep -q "127.0.0.1"; then
+        echo "⚠️  Warning: API_URL contains localhost/127.0.0.1"
+        echo "   Original: $API_URL"
+
+        # Try to use host.docker.internal (works on Mac/Windows and recent Linux with Docker Desktop)
+        FIXED_API_URL=$(echo "$API_URL" | sed 's/localhost/host.docker.internal/g' | sed 's/127\.0\.0\.1/host.docker.internal/g')
+
+        echo "   Converted to: $FIXED_API_URL"
+        echo "   This will work on Mac/Windows/Docker Desktop."
+        echo "   On Linux without Docker Desktop, you may need to:"
+        echo "     - Use --network host, OR"
+        echo "     - Set API_URL=http://172.17.0.1:8000 (Docker bridge IP)"
+
+        API_URL="$FIXED_API_URL"
+    fi
+
+    API_ARGS="--api-url $API_URL"
+    if [ -n "$API_TOKEN" ]; then
+        API_ARGS="$API_ARGS --api-token $API_TOKEN"
+    fi
+fi
+
 # Modified startup with transport mode selection and error handling
 if [ "$ENVIRONMENT" = "dev" ] || [ "$ENVIRONMENT" = "local" ]; then
     if [ "$DEBUG" = "true" ]; then
         echo "Waiting for the debugger to attach..."
         if [ "$TRANSPORT_MODE" = "sse" ]; then
-            exec python -m debugpy --wait-for-client --listen 0.0.0.0:$DEBUG_PORT -m cognee-mcp --transport sse --host 0.0.0.0 --port $HTTP_PORT --no-migration
+            exec python -m debugpy --wait-for-client --listen 0.0.0.0:$DEBUG_PORT -m cognee-mcp --transport sse --host 0.0.0.0 --port $HTTP_PORT --no-migration $API_ARGS
         elif [ "$TRANSPORT_MODE" = "http" ]; then
-            exec python -m debugpy --wait-for-client --listen 0.0.0.0:$DEBUG_PORT -m cognee-mcp --transport http --host 0.0.0.0 --port $HTTP_PORT --no-migration
+            exec python -m debugpy --wait-for-client --listen 0.0.0.0:$DEBUG_PORT -m cognee-mcp --transport http --host 0.0.0.0 --port $HTTP_PORT --no-migration $API_ARGS
         else
-            exec python -m debugpy --wait-for-client --listen 0.0.0.0:$DEBUG_PORT -m cognee-mcp --transport stdio --no-migration
+            exec python -m debugpy --wait-for-client --listen 0.0.0.0:$DEBUG_PORT -m cognee-mcp --transport stdio --no-migration $API_ARGS
         fi
     else
         if [ "$TRANSPORT_MODE" = "sse" ]; then
-            exec cognee-mcp --transport sse --host 0.0.0.0 --port $HTTP_PORT --no-migration
+            exec cognee-mcp --transport sse --host 0.0.0.0 --port $HTTP_PORT --no-migration $API_ARGS
         elif [ "$TRANSPORT_MODE" = "http" ]; then
-            exec cognee-mcp --transport http --host 0.0.0.0 --port $HTTP_PORT --no-migration
+            exec cognee-mcp --transport http --host 0.0.0.0 --port $HTTP_PORT --no-migration $API_ARGS
         else
-            exec cognee-mcp --transport stdio --no-migration
+            exec cognee-mcp --transport stdio --no-migration $API_ARGS
         fi
     fi
 else
     if [ "$TRANSPORT_MODE" = "sse" ]; then
-        exec cognee-mcp --transport sse --host 0.0.0.0 --port $HTTP_PORT --no-migration
+        exec cognee-mcp --transport sse --host 0.0.0.0 --port $HTTP_PORT --no-migration $API_ARGS
     elif [ "$TRANSPORT_MODE" = "http" ]; then
-        exec cognee-mcp --transport http --host 0.0.0.0 --port $HTTP_PORT --no-migration
+        exec cognee-mcp --transport http --host 0.0.0.0 --port $HTTP_PORT --no-migration $API_ARGS
     else
-        exec cognee-mcp --transport stdio --no-migration
+        exec cognee-mcp --transport stdio --no-migration $API_ARGS
     fi
 fi
diff --git a/cognee-mcp/pyproject.toml b/cognee-mcp/pyproject.toml
@@ -13,6 +13,7 @@ dependencies = [
     "fastmcp>=2.10.0,<3.0.0",
     "mcp>=1.12.0,<2.0.0",
     "uv>=0.6.3,<1.0.0",
+    "httpx>=0.27.0,<1.0.0",
 ]
 
 authors = [

diff --git a/cognee-mcp/src/__init__.py b/cognee-mcp/src/__init__.py
@@ -1,4 +1,7 @@
-from .server import main as server_main
+try:
+    from .server import main as server_main
+except ImportError:
+    from server import main as server_main
 import warnings
 import sys