mcpField
R
run-mcp-gateway

run-mcp-gateway

github.com/ngrokCloud & DevOps18143 installsUpdated 4d ago
Repository

About run-mcp-gateway

run-mcp-gateway is a skill for exposing an in-development MCP server through ngrok for remote testing by multiple AI model providers. It describes per-provider bearer-token authentication, traffic inspection, and a persistent cloud endpoint.

Key features

  1. 01Streamable HTTP transport for MCP
  2. 02Per-provider bearer-token authentication
  3. 03Traffic policy with caller tagging
  4. 04Internal forwarding to the MCP server
  5. 05Persistent public cloud endpoint

Use cases

  1. 01Test an MCP server remotely with multiple providers
  2. 02Keep a development server available at a stable endpoint
  3. 03Distinguish provider calls in traffic logs

MCP support

Guides exposing the user's MCP server to remote MCP clients over streamable HTTP, using ngrok endpoints and per-provider authentication.

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/ngrok/skills --skill run-mcp-gateway

After installing, type/run-mcp-gatewayin Claude Code to confirm it loaded.

Bundled filesreferences/http-transport.tsreferences/traffic-policy.yaml

Details

From the project README

Run an MCP gateway

Expose an in-development MCP (Model Context Protocol) server for remote testing against multiple AI model providers at once, with per-provider authentication and traffic inspection.

Before you start

Auth is required (ngrok-setup). This job uses a cloud endpoint + internal endpoint and a Traffic Policy with per-provider auth + forward-internal - both from ngrok-engine. A working reference implementation ships in references/: http-transport.ts and traffic-policy.yaml.

Architecture

MCP client (Claude/OpenAI) --Bearer token--> Cloud Endpoint (public, runs the policy)
  --forward-internal--> Agent Endpoint (bound internal, e.g. https://mcp.internal)
    --HTTP--> your MCP server (streamable HTTP transport)

Cloud endpoint (not agent) is required here: providers connect on their own schedule, so the public URL must persist independently of your dev process.

Steps

  1. Give your MCP server an HTTP transport. MCP dev servers are usually stdio; providers need streamable HTTP. Drop in references/http-transport.ts and call it alongside your existing stdio path:

    await runHttp(buildServer, port); // POST /mcp, bound to 127.0.0.1
    

    It needs express and @modelcontextprotocol/sdk. It binds loopback by default, so the process is reachable only through the local ngrok agent - pass { host } to change that. stdio keeps working for local clients.

  2. Run the server as an internal endpoint. The .internal URL is what makes it internal - no extra binding flag: ngrok http <port> --url https://mcp.internal --host-header=rewrite The --host-header=rewrite matters: traffic arriving via forward-internal carries Host: mcp.internal, which the MCP SDK's DNS-rebinding protection rejects by default.

  3. Create a vault + one secret per provider. These are tokens you generate (not the provider's API key), so you can tell providers apart:

    ngrok api vaults create --name "mcp-callers"
    ngrok api secrets create --name "claude-key" --value "$(openssl rand -hex 32)" --vault-id "$VAULT_ID"
    

    When ngrok-surfaces ("Account resources") picks the ngrok MCP server, use gw_create_vault and gw_create_secret instead, and do not ask for an API key. gw_create_secret sends the user to a dashboard form to type the value. Have the user make each token on their machine with openssl rand -hex 32, paste it into that form, and keep it for the provider's settings in step 5. Never ask for the token in the chat.

  4. Create a cloud endpoint with the policy (references/traffic-policy.yaml). Its shape is security-critical, so use it as-is rather than re-deriving it: one rule per provider that matches that provider's bearer token, tags the caller, and forward-internals - which is terminating - followed by an unconditional catch-all that returns 401. Anything without a valid token matches no provider rule and falls through to the 401.

    Do not restructure it so the rejection tests the x-mcp-caller tag instead. That header is added by the policy but is also a request header, so a client can send it and skip the check entirely.

    Attach via whichever surface fits (see ngrok-surfaces: Terraform or the operator for a durable setup, gw_create_cloud_endpoint on the ngrok MCP server or ngrok api from the CLI for a quick one).

  5. Point each provider at https://<your-cloud-endpoint>/mcp with its bearer token as a custom header. Add a provider later by adding a secret and copying its policy rule.

Gotchas

  • New server instance per request. MCP's stateless HTTP pattern needs a fresh server object per request so concurrent providers don't share session state. references/http-transport.ts follows this.
  • Caller attribution is advisory. x-mcp-caller tells your server which provider called, but a client holding any valid token can also send that header itself. Trust it for logging, not for authorization.
  • The /mcp path. Providers expect the MCP endpoint at a path (commonly /mcp); make sure the transport and the URL you hand out agree.
  • host-header rewrite (step 2) - the single most common reason a forwarded MCP request 400s.

Notes for agents

  • This is distinct from expose-localhost: it needs per-provider auth and a persistent cloud endpoint, not a plain tunnel.
  • This is for the user's own MCP server. To connect ngrok's MCP server to the user's agent, see ngrok-setup.
  • Don't invent the transport - use the bundled http-transport.ts and adapt the user's buildServer.

Comments

Markdown supported