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
- 01Streamable HTTP transport for MCP
- 02Per-provider bearer-token authentication
- 03Traffic policy with caller tagging
- 04Internal forwarding to the MCP server
- 05Persistent public cloud endpoint
Use cases
- 01Test an MCP server remotely with multiple providers
- 02Keep a development server available at a stable endpoint
- 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-gatewayAfter installing, type/run-mcp-gatewayin Claude Code to confirm it loaded.
Bundled filesreferences/http-transport.tsreferences/traffic-policy.yaml
Details
From the project READMERun 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
-
Give your MCP server an HTTP transport. MCP dev servers are usually stdio; providers need streamable HTTP. Drop in
references/http-transport.tsand call it alongside your existing stdio path:await runHttp(buildServer, port); // POST /mcp, bound to 127.0.0.1It needs
expressand@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. -
Run the server as an internal endpoint. The
.internalURL is what makes it internal - no extra binding flag:ngrok http <port> --url https://mcp.internal --host-header=rewriteThe--host-header=rewritematters: traffic arriving viaforward-internalcarriesHost: mcp.internal, which the MCP SDK's DNS-rebinding protection rejects by default. -
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, usegw_create_vaultandgw_create_secretinstead, and do not ask for an API key.gw_create_secretsends the user to a dashboard form to type the value. Have the user make each token on their machine withopenssl 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. -
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, andforward-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-callertag 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_endpointon the ngrok MCP server orngrok apifrom the CLI for a quick one). -
Point each provider at
https://<your-cloud-endpoint>/mcpwith 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.tsfollows this. - Caller attribution is advisory.
x-mcp-callertells 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
/mcppath. 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.tsand adapt the user'sbuildServer.