docs: view reverse proxy guide and examples#1149
Conversation
|
Warning Rate limit exceeded@MicBun has exceeded the limit for the number of commits or files that can be reviewed per hour. Please wait 3 minutes and 47 seconds before requesting another review. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. 📒 Files selected for processing (5)
WalkthroughAdds comprehensive documentation and examples for running the MCP server over SSE behind reverse proxies. Updates main README with a link. Introduces a reverse proxy guide, Windows testing guide, expanded MCP server docs for SSE, and multiple example configs for Nginx, Caddy (incl. Windows), Traefik, and Docker Compose. Changes
Sequence Diagram(s)sequenceDiagram
autonumber
actor User as MCP Client (e.g., Claude Desktop)
participant MR as mcp-remote (SSE proxy client)
participant RP as Reverse Proxy (Nginx/Caddy/Traefik)
participant MS as MCP Server (SSE)
participant DB as Postgres
User->>MR: Start MCP server via npx mcp-remote <URL>/sse
MR->>RP: HTTP GET /sse (SSE)\nHeaders: Host, X-Forwarded-*
note over RP: Disable buffering, use HTTP/1.1, no caching
RP->>MS: Proxy /sse to http://mcp:8000/sse
MS-->>RP: 200 OK + event-stream\n(continuous)
RP-->>MR: Stream events (SSE)
MR-->>User: Tools, prompts, results (via MCP)
MS->>DB: Queries (on demand)
DB-->>MS: Results
alt Health check
RP->>MS: GET /health
MS-->>RP: 200 OK
else Error
MS-->>RP: 5xx / timeout
RP-->>MR: Error response / disconnect
MR-->>User: Surface error
end
%% Styling notes: new/changed flow focuses on SSE through proxy
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
Pre-merge checks (4 passed, 1 inconclusive)❌ Failed checks (1 inconclusive)
✅ Passed checks (4 passed)
Poem
✨ 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. Comment |
This commit implements comprehensive MCP server reverse proxy documentation with complete Windows native support and multi-platform deployment guides. **New Documentation:** - Complete reverse proxy configuration guide (mcp-reverse-proxy.md) - Production-ready MCP server documentation (mcp-server.md) - Comprehensive Windows testing guide (windows-mcp-testing.md) - Full examples directory with configuration files **Multi-Platform Support:** - Nginx, Caddy, Traefik, HAProxy reverse proxy configurations - Claude Desktop, Cursor, Cline, Windsurf client configurations - Windows PowerShell, Linux bash, macOS deployment instructions - Docker Compose and native installation methods This documentation enables enterprise users to successfully deploy and test MCP server functionality with reverse proxy support. resolves: trufnetwork/truf-network#1177 resolves: trufnetwork/truf-network#1178
MicBun
force-pushed
the
reverseProxy
branch
from
e3d3ba1 to
9d10ab8
Compare
Time Submission Status
|
![coderabbitai[bot]](https://waps.l3s.uni-hannover.de/live/im_/https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 12
🧹 Nitpick comments (11)
docs/examples/mcp-reverse-proxy/Caddyfile.windows.example (3)
26-30: Switch away from deprecated ‘single_field’ log encoder.The single_field encoder is deprecated; prefer json (built-in) or the format-encoder plugin for CLF. (i.scwy.net)
log { - output file caddy-access.log - format single_field common_log + output file caddy-access.log + format json }
33-53: Update security headers (drop X-XSS-Protection; consider CSP frame-ancestors).X-XSS-Protection is deprecated and may introduce issues; prefer CSP, and use frame-ancestors over X-Frame-Options for modern browsers. (web.nodejs.cn, github.com, centralcsp.com)
-# header { -# X-Frame-Options DENY -# X-Content-Type-Options nosniff -# X-XSS-Protection "1; mode=block" -# Strict-Transport-Security "max-age=31536000; includeSubDomains" -# } +# header { +# Content-Security-Policy "frame-ancestors 'none'" +# X-Content-Type-Options nosniff +# Strict-Transport-Security "max-age=31536000; includeSubDomains" +# # Intentionally omit deprecated X-XSS-Protection +# }
55-60: Improve curl SSE test command.Add -N to disable curl buffering and include Cache-Control header for a closer real‑client behavior.
-# 4. Test: curl.exe -H "Accept: text/event-stream" http://127.0.0.1:8080/sse +# 4. Test: curl.exe -N -H "Accept: text/event-stream" -H "Cache-Control: no-cache" http://127.0.0.1:8080/ssedocs/examples/mcp-reverse-proxy/Caddyfile.example (2)
15-29: Tighten matcher and drop redundant header overrides; note flush_interval behavior.
- Use an explicit matcher for both /sse and /sse/*.
- Remove header_up Host/X-Forwarded-*; Caddy sets these by default.
- flush_interval -1 is optional; Caddy streams text/event-stream without buffering. (caddyserver.com, scwy.net, caddy.dev.org.tw)
- reverse_proxy /sse/* localhost:8000 { - # Caddy handles SSE automatically, but these settings ensure optimal performance - flush_interval -1 - - # Headers - header_up Host {http.reverse_proxy.upstream.hostport} - header_up X-Real-IP {http.request.remote} - header_up X-Forwarded-Proto {http.request.scheme} - header_up X-Forwarded-Port {http.request.port} - - # Optional: Health checks - health_uri /health - health_interval 30s - health_timeout 5s - } + @sse path /sse /sse/* + reverse_proxy @sse localhost:8000 { + # flush_interval -1 # optional for SSE + # Optional: Health checks + health_uri /health + health_interval 30s + health_timeout 5s + }
31-44: Modernize security headers (avoid X-XSS-Protection; prefer CSP).Replace X-XSS-Protection with CSP; consider CSP frame-ancestors over X-Frame-Options. (web.nodejs.cn, github.com, centralcsp.com)
header { - # Security headers - X-Frame-Options DENY + # Security headers + Content-Security-Policy "frame-ancestors 'none'" X-Content-Type-Options nosniff - X-XSS-Protection "1; mode=block" Strict-Transport-Security "max-age=31536000; includeSubDomains" Referrer-Policy "strict-origin-when-cross-origin"docs/examples/mcp-reverse-proxy/nginx.conf.example (2)
44-50: Optional: chunked_transfer_encoding off is usually unnecessary.SSE issues are almost always buffering-related; chunking can stay enabled in most cases. Keeping proxy_buffering off is the key. Consider removing the chunked_transfer_encoding line. (snapoverflow.com, nginx.org)
63-67: Optional: add Cache-Control to SSE responses.To prevent intermediaries from caching event streams, consider adding:
add_header Cache-Control "no-cache" always;docs/examples/mcp-reverse-proxy/README.md (1)
30-36: Fix the unnecessary duplication in the environment file setup.The comment about the kwildb/postgres image auto-creating the kwild user/database is duplicated - it appears both here and later in line 279-280. Keep one instance for clarity.
cat > .env << EOF - # TRUF.NETWORK uses kwildb/postgres image which auto-creates kwild user/database - # Note: No password needed - uses POSTGRES_HOST_AUTH_METHOD=trust DOMAIN=mcp.your-domain.com ACME_EMAIL=admin@your-domain.com EOFdocs/mcp-reverse-proxy.md (1)
637-643: Add file extensions to the example file references for clarity.The file references lack clarity about their actual names in the directory.
Ready-to-use configuration files and Docker Compose setups are available in the [`examples/mcp-reverse-proxy/`](./examples/mcp-reverse-proxy/) directory, including: - **nginx.conf.example** - Production-ready nginx configuration - **Caddyfile.example** - Caddy configuration with automatic HTTPS +- **Caddyfile.windows.example** - Windows-specific Caddy configuration - **traefik.yml.example** - Traefik static/dynamic configuration - **docker-compose.sse.yaml** - Complete Docker Compose setup with multiple reverse proxy options +- **claude-desktop-config.example** - Claude Desktop configuration examples for SSEdocs/mcp-server.md (1)
44-47: Consider adding a note about Python installation methods.For consistency, consider mentioning that users can also install Python directly from python.org if winget is not available.
```powershell # Install Python 3.12+ from https://www.python.org/downloads/ # or use winget: winget install Python.Python.3.12 +# Note: If winget is not available, download directly from python.orgdocs/examples/mcp-reverse-proxy/docker-compose.sse.yaml (1)
29-30: Consider parameterizing the PostgreSQL user and database names.The healthcheck hardcodes default values but uses environment variables. Consider using consistent variable references.
- test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-kwild} -d ${POSTGRES_DB:-kwild}"] + test: ["CMD-SHELL", "pg_isready -U kwild -d kwild"]Since the kwildb/postgres image auto-creates these with fixed names, using the hardcoded values is clearer.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (11)
README.md(1 hunks)docs/examples/mcp-reverse-proxy/Caddyfile.example(1 hunks)docs/examples/mcp-reverse-proxy/Caddyfile.windows.example(1 hunks)docs/examples/mcp-reverse-proxy/README.md(1 hunks)docs/examples/mcp-reverse-proxy/claude-desktop-config.example(1 hunks)docs/examples/mcp-reverse-proxy/docker-compose.sse.yaml(1 hunks)docs/examples/mcp-reverse-proxy/nginx.conf.example(1 hunks)docs/examples/mcp-reverse-proxy/traefik.yml.example(1 hunks)docs/mcp-reverse-proxy.md(1 hunks)docs/mcp-server.md(3 hunks)docs/windows-mcp-testing.md(1 hunks)
🧰 Additional context used
🪛 YAMLlint (1.37.1)
docs/examples/mcp-reverse-proxy/docker-compose.sse.yaml
[error] 42-42: trailing spaces
(trailing-spaces)
[error] 206-206: trailing spaces
(trailing-spaces)
[error] 209-209: trailing spaces
(trailing-spaces)
[error] 214-214: trailing spaces
(trailing-spaces)
[error] 217-217: trailing spaces
(trailing-spaces)
[error] 237-237: trailing spaces
(trailing-spaces)
[error] 240-240: trailing spaces
(trailing-spaces)
[error] 254-254: no new line character at the end of file
(new-line-at-end-of-file)
⏰ 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). (2)
- GitHub Check: acceptance-test
- GitHub Check: lint
🔇 Additional comments (4)
docs/windows-mcp-testing.md (2)
71-72: No action needed:install.shexists in thepostgres-mcprepo
Confirmed thatinstall.shis present at https://github.com/trufnetwork/postgres-mcp/blob/main/install.sh; the referenced installation script path is correct.
147-157: Potential issue with the Caddyfile creation method.The PowerShell here-string may not create the file with proper line endings for Caddy. Consider using a more reliable method.
# Create Caddyfile in current directory -@" +$caddyfileContent = @" :8080 { reverse_proxy /sse* 127.0.0.1:8000 { flush_interval -1 header_up Host {http.reverse_proxy.upstream.hostport} header_up Connection {>Connection} header_up Cache-Control {>Cache-Control} } } -"@ | Out-File -FilePath "Caddyfile" -Encoding UTF8 +"@ +$caddyfileContent | Out-File -FilePath "Caddyfile" -Encoding UTF8 -NoNewlineLikely an incorrect or invalid review comment.
README.md (1)
57-58: LGTM! Clear addition to the documentation.The new link to the MCP Reverse Proxy Configuration guide is well-placed and provides valuable production deployment guidance.
docs/examples/mcp-reverse-proxy/claude-desktop-config.example (1)
1-98: Comprehensive examples for Claude Desktop SSE configuration.Excellent documentation with clear examples covering different deployment scenarios and important Windows-specific notes. The troubleshooting section is particularly helpful.
MicBun
force-pushed
the
reverseProxy
branch
from
aacc672 to
ab7be48
Compare
|
I will test on macos, the local sse setup. |
Yes, please do so, I am only able to test the Windows + WSL one |
williamrusdyputra
left a comment
williamrusdyputra
left a comment
There was a problem hiding this comment.
working fine on MacOS, I didn't test the nginx or traefik, but it supposed to be the same across platform.
|
Yes, it is supposed to be the same @williamrusdyputra |
3 participants
This commit implements comprehensive MCP server reverse proxy documentation
with complete Windows native support and multi-platform deployment guides.
New Documentation:
Multi-Platform Support:
This documentation enables enterprise users to successfully deploy and test
MCP server functionality with reverse proxy support.
resolves: https://github.com/trufnetwork/truf-network/issues/1177
resolves: https://github.com/trufnetwork/truf-network/issues/1178
Summary by CodeRabbit