Update README.md to clarify Docker usage and transport mode configuration #1272
Conversation
Please make sure all the checkboxes are checked:
|
WalkthroughThe README for cognee-mcp was updated to switch Docker transport configuration from CLI flags to the TRANSPORT_MODE environment variable, add detailed SSE/HTTP client configuration examples and a Docker vs direct usage note, remove a Cursor IDE section, and adjust development steps and formatting. Changes
Sequence Diagram(s)sequenceDiagram
autonumber
actor User
participant Docker as Docker Container
participant Server as MCP Server
participant Client as MCP Client (Claude/Cursor)
rect rgb(235,245,255)
note over User,Docker: Start server with TRANSPORT_MODE env
User->>Docker: docker run -e TRANSPORT_MODE=sse|http ...
Docker->>Server: Start server with selected transport
note over Server: Server listens on SSE or HTTP
end
alt SSE transport
Client->>Server: Connect to SSE endpoint
Server-->>Client: Event stream / health responses
else HTTP transport
Client->>Server: HTTP requests (health, calls)
Server-->>Client: HTTP responses
end
note over Client,Server: Only enable the active server entry to avoid errors
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related PRs
Suggested labels
Suggested reviewers
Poem
Tip 🔌 Remote MCP (Model Context Protocol) integration is now available!Pro plan users can now connect to remote MCP servers from the Integrations page. Connect with popular remote MCPs such as Notion and Linear to add more context to your reviews and chats. ✨ Finishing Touches🧪 Generate unit tests
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. CodeRabbit Commands (Invoked using PR/Issue comments)Type Other keywords and placeholders
CodeRabbit Configuration File (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (6)
cognee-mcp/README.md (6)
106-111: Confirm container network binding (host accessibility).If the server inside the container binds to 127.0.0.1 by default, publishing -p 8000:8000 won’t expose it to the host. Please verify the HTTP/SSE server binds to 0.0.0.0 in Docker, and document how to adjust it if needed (e.g., via an env var or image entrypoint default).
I can update the README with a short “Troubleshooting: port not reachable” note once you confirm the binding behavior for the image.
122-131: Minor copy edit: hyphenate “command-line”.Improves readability/consistency and addresses the linter nits.
-**Docker uses environment variables**, not command line arguments: +**Docker uses environment variables**, not command-line arguments: @@ -**Direct Python usage** uses command line arguments: +**Direct Python usage** uses command-line arguments:
156-160: Add a language to the fenced block (fixes MD040).Declare the block as text/console to satisfy markdownlint and improve rendering.
-``` +```text Checking MCP server health... cognee-sse: http://localhost:8000/sse (SSE) - ✓ Connected -``` +```
206-211: Add a language to the fenced block (fixes MD040).Same as above for the HTTP example.
-``` +```text Checking MCP server health... cognee-http: http://localhost:8000/mcp (HTTP) - ✓ Connected -``` +```
176-185: Align Cursor config examples: include “type” consistently.Cursor examples omit the “type” while the dual example includes it. Recommend adding “type” to the Cursor SSE/HTTP examples for consistency and to reduce user confusion.
Apply to SSE Cursor example:
{ "mcpServers": { "cognee-sse": { + "type": "sse", "url": "http://localhost:8000/sse" } } }Apply to HTTP Cursor example:
{ "mcpServers": { "cognee-http": { + "type": "http", "url": "http://localhost:8000/mcp" } } }No change needed to the dual example; it’s already explicit.
If Cursor intentionally infers transport type from URL and “type” is unnecessary, consider removing “type” from the dual example instead to keep all Cursor examples uniform. I can update either direction once confirmed.
Also applies to: 227-236, 242-254
313-313: Minor grammar tweak.Add the article for smoother reading.
-1. Update dependencies in cognee folder if needed +1. Update dependencies in the cognee folder if needed
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
💡 Knowledge Base configuration:
- MCP integration is disabled by default for public repositories
- Jira integration is disabled by default for public repositories
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (1)
cognee-mcp/README.md(3 hunks)
🧰 Additional context used
🪛 LanguageTool
cognee-mcp/README.md
[grammar] ~122-~122: There might be a mistake here.
Context: ... ### Important: Docker vs Direct Usage Docker uses environment variables, not...
(QB_NEW_EN)
[grammar] ~123-~123: There might be a mistake here.
Context: ...variables**, not command line arguments: - ✅ Docker: -e TRANSPORT_MODE=http - ❌ D...
(QB_NEW_EN)
[grammar] ~124-~124: There might be a mistake here.
Context: ...not command line arguments: - ✅ Docker: -e TRANSPORT_MODE=http - ❌ Docker: --transport http (won't work...
(QB_NEW_EN)
[grammar] ~127-~127: There might be a mistake here.
Context: ...hon usage** uses command line arguments: - ✅ Direct: `python src/server.py --transp...
(QB_NEW_EN)
[grammar] ~128-~128: There might be a mistake here.
Context: ...ses command line arguments: - ✅ Direct: python src/server.py --transport http - ❌ Direct: -e TRANSPORT_MODE=http (won'...
(QB_NEW_EN)
[grammar] ~132-~132: There might be a mistake here.
Context: ...t work) ## 🔗 MCP Client Configuration After starting your Cognee MCP server wit...
(QB_NEW_EN)
[grammar] ~238-~238: There might be a mistake here.
Context: ... } ``` ### Dual Configuration Example You can configure both transports simult...
(QB_NEW_EN)
[grammar] ~258-~258: There might be a mistake here.
Context: ...id connection errors. ## 💻 Basic Usage The MCP server exposes its functionality ...
(QB_NEW_EN)
[grammar] ~313-~313: There might be a mistake here.
Context: ...you need to do: 1. Update dependencies in cognee folder if needed 2. `uv sync --d...
(QB_NEW_EN)
🪛 markdownlint-cli2 (0.17.2)
cognee-mcp/README.md
156-156: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
207-207: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (16)
- GitHub Check: Basic Tests / Run Basic Graph Tests
- GitHub Check: Basic Tests / Run Simple Examples
- GitHub Check: Basic Tests / Run Formatting Check
- GitHub Check: Basic Tests / Run Unit Tests
- GitHub Check: End-to-End Tests / Deletion Test
- GitHub Check: Basic Tests / Run Simple Examples BAML
- GitHub Check: Basic Tests / Run Integration Tests
- GitHub Check: End-to-End Tests / Run Telemetry Pipeline Test
- GitHub Check: Basic Tests / Run Linting
- GitHub Check: End-to-End Tests / Test permissions with different situations in Cognee
- GitHub Check: End-to-End Tests / S3 Bucket Test
- GitHub Check: End-to-End Tests / Test graph edge ingestion
- GitHub Check: End-to-End Tests / Deduplication Test
- GitHub Check: End-to-End Tests / Test using different async databases in parallel in Cognee
- GitHub Check: End-to-End Tests / Server Start Test
- GitHub Check: End-to-End Tests / Run Telemetry Test
🔇 Additional comments (2)
cognee-mcp/README.md (2)
115-120: Mirror the host-binding note for the Docker Hub image.Same concern as above applies to the pulled image: ensure it listens on 0.0.0.0 in the container so the mapped port is reachable from the host.
294-294: Good clarifying tip.Calling out CODE search type for code graphs is helpful.
There was a problem hiding this comment.
Actionable comments posted: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
cognee-mcp/README.md (1)
59-66: Correct UV installation method (pip install is misleading/incorrect).Astral’s uv is not installed via pip. The recommended install is the official shell/Powershell script; otherwise users will get the wrong package or a broken setup.
Apply this diff to fix Step 3:
-3. Install uv if you don't have one - ``` - pip install uv - ``` +3. Install uv if you don't have it installed + - macOS/Linux: + ```bash + curl -LsSf https://astral.sh/uv/install.sh | sh + ``` + - Windows (PowerShell): + ```powershell + irm https://astral.sh/uv/install.ps1 | iex + ``` + - Verify: + ```bash + uv --version + ```
🧹 Nitpick comments (5)
cognee-mcp/README.md (5)
106-111: Clarify/verify server defaults and env overrides for HTTP/SSE in Docker.Examples assume the container listens on 0.0.0.0:8000, HTTP path “/mcp” and SSE path “/sse”. If these differ, clients will fail. Recommend documenting HOST/PORT/PATH envs (if supported) and confirming defaults.
Consider adding a short note under each docker run example stating:
- Defaults: HOST=0.0.0.0, PORT=8000, HTTP_PATH=/mcp, SSE_PATH=/sse
- How to override with env vars (if supported), e.g.:
-e HOST=0.0.0.0 -e PORT=8000 -e HTTP_PATH=/mcp -e SSE_PATH=/sseIf these envs aren’t wired up in the image, either remove the suggestion or add support in the entrypoint.
Example doc tweak within these blocks:
# For HTTP transport (recommended for web deployments) - docker run -e TRANSPORT_MODE=http --env-file ./.env -p 8000:8000 --rm -it cognee/cognee-mcp:main + docker run \ + -e TRANSPORT_MODE=http \ + -e HOST=0.0.0.0 -e PORT=8000 -e HTTP_PATH=/mcp \ + --env-file ./.env -p 8000:8000 --rm -it cognee/cognee-mcp:main # For SSE transport - docker run -e TRANSPORT_MODE=sse --env-file ./.env -p 8000:8000 --rm -it cognee/cognee-mcp:main + docker run \ + -e TRANSPORT_MODE=sse \ + -e HOST=0.0.0.0 -e PORT=8000 -e SSE_PATH=/sse \ + --env-file ./.env -p 8000:8000 --rm -it cognee/cognee-mcp:main # For stdio transport (default) docker run -e TRANSPORT_MODE=stdio --env-file ./.env --rm -it cognee/cognee-mcp:mainPlease verify the entrypoint actually reads these envs (or adjust names accordingly) before merging. I can help patch the Dockerfile/entrypoint if needed.
Also applies to: 115-120
122-130: Hyphenate “command-line” and minor copy edits in the Important note.Small grammar polish for clarity and consistency.
Apply this diff:
-### **Important: Docker vs Direct Usage** -**Docker uses environment variables**, not command line arguments: +### **Important: Docker vs Direct Usage** +**Docker uses environment variables**, not command-line arguments: - ✅ Docker: `-e TRANSPORT_MODE=http` - ❌ Docker: `--transport http` (won't work) -**Direct Python usage** uses command line arguments: +**Direct Python usage** uses command-line arguments: - ✅ Direct: `python src/server.py --transport http` - ❌ Direct: `-e TRANSPORT_MODE=http` (won't work)
156-160: Add a code fence language to satisfy markdownlint (MD040).The output block is missing a language. Use “text” for console output.
Apply this diff:
-``` +```text Checking MCP server health... cognee-sse: http://localhost:8000/sse (SSE) - ✓ Connected--- `206-211`: **Add a code fence language to satisfy markdownlint (MD040).** Same linter issue as above; specify a language. Apply this diff: ```diff -``` +```text Checking MCP server health... cognee-http: http://localhost:8000/mcp (HTTP) - ✓ Connected--- `311-311`: **Minor grammar: add article for readability.** Apply this diff: ```diff -1. Update dependencies in cognee folder if needed +1. Update dependencies in the cognee folder if needed
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
💡 Knowledge Base configuration:
- MCP integration is disabled by default for public repositories
- Jira integration is disabled by default for public repositories
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (1)
cognee-mcp/README.md(2 hunks)
🧰 Additional context used
🪛 LanguageTool
cognee-mcp/README.md
[grammar] ~122-~122: There might be a mistake here.
Context: ... ### Important: Docker vs Direct Usage Docker uses environment variables, not...
(QB_NEW_EN)
[grammar] ~123-~123: There might be a mistake here.
Context: ...variables**, not command line arguments: - ✅ Docker: -e TRANSPORT_MODE=http - ❌ D...
(QB_NEW_EN)
[grammar] ~124-~124: There might be a mistake here.
Context: ...not command line arguments: - ✅ Docker: -e TRANSPORT_MODE=http - ❌ Docker: --transport http (won't work...
(QB_NEW_EN)
[grammar] ~127-~127: There might be a mistake here.
Context: ...hon usage** uses command line arguments: - ✅ Direct: `python src/server.py --transp...
(QB_NEW_EN)
[grammar] ~128-~128: There might be a mistake here.
Context: ...ses command line arguments: - ✅ Direct: python src/server.py --transport http - ❌ Direct: -e TRANSPORT_MODE=http (won'...
(QB_NEW_EN)
[grammar] ~132-~132: There might be a mistake here.
Context: ...t work) ## 🔗 MCP Client Configuration After starting your Cognee MCP server wit...
(QB_NEW_EN)
[grammar] ~238-~238: There might be a mistake here.
Context: ... } ``` ### Dual Configuration Example You can configure both transports simult...
(QB_NEW_EN)
[grammar] ~258-~258: There might be a mistake here.
Context: ...id connection errors. ## 💻 Basic Usage The MCP server exposes its functionality ...
(QB_NEW_EN)
[grammar] ~311-~311: There might be a mistake here.
Context: ...you need to do: 1. Update dependencies in cognee folder if needed 2. `uv sync --d...
(QB_NEW_EN)
🪛 markdownlint-cli2 (0.17.2)
cognee-mcp/README.md
156-156: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
207-207: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (16)
- GitHub Check: End-to-End Tests / S3 Bucket Test
- GitHub Check: End-to-End Tests / Deduplication Test
- GitHub Check: End-to-End Tests / Test graph edge ingestion
- GitHub Check: End-to-End Tests / Test permissions with different situations in Cognee
- GitHub Check: End-to-End Tests / Deletion Test
- GitHub Check: Basic Tests / Run Basic Graph Tests
- GitHub Check: End-to-End Tests / Test using different async databases in parallel in Cognee
- GitHub Check: End-to-End Tests / Run Telemetry Pipeline Test
- GitHub Check: End-to-End Tests / Run Telemetry Test
- GitHub Check: End-to-End Tests / Server Start Test
- GitHub Check: Basic Tests / Run Simple Examples
- GitHub Check: Basic Tests / Run Formatting Check
- GitHub Check: Basic Tests / Run Linting
- GitHub Check: Basic Tests / Run Simple Examples BAML
- GitHub Check: Basic Tests / Run Integration Tests
- GitHub Check: Basic Tests / Run Unit Tests
🔇 Additional comments (3)
cognee-mcp/README.md (3)
187-236: HTTP section looks good; mirror the syntax/version note as with SSE.Content is clear and correct assuming defaults. Once the Claude CLI syntax is verified in the SSE section, mirror any required version note here for consistency.
238-256: Dual configuration example is clear; good cautionary note.The example JSON and the note about enabling only the running server are helpful.
132-256: Overall: Excellent clarity on Docker vs direct usage and client configs.The new sections significantly improve onboarding and reduce configuration footguns. Once the UV install and minor lints are fixed, this will be very solid.
| #### **Claude CLI (Easiest)** | ||
| ```bash | ||
| claude mcp add cognee-sse -t sse http://localhost:8000/sse | ||
| ``` | ||
|
|
There was a problem hiding this comment.
💡 Verification agent
🧩 Analysis chain
Confirm current Claude CLI syntax for adding MCP servers.
CLI interfaces change. Please verify that claude mcp add <name> -t sse <url> matches the current Claude CLI version you target.
Run this web check to confirm the latest syntax and, if needed, include a minimal supported version note in the README:
🌐 Web query:
What is the current syntax for adding an MCP server in the Claude CLI (command: "claude mcp add") and the valid transport type flags for SSE and HTTP?
💡 Result:
The current syntax to add an MCP server in the Claude CLI is:
claude mcp add [options] <name> <commandOrUrl> [args...]-
For a typical case:
claude mcp add github --scope user -
To explicitly specify transport type, use
-tor--transport:- Example (SSE):
claude mcp add myserver --transport sse -- npx my-server --flag - Example (HTTP, for a remote server):
claude mcp add myserver --transport http --url http://localhost:8000/mcp[3][8][5][6].
- Example (SSE):
Valid Transport Type Flags
The primary valid values for the --transport flag are:
- stdio (default)
- sse
- http
Usage examples:
- For SSE:
claude mcp add myserver -t sse --url http://localhost:8080/mcp
- For HTTP:
claude mcp add myserver -t http --url http://localhost:8000/mcp
- For stdio:
claude mcp add myserver -t stdio -- npx my-stdio-mcp-server[3][8][6].
Notes on related options:
--env KEY=valuesets environment variables.--header X-Api-Key:foobarsets HTTP headers (for SSE or HTTP)[3].--scopecontrols scope (local,user,project; defaults tolocal)[3][1].
References to Docs:
- Configurable via direct edits to
claude_desktop_config.jsonor by importing from Claude Desktop[1][2].
Summary Table: Valid Transport Types
| Flag Value | Description | When to Use |
|---|---|---|
| stdio | Local process, default for CLI tools | For local scripts |
| sse | Server-Sent Events (push updates) | For event streams |
| http | Standard HTTP API endpoint | For web servers |
If using JSON to add a server:
claude mcp add-json <name> '{"type":"sse"|"http"|"stdio", ... }'This configures the transport type explicitly in the JSON object[5][3][6].
Citations:
- 1: https://mcpcat.io/guides/adding-an-mcp-server-to-claude-code/
- 2: https://appwrite.io/docs/tooling/mcp/claude
- 3: https://notes.dsebastien.net/30+Areas/33+Permanent+notes/33.02+Content/Claude+Code
- 4: https://github.com/zilliztech/claude-context
- 5: https://docs.anthropic.com/en/docs/claude-code/mcp
- 6: https://github.com/alpacahq/alpaca-mcp-server
- 7: https://www.danliden.com/posts/20250412-mcp-quickstart.html
- 8: https://www.devshorts.in/p/claude-code-the-complete-guide-for
- 9: https://github.com/microsoft/playwright-mcp
- 10: https://www.anthropic.com/engineering/desktop-extensions
Update README to use official claude mcp add syntax
The snippet on lines 145–149 should explicitly include the --url flag for HTTP/SSE transports and use the correct --transport (or -t) option. For example:
claude mcp add cognee-sse --transport sse --url http://localhost:8000/sseAnd for HTTP:
claude mcp add cognee-http --transport http --url http://localhost:8000/mcp• Replace the existing
claude mcp add cognee-sse -t sse http://localhost:8000/ssewith the first example above.
• Add a note that --transport supports stdio (default), sse, and http.
• Optionally mention the equivalent short flag (-t) and related options (--env, --header, --scope) for completeness.
🤖 Prompt for AI Agents
In cognee-mcp/README.md around lines 145 to 149, the Claude CLI example uses an
incomplete invocation; replace the current snippet with a version that
explicitly passes the --transport and --url flags (e.g., "claude mcp add
cognee-sse --transport sse --url http://localhost:8000/sse"), and add a short
note that --transport supports stdio (default), sse, and http plus the
equivalent short flag -t and related options (--env, --header, --scope) so
readers know the available transports and common flags.
Description
Rendered README
DCO Affirmation
I affirm that all code in every commit of this pull request conforms to the terms of the Topoteretes Developer Certificate of Origin.