NGINX for Model Context Protocol

Model Context Protocol (MCP) lets clients call tools provided by a server. Over HTTP, a tool call is a JSON-RPC request sent by POST to a single endpoint, such as /mcp. The RPC method tools/call selects the operation; params.name selects the tool.

This repository provides NGINX routing recipes and runnable examples of HTTP metrics, backend operation metrics, and JSON response observation. The examples support direct calls to known tools using MCP 2026-07-28. Clients that require tool discovery need an additional discovery endpoint or adapter; these examples do not aggregate backend tool catalogs.

Native request processing

The HTTP JSON module is available since NGINX 1.31.5 and requires --with-http_json_module when building from source. The demos use the official NGINX 1.31.6 alpine-otel image with the JSON module built in.

MCP 2026-07-28 mirrors the RPC method and tool name into HTTP headers. NGINX can route using these headers. client_body_early_read and json_set also make body fields available before routing and access checks. Comparing headers with the body prevents a caller from routing to one tool while asking the backend to execute another.

A request to the native example looks like this:

POST /mcp HTTP/1.1
Host: localhost:9000
Content-Type: application/json
Accept: application/json, text/event-stream
MCP-Protocol-Version: 2026-07-28
Mcp-Method: tools/call
Mcp-Name: get_forecast

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_forecast",
    "arguments": {},
    "_meta": {
      "io.modelcontextprotocol/protocolVersion": "2026-07-28",
      "io.modelcontextprotocol/clientCapabilities": {}
    }
  }
}

This abbreviated configuration illustrates the key settings:

http {
    json_set $mcp_body_method $request_body method;
    json_set $mcp_body_tool $request_body params.name;

    map "$mcp_body_method:$mcp_body_tool" $mcp_upstream {
        default                   "";
        "tools/call:get_forecast" forecast_backend;
    }

    upstream forecast_backend {
        server 127.0.0.1:9001;
    }

    server {
        listen 9000;

        client_body_early_read on;
        client_max_body_size 64k;
        client_body_buffer_size 64k;

        location = /mcp {
            if ($http_mcp_method != $mcp_body_method) {
                return 400;
            }

            if ($http_mcp_name != $mcp_body_tool) {
                return 400;
            }

            if ($mcp_upstream = "") {
                return 403;
            }

            proxy_pass http://$mcp_upstream;
        }
    }
}

The complete native example also checks HTTP method, media type and protocol version. Request buffers must hold the allowed body size so $request_body is available to json_set.

What each observation layer provides