MCP Server (AI control) — Docs

MCP server — drive Ngris from your AI assistant

Ngris runs a hosted Model Context Protocol (MCP) server at https://mcp.ngris.com/mcp. Connect an MCP client — Claude Code, Claude Desktop, or any other MCP-capable assistant — and manage your whole Ngris edge in natural language: expose a service, deploy an app, write a traffic policy, inspect and replay a request, check usage, open a ticket, and more.

The server is a thin client over the public Ngris REST API. Every tool forwards your own credential to the API, so the assistant can never do more than you could yourself in the dashboard. There is no admin surface and no service-level token — it is user-facing scope only.

What it is not: the MCP server does not run your workloads or store your data. It turns Ngris' user-facing API into tools your assistant can call, under your account, with your permission.

Connect in Claude Code

# Add the remote MCP server (Streamable HTTP)
claude mcp add --transport http ngris https://mcp.ngris.com/mcp

# Then authenticate in the browser when prompted:
# Claude opens the Ngris login, you approve, and the
# connection is bound — no key to copy or paste.

Connect in 30 seconds

The transport is Streamable HTTP for the hosted endpoint, plus stdio for a local CLI/desktop process. Two ways to connect:

Claude Code (recommended)

Run the claude mcp add command on the right, then finish the browser login. Claude discovers the ~150 tools and you can start asking — e.g. “expose my app on port 3000” or “show me the 5xx requests on my API endpoint and replay the last one.”

Any other MCP client

Point a spec-native MCP client at the remote URL below. Clients that support OAuth 2.1 will trigger the browser consent flow automatically; clients that take a static credential can send an Ngris API key as a bearer token instead.

stdio: for a local process, run the server over stdio with an Ngris API key in NGRIS_TOKEN. Same tools, no browser round-trip — handy for a scripted or air-gapped agent on your own machine.

Generic MCP client config

{
  "mcpServers": {
    "ngris": {
      "type": "http",
      "url": "https://mcp.ngris.com/mcp"
    }
  }
}

Local stdio (API key)

# The MCP client launches the server over stdio and
# passes your API key through the environment.
NGRIS_MCP_TRANSPORT=stdio \
NGRIS_TOKEN=ak-your-ngris-api-key \
ngris-mcp

What you can do

The server exposes about 150 tools mapped one-to-one onto the public Ngris API, grouped by domain. Reads are marked read-only; writes declare whether they are destructive so your assistant can ask before applying anything risky.

Domain	What the assistant can do
Endpoints & tunnels	Create and manage endpoints, read tunnel status, and update endpoint settings (routing rules, client access/RBAC, health checks, custom error pages, cache).
Edge security	Traffic policies, firewall policies, and rate-limit rules — with `policy_test_expression` (CEL) and `policy_preview` (blast radius) to preview before apply.
Domains, TLS & DNS	Check domain availability, add domains, verify CNAMEs, read/reissue certificates, and manage DNS records.
Applications / deploy	Full deploy lifecycle: create, deploy, read deploy logs, roll back, set preview URLs, manage env vars, and provision app databases — static and managed apps.
Traffic inspector	List and read captured requests, run smart search, analyze a request, replay it against your backend, and export.
Account & identity	Account settings, members and roles, SSO config, and the account audit log; your own profile and MFA status; multi-account list/switch.
Usage & billing	Read usage and metrics, list plans, preview a plan change, view invoices, and open the Stripe billing portal.
Support & board	Create, list, reply to, and close support tickets and search the KB; browse and update the kanban board.

Four guided prompts ship alongside the tools — expose_localhost, deploy_repo, lock_down_endpoint, and debug_5xx — each a multi-tool flow your assistant can run end to end.

Ask in plain English

You:  Expose my app running on localhost:3000
      and put a rate limit of 60 req/min on it.

Iris via MCP:
  1. endpoint_create  → https://calm-fox.ngris.dev
  2. policy_preview   → shows blast radius
  3. rate_limit_create → applied after you confirm

Authentication: OAuth or API key

Two ways to authenticate a connection. Both resolve to your Ngris identity, and api-server is always the authority on what the credential can do.

OAuth 2.1 (browser login)

A spec-native MCP client (like Claude) connects with OAuth 2.1: you click Authenticate, sign in to Ngris, and approve — no key to copy or paste. The MCP server verifies the resulting access token against api-server's public keys, and api-server stays the single authorization server (there is no second identity provider to configure).

API key (bearer token)

Clients that take a static credential can send an Ngris API key as a bearer token; it is forwarded to api-server, which validates it. The HTTP transport rejects any request that arrives with no credential.

Pick one: OAuth is best for interactive assistants (Claude Code / Desktop) because there is nothing to store. An API key is best for a scripted local agent over stdio. An account API key is scoped to a single account; multi-account tools need an OAuth or session credential.

Security model

The MCP server is designed to be safe to hand to an autonomous assistant:

User-facing scope only. The server forwards your own credential and only calls public API routes. No /admin/* route is reachable — it can never do more than you can.
Least privilege. There is no database and no service-level token in the MCP server, so it holds no standing access of its own; every call is bound to the calling user.
An OAuth session cannot mint credentials. Requests authenticated with an OAuth/MCP token are refused when they try to create long-lived API keys or agent auth tokens — api-server returns a 403 and tells you to create those in the dashboard instead. So a connected assistant can operate your edge, but it cannot forge a durable key to keep for later.
Preview before apply. Mutating policy tools pair with policy_test_expression and policy_preview so impact is shown before a change lands, and write tools declare when they are destructive.
Secrets stay write-only. App env secrets are set, never read back; a newly created API key is returned exactly once; billing tools never touch card data (they return a Stripe-hosted URL or client secret).

In short: connecting the MCP server is like giving an assistant a seat in your account with your own permissions — consented, revocable, and unable to escalate.