ngrok MCP Server - ngrok documentation

The ngrok MCP server lets your AI agent read and manage your ngrok account. Connect a client such as Claude Code, Codex, or Cursor, then ask about your endpoints, traffic, usage, and team, or ask it to make changes, in plain language.

This page covers ngrok’s own MCP server. To put your own MCP server online with ngrok, see the guide on using ngrok as an MCP gateway.

The server URL is:

https://mcp.ngrok.com/mcp

Use this exact URL. The /mcp path is part of the OAuth resource, so the bare origin https://mcp.ngrok.com doesn’t work.

Access isn’t read-only. Your AI agent can create, change, and delete resources in your account, such as Cloud Endpoints, domains, IP policies, and secrets. The AI agent acts as you, with your role’s permissions, so check what it’s about to do before you approve a tool call. See Make changes safely.

Quickstart

Most clients sign in with OAuth. You add the server, then sign in to ngrok in your browser and approve the consent screen. You never paste a token into your AI agent.

Run:

claude mcp add --transport http --scope user ngrok https://mcp.ngrok.com/mcp
claude mcp login ngrok

Don’t pass --client-id or --callback-port. Claude Code finds its client through server discovery.

Use Codex 0.157.0 or later. Run:

codex mcp add ngrok --url https://mcp.ngrok.com/mcp
codex mcp login ngrok

If codex mcp add starts a sign-in, cancel it and run codex mcp login ngrok. Don’t pass --oauth-client-id or --oauth-resource.

Add this to ~/.cursor/mcp.json (global) or .cursor/mcp.json (project):

{
  "mcpServers": {
    "ngrok": {
      "url": "https://mcp.ngrok.com/mcp",
      "auth": {
        "CLIENT_ID": "iamcli_3KeK8d8sO4d9RArARx7RFzcTVtO"
      }
    }
  }
}

Don’t set CLIENT_SECRET. Then connect the server from Cursor’s MCP settings.

Add this to ~/.gemini/settings.json:

{
  "mcpServers": {
    "ngrok": {
      "httpUrl": "https://mcp.ngrok.com/mcp",
      "oauth": {
        "enabled": true,
        "clientId": "iamcli_3KeK8docLctYxdqmXkXUIBSFhMo"
      }
    }
  }
}

Don’t set clientSecret or redirectUri. Then run /mcp auth ngrok in Gemini CLI.

Run these on the machine that runs Amp:

amp mcp add ngrok https://mcp.ngrok.com/mcp
amp mcp oauth login ngrok \
  --server-url https://mcp.ngrok.com/mcp \
  --client-id iamcli_3KeO0uXWr4mqAa5QKHWzGNdqtv0

Don’t set --client-secret. Then start Amp to finish signing in.

Add this through Cline’s MCP settings (cline_mcp_settings.json):

{
  "mcpServers": {
    "ngrok": {
      "type": "streamableHttp",
      "url": "https://mcp.ngrok.com/mcp",
      "oauthClient": {
        "clientId": "iamcli_3KeO0voSIkw55lArUFbxy1fUnqM"
      }
    }
  }
}

Leave clientSecret unset. Then use Cline’s authorize action.

Add this to ~/.pi/agent/mcp.json:

{
  "mcpServers": {
    "ngrok": {
      "url": "https://mcp.ngrok.com/mcp",
      "oauth": {
        "clientRegistration": "cimd"
      }
    }
  }
}

Then run:

pi mcp login ngrok

Pi doesn’t use client ID metadata documents (CIMD) by default yet, so the clientRegistration setting is required. Without it, pi mcp login ngrok fails with “Authorization server does not support dynamic client registration.” pi mcp add can’t set this option, so edit the file instead of running it.

Add this to .vscode/mcp.json (workspace) or your user MCP configuration:

{
  "servers": {
    "ngrok": {
      "type": "http",
      "url": "https://mcp.ngrok.com/mcp"
    }
  }
}

Then start the server from that file and sign in.

Other clients

If your client supports OAuth client ID metadata documents, add https://mcp.ngrok.com/mcp as a remote HTTP server. Zed, Goose, and OpenCode work this way. In Claude on the web, Claude Desktop, and Cowork, go to Customize > Connectors and add a custom connector with https://mcp.ngrok.com/mcp. Then connect it to sign in. On Team and Enterprise plans, an owner adds the connector in Organization settings > Connectors. ChatGPT can’t connect yet.

Clients without OAuth

If your client can’t sign in with OAuth, use a personal access token (PAT) instead:

Create a personal access token

In the dashboard, go to Access Tokens and create a token. Choose the scopes for what you want your AI agent to do, and set an expiration. Read scopes, such as endpoints:read, let the AI agent look things up. Write scopes, such as endpoints:write and ip-policies:write, let it make changes. Copy the token right away. It starts with ngrok_pat_ and the dashboard shows it only once.

Send the token as a bearer header

Configure your client to send this header with every request to https://mcp.ngrok.com/mcp:

Authorization: Bearer ngrok_pat_...

For example, with Claude Code:

claude mcp add --transport http --scope user ngrok https://mcp.ngrok.com/mcp \
  --header "Authorization: Bearer $NGROK_PAT"

Most clients that take a JSON configuration accept a headers object next to url.

API keys and authtokens don’t work with the MCP server. Store the PAT the way you store other secrets, such as in an environment variable, and don’t paste it into a chat with your AI agent.

Check that it works

After you sign in, confirm that your client sees the ngrok tools:

Claude Code: run /mcp and select ngrok.
Codex: run codex mcp list.
Pi: run pi mcp list.
Any client: ask your AI agent “What ngrok tools do you have?”

Then ask “Which ngrok account am I signed in to?” The AI agent replies with your user, account, role, and plan. Your AI agent can look up:

Endpoints, ngrok agents, and Traffic Inspector traffic.
Gateway resources, such as domains, TCP addresses, IP policies, certificates, vaults, and event destinations.
Your account, team, credentials, usage, and limits.
The ngrok documentation.

Your AI agent can change:

Cloud Endpoints, including their URL, bindings, pooling, and Traffic Policy.
Reserved domains and TCP addresses.
IP policies and their allow and deny rules.
Vaults and secrets.
Credentials: it can revoke authtokens, API keys, and SSH keys.
Traffic Policy: it can write a policy and validate it before applying it.

What you can ask

These examples show what a conversation with the ngrok MCP server looks like. Your AI agent picks the tools, so the exact steps can differ. For more prompts you can copy, grouped by job, see Example prompts.

Show me the 500s on my endpoints by hour for the last day

The AI agent queries Traffic Inspector for status 500 over the last 24 hours, counted per hour in your time zone. You get an hourly breakdown, plus the paths and client IPs behind the spikes. Follow up with “Show me one of those requests” to see its headers, timing, and error detail.

I got an ngrok error page with request ID req_0a1b2c3d. What happened?

The AI agent looks up that request and reads the docs for the error. You get what failed, where it failed (ngrok, your ngrok agent, or your upstream), and how to fix it. The request details include the ERR_NGROK code only when full capture is turned on. Without full capture, paste the error code from the error page too, so the AI agent doesn’t blame your app for an ngrok error.

Rate limit /api on my Cloud Endpoint to 100 requests per minute per IP

The AI agent reads the rate-limit action docs, writes the policy, and validates it. If validation fails, it fixes the errors and validates again. Then it asks to update your Cloud Endpoint’s Traffic Policy.

Who on my team has API keys? Revoke the ones that belong to people who left

The AI agent joins your team with your API keys. You get each key’s owner, description, and status. For keys whose owner is no longer on the team, it asks to revoke each one. Tools never return the key, token, or secret values themselves.

Traffic questions use Traffic Inspector data, so the window your AI agent can see depends on your plan’s retention. Request headers and bodies are available only when full capture is turned on.

Make changes safely

The MCP server marks each tool as read-only or as one that makes changes, and marks deletes as destructive. Most clients use these markers to ask you before the AI agent runs a tool that changes your account. Keep those prompts on, and read what the AI agent is about to do before you approve it. To keep an AI agent read-only, connect with a personal access token that has only read scopes. See Clients without OAuth.

Troubleshooting

“Got new credentials, but ngrok rejected them”: Your account doesn’t have access to the MCP server. Contact ngrok support.
Sign-in fails or the server isn’t found: Check that the URL ends in /mcp.
Pi fails with “Authorization server does not support dynamic client registration”: Set oauth.clientRegistration to cimd for the server in ~/.pi/agent/mcp.json, then run pi mcp login ngrok again.
Claude Code uses an old callback port: Run claude mcp remove ngrok --scope user, then add the server again.
A PAT is rejected: The token is invalid, expired, or revoked. Create a new one and update the Authorization header.

Traffic Inspector: The traffic data behind most questions.
Traffic Policy: The rules your AI agent can write and validate.
IP policies: How deny and allow rules apply to endpoints.
Role-based access control: What your role allows the AI agent to do.
Use ngrok as an MCP gateway: Put your own MCP server online with ngrok.

Quickstart

Other clients

Clients without OAuth

Check that it works

What you can ask

Make changes safely

Troubleshooting

Related resources