> ## 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.

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.

[The ngrok MCP server: put a secure app online in plain English](https://www.youtube.com/embed/5yE0smuZkpU)

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).

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).

## 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**.

### Clients without OAuth

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

> [!NOTE]
>
> Personal access tokens are in early access.
> If the Access Tokens page sends you to Credentials, contact [ngrok Support](mailto:support@ngrok.com?subject=Personal+access+tokens) to turn them on for your account.

**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.
To see which tools each scope unlocks, see [Tools and scopes](https://ngrok.com/docs/mcp-server/tools.md#tools-by-scope).
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.
* AI Gateway models, costs, requests, and captures.
  See [AI Gateway tools](https://ngrok.com/docs/mcp-server/ai-gateway.md).
* AI Gateway setup, such as access keys, providers, virtual models, and firewall policies.
* 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.
* Team: it can invite a team member by email and cancel a pending invitation.
* Traffic Policy: it can write a policy and validate it before applying it.
* AI Gateway setup: access configs, access keys, custom providers, provider keys, virtual models, firewall policies, and gateway settings.
  Changes apply to live traffic right away.

For every tool and the scope it needs, see [Tools and scopes](https://ngrok.com/docs/mcp-server/tools.md).

## 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 HTTP 500s on my endpoints by hour for the last 24 hours, in Pacific time
>
> The AI agent queries Traffic Inspector for status 500 only over the last 24 hours, counted per hour in the time zone you named.
> You get an hourly breakdown, plus the paths and client IPs behind the spikes.
> To include 502, 503, and every other server error, ask for 5xx instead of 500.
> 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.
> Follow up with "Which connection carried that request?" to see the client, timing, bytes, TLS details, and failure of the [connection](https://ngrok.com/docs/obs/traffic-inspection/tcp-connections.md#connections-and-requests) it used.

> [accordion] Am I being rate limited? Why are my requests failing?
>
> The AI agent checks each of your plan's limits, your current usage, and when a limit last blocked your account.
> You get any limit that's blocking you, plus how close you are to the others.
> If no limit is blocking you, it looks for the failing requests in Traffic Inspector instead.

> [accordion] Rate limit /api and every path under /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.
> The rule matches `/api` and paths that start with `/api/`, such as `/api/users`, but not `/apiv2`.
> If you mean only the exact path `/api`, say so.
> If validation fails, it fixes the errors and validates again.
> Then it asks to update your Cloud Endpoint's Traffic Policy.

> [accordion] Are my event destinations failing to deliver logs?
>
> The AI agent lists your event destinations with their recent delivery errors, and the event subscriptions that send to each one.
> You get which destinations are failing, the error each one returned, and which logs you're missing as a result.
> Tools never return a destination's credentials.

> [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.
> A key counts as a leaver's key only when its owner isn't in your current list of users and service users.
> The AI agent shows you that evidence for each key and asks before it revokes one, so you can confirm the person really left.
> 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.
> The AI agent sees your current configuration and traffic, not a history of changes, so it can't tell you who changed a setting or when.

## Make changes safely

The MCP server marks each tool as read-only or as one that makes changes, and marks deletes and some updates to live configuration 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.
For how each tool is marked and the scope it needs, see [Tools and scopes](https://ngrok.com/docs/mcp-server/tools.md).

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.