> ## Documentation Index
> Fetch the complete documentation index at: https://ngrok.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# ngrok MCP Server

> Connect Claude Code, Codex, Cursor, and other AI agents to the ngrok MCP server to inspect and manage your endpoints, traffic, and account.

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.

> [!NOTE]
>
> 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](https://ngrok.com/docs/gateway/api-gateway/mcp-gateway.md).

The server URL is:

```txt theme={"theme":{"light":"css-variables","dark":"css-variables"}}
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.

> [!WARNING]
>
> 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](#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.

> [tab] Claude Code
>
> Run:
>
> ```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
> 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.

> [tab] Codex
>
> Use Codex 0.157.0 or later.
> Run:
>
> ```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
> 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`.

> [tab] Cursor
>
> Add this to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project):
>
> ```json theme={"theme":{"light":"css-variables","dark":"css-variables"}}
> {
>   "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.

> [tab] Gemini CLI
>
> Add this to `~/.gemini/settings.json`:
>
> ```json theme={"theme":{"light":"css-variables","dark":"css-variables"}}
> {
>   "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.

> [tab] Amp
>
> Run these on the machine that runs Amp:
>
> ```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
> 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.

> [tab] Cline
>
> Add this through Cline's MCP settings (`cline_mcp_settings.json`):
>
> ```json theme={"theme":{"light":"css-variables","dark":"css-variables"}}
> {
>   "mcpServers": {
>     "ngrok": {
>       "type": "streamableHttp",
>       "url": "https://mcp.ngrok.com/mcp",
>       "oauthClient": {
>         "clientId": "iamcli_3KeO0voSIkw55lArUFbxy1fUnqM"
>       }
>     }
>   }
> }
> ```
>
> Leave `clientSecret` unset.
> Then use Cline's authorize action.

> [tab] Pi
>
> Add this to `~/.pi/agent/mcp.json`:
>
> ```json theme={"theme":{"light":"css-variables","dark":"css-variables"}}
> {
>   "mcpServers": {
>     "ngrok": {
>       "url": "https://mcp.ngrok.com/mcp",
>       "oauth": {
>         "clientRegistration": "cimd"
>       }
>     }
>   }
> }
> ```
>
> Then run:
>
> ```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
> 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.

> [tab] VS Code
>
> Add this to `.vscode/mcp.json` (workspace) or your user MCP configuration:
>
> ```json theme={"theme":{"light":"css-variables","dark":"css-variables"}}
> {
>   "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:

**1. Create a personal access token**

In the dashboard, go to [Access Tokens](https://dashboard.ngrok.com/access-tokens/new) 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.

**2. Send the token as a bearer header**

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

```txt theme={"theme":{"light":"css-variables","dark":"css-variables"}}
Authorization: Bearer ngrok_pat_...
```

For example, with Claude Code:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
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](https://ngrok.com/docs/mcp-server/prompts.md).

> [accordion] 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.

> [accordion] 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.

> [accordion] Rate limit /api on my Cloud Endpoint to 100 requests per minute per IP
>
> The AI agent reads the [`rate-limit`](https://ngrok.com/docs/gateway/traffic-policy/actions/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.

> [accordion] 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.

> [!NOTE]
>
> Traffic questions use [Traffic Inspector](https://ngrok.com/docs/obs/traffic-inspection) 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](#clients-without-oauth).

## Troubleshooting

* **"Got new credentials, but ngrok rejected them":** Your account doesn't have access to the MCP server.
  Contact [ngrok support](mailto:support@ngrok.com).
* **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.

## Related resources

* [Traffic Inspector](https://ngrok.com/docs/obs/traffic-inspection): The traffic data behind most questions.
* [Traffic Policy](https://ngrok.com/docs/gateway/traffic-policy.md): The rules your AI agent can write and validate.
* [IP policies](https://ngrok.com/docs/gateway/traffic-policy/concepts/ip-policies.md): How deny and allow rules apply to endpoints.
* [Role-based access control](https://ngrok.com/docs/iam/rbac.md): What your role allows the AI agent to do.
* [Use ngrok as an MCP gateway](https://ngrok.com/docs/gateway/api-gateway/mcp-gateway.md): Put your own MCP server online with ngrok.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.