mcp-browser/examples/mcp.conf

# Example NGINX front-end for MCP Browser
#
# This template follows the MCP specification (2025-03-26) section 2.4 on dynamic
# client registration:
#   https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization#2-4-dynamic-client-registration
#
# Replace the placeholder values (domain, certificate paths, hash slug, upstream
# ports) with values that match your deployment. The configuration provides:
#   * OAuth metadata + register/token endpoints backed by an njs helper
#   * A protected Streamable HTTP MCP endpoint (auth_request + OAuth)
#   * An optional unauthenticated SSE bridge for local debugging
#
# The example assumes that:
#   * An njs script lives at /etc/nginx/njs/mcp_oauth.js providing handlers
#     for the metadata/register/token endpoints.
#   * The mcp-browser bridge listens on 127.0.0.1:8251 for SSE requests.
#   * The upstream MCP server (or proxy) exposes streamable-http at
#     127.0.0.1:8250.

map $http_upgrade $connection_upgrade {
  default upgrade;
  ''      close;
}

js_path   /etc/nginx/njs;
js_import mcp_oauth from /etc/nginx/njs/mcp_oauth.js;

# Upstream pools (tune keepalive as needed)
upstream mcp_streamable_backend {
  server 127.0.0.1:8250;
  keepalive 32;
}

upstream mcp_browser_backend {
  server 127.0.0.1:8251;
  keepalive 8;
}

server {
  listen      443 ssl http2;
  server_name mcp.example.com;

  ssl_certificate      /etc/letsencrypt/live/mcp.example.com/fullchain.pem;
  ssl_certificate_key  /etc/letsencrypt/live/mcp.example.com/privkey.pem;
  include              /etc/letsencrypt/options-ssl-nginx.conf;
  ssl_dhparam          /etc/letsencrypt/ssl-dhparams.pem;
  # ssl_trusted_certificate /etc/letsencrypt/live/mcp.example.com/chain.pem;

  add_header X-Robots-Tag "noindex, nofollow, noarchive" always;

  # Resource identifiers MUST match what your metadata document returns.
  # Use the same hash/digest in mcp_oauth.metadata().
  set $mcp_resource "__MCP_RESOURCE_HASH__";

  # --- OAuth discovery + token/register endpoints per §2.4 ------------------
  location = /.well-known/oauth-authorization-server/$mcp_resource/mcp {
    default_type application/json;
    js_content mcp_oauth.metadata;
  }

  location = /.well-known/oauth-protected-resource/$mcp_resource/mcp {
    default_type application/json;
    js_content mcp_oauth.metadata;
  }

  location = /.well-known/oauth-authorization-server {
    default_type application/json;
    js_content mcp_oauth.metadata;
  }

  location = /.well-known/oauth-protected-resource {
    default_type application/json;
    js_content mcp_oauth.metadata;
  }

  location = /register {
    default_type application/json;
    js_content mcp_oauth.register;
  }

  location = /token {
    default_type application/json;
    js_content mcp_oauth.token;
  }

  # The metadata served above should advertise this /authorize endpoint.
  # Update the upstream target to whatever Authorization Server you use.
  location = /authorize {
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_pass https://idp.example.com/oauth2/authorize;
  }

  # Internal auth_request hook used by the protected MCP endpoint.
  location = /_oauth_check {
    internal;
    js_content mcp_oauth.check;
  }

  # --- Protected Streamable HTTP MCP endpoint --------------------------------
  # Requires successful OAuth check before proxying to the upstream server.
  location ^~ /$mcp_resource/mcp/ {
    auth_request /_oauth_check;

    proxy_http_version 1.1;
    proxy_set_header Connection "";
    proxy_set_header Authorization "";
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

    # Streaming friendly defaults
    proxy_request_buffering off;
    proxy_buffering        off;
    proxy_read_timeout     1d;
    proxy_send_timeout     1d;
    proxy_connect_timeout  30s;

    # Advertise latest protocol version if desired
    # proxy_set_header MCP-Protocol-Version "2025-06-18";

    proxy_pass http://mcp_streamable_backend;
  }

  # --- Optional unauthenticated SSE bridge for local debugging ---------------
  location ^~ /$mcp_resource/mcp-browser/ {
    proxy_http_version 1.1;
    proxy_set_header Connection "";
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-NginX-Proxy true;

    proxy_request_buffering off;
    proxy_buffering        off;
    proxy_cache            off;
    proxy_read_timeout     1d;
    proxy_send_timeout     1d;
    send_timeout           1d;
    keepalive_timeout      1d;

    proxy_pass http://mcp_browser_backend/servers/mcp-browser/sse;
  }
}