> For the complete documentation index, see [llms.txt](https://help.nightfall.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.nightfall.ai/data-exfiltration-prevention/ai-agent-security/ai-governance/mcp-gateway.md). # MCP Gateway MCP Gateway sits between your AI clients (Cursor, Claude Code, Claude connectors, ChatGPT, VS Code, Windsurf) and the remote MCP servers those clients call (GitHub, Linear, Notion, an internal HTTPS service). People stop pasting vendor URLs and personal tokens into `mcp.json`. They point one Nightfall URL. You decide which servers and tools exist, whose credentials are in play, and you get a log of what was asked. {% hint style="info" %} The tab is double-gated. Nightfall has to enable the product for your organization, and the person needs **MCP Gateway** read access. If the backend is not provisioned yet, the console says **MCP Gateway isn't enabled for your organization**. Use **Check again** after your Nightfall rep turns it on. {% endhint %} ## When to use the gateway Use **MCP Server Visibility** when the question is "what is already running on laptops," including local `stdio` servers and shadow installs nobody approved. Visibility does not broker credentials or sit on the call path. Use **MCP Gateway** when you want a sanctioned remote path that you can shrink, revoke, and audit. Typical jobs: | Job | What the gateway does | | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | IT cannot see or revoke the GitHub / Linear tokens sitting in every developer's client | Broker those credentials. Admins see that a connection exists and can cut it. They never see the secret. | | You cannot answer "who called `delete_issue` last week, with what arguments" | **Audit** records user, server, tool, status, and request payload. | | Someone left and their AI connectors still work until each vendor token expires | Remove MCP access (or the Nightfall user). The next client call fails. Revoke the upstream connection so the provider is told to invalidate its token. | | GitHub MCP is useful for search, dangerous for write and delete | Keep the server enabled. Disable the write and delete tools. Clients stop listing them and cannot call them. | | A vendor is having an incident, or you want Linear gone from every client today | **Block** the server. Config stays. Tools disappear. **Unblock** when you are ready. | | You are done with a server and want credentials wiped | **Remove**. This cannot be undone. | | Contractors should use the gateway without a full Nightfall admin seat | Invite them as **MCP User** on the Users tab. | | Claude or ChatGPT should not also have a direct GitHub connector | Publish only the Nightfall URL as the org connector. Do tool governance once, here. | Do **not** use the gateway to inventory local filesystem or stdio MCP. That is [MCP Server Visibility](/data-exfiltration-prevention/ai-agent-security/ai-governance/mcp-server-visibility.md). The gateway also does not stop someone from typing a vendor URL into a local Cursor or Claude Code config. It governs the traffic that uses the Setup URL. ## What you can turn off Enabling a server is not all-or-nothing. Pick the smallest control that matches the risk. These four actions do not overlap. | If you need this | Use | What clients see | What you keep | | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | --------------------------------------------------------- | | This **server** must stop for everyone, but you may bring it back | **Block** on Enabled Servers | Members lose the row. Tools vanish from the aggregator. | Alias, URL, auth setup, stored credentials | | This **server** must go away for good | **Remove** | Gone. | Nothing. Tools cache and credentials are deleted. | | The server stays. These **tools** must not exist for anyone (delete, admin, write) | **Disable** on the server's Tools card (admin **Enabled** column). Bulk select works. | Disabled tools drop out of listings and cannot be invoked. Other tools stay. | The server, other tools, everyone's connections | | The server is fine for the company. **I** do not want this tool in my client | Turn off **Enabled for me** | Only that person's client loses the tool | Org-wide enablement. Admins still see **Disabled for me** | Leave a catalog row disabled (do not click **Enable**) when the server is not sanctioned yet. Uncertified catalog rows cannot be enabled in place; add them as custom only if you accept that risk. New tools discovered on refresh start **enabled**. After **Refresh tools**, open the **Write** and **Delete** groups and disable anything you do not want in agents. The org-wide **Tools** tab is a read-only index (name, server, description). You change enablement on the server, not on that tab. **Block** vs **disable tools:** Block is the whole vendor. Disable is one capability. If Linear is approved but `delete_*` is not, disable those tools. If Linear should not be reachable at all this week, Block. A disabled or blocked tool is how you hide a capability from clients today. Endpoint DLP that mentions MCP collections is a different surface: [Creating an AI Agent Security Policy](/data-exfiltration-prevention/ai-agent-security/ai-governance/auditability-and-control/creating-an-ai-agent-security-policy.md). ## Who sees what Two MCP roles exist. Settings lists them as **Mcp Gateway Admin** and **Mcp Gateway User**. In the gateway they show as **MCP Admin** and **MCP User**. **MCP Admins** see every sub-tab, in this order: 1. Audit 2. Server Catalog 3. Enabled Servers 4. Tools 5. Users 6. Setup **MCP Users** (members) see **Enabled Servers** and **Setup** only. They land on Enabled Servers. They can connect their own OAuth or PAT. They cannot enable servers, invite people, or open Audit. People who only have MCP Gateway access (and no other Nightfall products) get a standalone **MCP Gateway** app at `/mcp-gateway`, with the same sub-tabs their role allows. Everyone else uses **AI Governance > MCP Gateway**. The dropdown label looks like **MCP Gateway: Setup**. If your role is still loading, the UI stays open (admin-capable) until the server says you are a member. Server-side checks still apply. ## How a call actually travels 1. An admin enables a server from the catalog or adds one by URL. 2. Each person points Cursor, Claude Code, Windsurf, or VS Code at the tenant **MCP endpoint URL** from Setup. 3. The client opens a browser. Nightfall asks them to **Approve** or **Deny** access to the gateway. 4. If the upstream server needs GitHub (or similar), they click **Connect** on Enabled Servers and finish that provider's sign-in. 5. The client lists tools as `__` (for example `github__search`). 6. Each invocation shows up on **Audit**. Two different "Connect" moments: the browser page **Connect to Nightfall MCP Gateway** is client-to-gateway. **Connect** on a server row is gateway-to-upstream (GitHub, Linear, and so on). ## Scope The gateway is a Nightfall-hosted remote MCP server. Clients that speak streamable HTTP and OAuth use the URL from Setup. It does **not** proxy local `stdio` servers (a filesystem server on a developer's machine, for example). Those stay on [MCP Server Visibility](/data-exfiltration-prevention/ai-agent-security/ai-governance/mcp-server-visibility.md). The gateway is for remote HTTP MCP: GitHub, Linear, Notion, an internal service you expose over HTTPS, and the like. It aggregates **tools**. MCP prompts and resources are not served through the gateway in this release. There is no separate gateway password. Sign-in is Nightfall SSO (or whatever identity you already use on the platform). When a client connects, the browser redirects to Nightfall for authentication and consent. The workspace path in the Setup URL routes traffic to your tenant. Access still requires a Nightfall sign-in and membership. A URL by itself is not a credential. ## Credentials Management Every call through the gateway uses two different secrets: 1. **The client's gateway token.** Issued after **Approve** on **Connect to Nightfall MCP Gateway**. It proves the person to Nightfall. It is scoped to your tenant and is not sent to GitHub, Linear, or any other backend. 2. **The backend credential.** The user's OAuth tokens or PAT for that upstream server. Nightfall stores those encrypted and injects them when calling the backend. Clients never see them. Admins can see that a connection exists, how many people are connected, and connection health (**Connected**, **Token expired**, **Not connected**). They cannot see token or key values. OAuth client secrets on **Set OAuth client** are write-only; you will not see the secret again. For OAuth backends, each person's **Connect** flow talks to the provider. Nightfall does not see that password. After approval, calls from that person's clients use *that* person's identity at the backend, so the provider's own permissions and audit trail match a real user. If a backend is down, calls fail with the backend error. Repeated calls to a failing server are short-circuited so clients fail fast instead of hanging. Other enabled servers keep working. Custom **Remote URL** values must be public `http(s)` MCP endpoints. Private, link-local, and cloud-metadata addresses are rejected. Use **Add custom server** for internal servers only when they are reachable from Nightfall's hosted service over HTTPS. *** ## Scenario: Getting Started You have MCP Admin or System Administrator privileges in Nightfall. The tab is visible. You want one working client today. ### 1. Confirm the tenant is live Open **AI Governance > MCP Gateway > Setup**. The card title is **Connect your MCP client**. You should see **MCP endpoint URL** and **Copy**. If you see **Your MCP endpoint is unavailable right now**, provisioning is not finished. If you see **Couldn't load your MCP endpoint**, retry. If you still get the "isn't enabled" screen, your Nightfall rep has more work to do. ### 2. Enable a catalog server Go to **Server Catalog**. Description in the product: curated servers you can enable; anything else is **Add custom server**. 1. Search by name, or filter **Certification** to **Certified** / **Uncertified**. 2. Certified rows have **Enable**. Uncertified rows do not. The tooltip says to add those manually via **Add custom server**. 3. Click **Enable**. Set **Alias** (max 24 characters; letters, numbers, hyphens, underscores). Tools will appear as `__`. 4. Some OAuth servers ask for a client id and secret in the wizard. Those fields are optional here. You can leave them blank and use **Set OAuth client** on the server later. 5. Success toast: **Enabled "\". It now appears under Servers.** ### 3. Check Enabled Servers Columns: **Alias**, **Canonical name**, **URL**, **Auth**, **Status**, **Validation**, **Connected**. Auth values you may see: **None**, **OAuth (DCR)**, **OAuth (static)**, **OAuth (CIMD)**, **PAT**. Validation values: **Pending**, **Config valid**, **Config valid - manual OAuth**, **Awaiting first user OAuth**, **Tools discovered**, **Tools discovery failed**, **Reconnect required**. Use **Validate** or, on the server page, **Validate now**. **Refresh tools** pulls a new tool list. **View check results** shows the raw checks. ### 4. Point a client at Setup Setup has four client tabs. Use the snippet the console generates (it already has your URL). The shapes are: **Cursor** (`~/.cursor/mcp.json` or project `.cursor/mcp.json`): ```json { "mcpServers": { "nightfall": { "url": "" } } } ``` Reload Cursor's MCP server list, or restart Cursor. **Claude Code** (no config file): ```bash claude mcp add --transport http nightfall ``` It registers immediately. No restart. **Windsurf** (`~/.codeium/windsurf/mcp_config.json`). Note `serverUrl`, not `url`: ```json { "mcpServers": { "nightfall": { "serverUrl": "" } } } ``` Reload Cascade's MCP list from Windsurf settings. **VS Code** (workspace `.vscode/mcp.json` or user profile). Note `servers` and `"type": "http"`: ```json { "servers": { "nightfall": { "type": "http", "url": "" } } } ``` Run **MCP: List Servers** to confirm. ### 5. Approve the gateway, then call a tool The client opens **Connect to Nightfall MCP Gateway**. Sign in if asked. **Approve**. If the window is wrong, **Deny** and close the tab. **Switch account** if you are in the wrong Nightfall user. Then invoke a tool. Open **Audit**. You should see User, Server, Tool, Method, Event, Status, Time. *** ## Scenario: an employee connects their own client You have MCP User. You do not see Catalog, Tools, Users, or Audit. 1. Open **Setup**. Copy the snippet for your client. Same four clients as above. 2. Approve the Nightfall consent page when the browser opens. 3. Open **Enabled Servers**. Member copy: **MCP servers your company has enabled. Connect your own credentials where required.** 4. Blocked servers are hidden from you. If the list is empty: **No servers enabled for your company**. Ask an MCP Admin. 5. For OAuth servers, click **Connect**. Allow popups. If you see **Popup blocked**, allow popups and click Connect again. 6. Connection states: **Connected**, **Token expired**, **Not connected**. 7. For PAT servers, use **Set my PAT**. 8. On a server's tool list you can turn **Enabled for me** off for tools you do not want in your client. Admins can also disable a tool for everyone. Disabled tools are hidden from MCP clients. Tools discovered later start enabled. *** ## Scenario: add a server that is not in the catalog Use this for an internal remote MCP server, or an uncertified catalog entry. 1. **Server Catalog > Add custom server**. 2. **Alias** and **Remote URL** (`https://host/mcp`). Invalid URLs get **Enter a valid http(s) URL.** 3. **Add**. Toast: **Added "\". It now appears under Servers.** If the catalog table itself is empty, you can still add by URL. Uncertified catalog rows cannot be enabled in place. The product tells you to add them as custom if you need them now. Ask your Nightfall account team if you want an entry certified. Tool lists refresh when you enable a server, after a user's first connection, on **Refresh tools**, and in the background. New tools start enabled. Disable the ones you do not want clients to see. *** ## Scenario: GitHub (or any upstream OAuth) for each person 1. Admin enables the certified GitHub catalog entry (or adds it as custom if that is how you run it). 2. If the provider needs a static OAuth app, an admin uses **Set OAuth client** / **Update OAuth client**. Credentials are write-only. You will not see the secret again. 3. Each member clicks **Connect** and finishes GitHub's consent. 4. Admins see **N connected** on the row, not the token. **Set OAuth client** is also on the server detail **Setup** card when the product has setup guidance for that server. *** ## Scenario: shared PAT vs per-user PAT Auth type **PAT**: * **Credential scope: Shared** plus **Paste PAT (shared)**: one token, injected for everyone. * **Credential scope: Per-user** plus each person **Set my PAT**: no fallback to a shared token. **PAT auth header** on the server detail page defaults to **Default (Authorization: Bearer)** unless an admin changes it. Admins can paste a PAT on a **None** auth server to switch it to PAT. *** ## Scenario: pull a server out of every client (Block or Remove) You approved GitHub, then legal says pause it, or the vendor is in an incident. You do not want to rebuild the alias and OAuth app next week. 1. Open **Enabled Servers**. 2. **Block**. The confirm dialog warns if people are still connected. Status becomes **Blocked**. Members no longer see the row. Clients lose every tool from that alias. 3. **Unblock** when the pause is over. Use **Remove** only when the server should not return and stored credentials should die with it. The dialog says this cannot be undone. **Rename** changes the alias, which changes the `__` names clients already have. Do that on purpose, not as a substitute for Block. *** ## Scenario: allow a server, hide the dangerous tools GitHub (or Linear, Notion, any catalog server) ships read, write, and delete in one package. Most teams want search and list, not `delete_*` or admin. 1. Open the server (row click). Breadcrumb: **Enabled Servers** › `{alias}`. 2. On the **Tools** card, use the **Write**, **Delete**, and **Unspecified** groups. Columns: **Tool Name**, **Description**, **Enabled** (admin) or **Enabled for me** (member). 3. Select the tools you do not want in agents. Bulk **Disable**. 4. Confirm in a client: those names are gone from the tool list and a call to them fails. Admins can also see **Disabled for me** when a member hid a tool only for themselves. That does not protect the company. Org risk belongs on the admin **Enabled** column. After **Refresh tools**, walk Write and Delete again. New tools start enabled. The **Tools** tab (admin, org-wide) is an index only: **Exposed name**, **Server**, **Description**. Search there. Change enablement on the server. If the index is empty: **Refresh tools on a server from the Servers tab.** *** ## Scenario: invite MCP people without making them full Nightfall admins **Users** (admin): *Console users with MCP Gateway access. Invite people from your company directory without exposing them in the admin user list.* 1. **Invite users**. 2. **Directory search** or **Upload CSV** (one email per line). 3. Assign **MCP Admin** or **MCP User**. 4. Outcomes you may see: already invited, already has this role, or a cross-company conflict. The table: **Email**, **Role**, **Created**, **Status** (**ACTIVE**, or **EXPIRES IN N DAY(S)**). **Edit** changes Admin ↔ User. **Delete** removes MCP Gateway access only. Other Nightfall access stays. You cannot edit or remove yourself. Pending invitations appear in the table. There is no revoke action on a pending invite in the current console. MCP-only users are not a replacement for Nightfall Settings → Users & Roles. Invite here when you want gateway access without a full console seat. *** ## Scenario: investigate a tool call **Audit** (admin). Default window is the last 7 days. Columns: **User**, **Server**, **Tool**, **Method**, **Event**, **Status**, **Time**. Search by server or tool name. Status values are humanized: success, failure, error, denied, **blocked**. Open a row for **Request**, **Identifiers** (User, Session, Event ID, Request URL), and **Request payload**. **Export to CSV** → **Send Download Link**. You get email within 15 minutes. You can deep-link with `?userId=` on the Audit URL. There is no "View logs" button on user rows yet. Members who hit Audit see **You don't have access to audit logs**. This tab is a call log. It does not show a separate "would block" or policy-reason column. To take a capability away, Block the server or Disable the tool (see **What you can turn off**). Audit stores who called, which server and tool, method, event, status, identifiers, and the **request** arguments (capped at 8 KiB). Backend tool responses are not stored. When someone leaves: **Delete** their MCP Gateway access on Users (or remove them from Nightfall). Revoke or reconnect is per server via **Connect** / disconnect on Enabled Servers. Their next client call should fail once access is gone. Re-inviting them later starts a fresh sign-in. *** ## Scenario: Claude Cowork, claude.ai, or Claude Desktop These clients use **custom connectors**, not the four Setup file snippets. Copy the **MCP endpoint URL** from **Setup** first. You need a Claude Team or Enterprise plan for an org-wide connector. Only an Owner or Primary Owner can add it to the organization. 1. In Claude, open **Organization settings > Connectors** (or **Admin settings > Connectors**). 2. **Add** / **Add custom connector**. If asked for a type, choose **Custom** then **Web**. 3. Name it something people will recognize, for example **Nightfall MCP Gateway**. 4. Paste the MCP endpoint URL from Setup. Leave OAuth Client ID and Client Secret empty. The gateway registers Claude dynamically. 5. **Add**. Each member still selects **Connect** on that connector, signs in to Nightfall, and **Approve**. Adding the connector does not grant access by itself. In a conversation, turn the connector on with **+** then **Connectors**. Tools show as `__`. Some backends still need **Connect** on Enabled Servers in Nightfall (GitHub is the usual case). To make the gateway the only Claude path: add only this connector, and do not add direct Linear/Notion/GitHub connectors for the same services. On Team and Enterprise, members cannot add org connectors themselves. Claude Code still reads a local config file a user can edit. On Pro or Max, a person can **Add custom connector** themselves with the same URL and empty OAuth fields. If tools are missing in chat: the connector may be off for that conversation, Nightfall sign-in may be incomplete, or the backend still needs **Connect** in the Nightfall console. HIPAA-ready Claude Enterprise plans can block custom connectors org-wide; that is a Claude admin setting, not Nightfall. *** ## Scenario: ChatGPT custom connector ChatGPT can attach the same Setup URL as a custom MCP app on Business, Enterprise, and Edu workspaces (developer mode). Individual paid plans can do this in developer mode as well. 1. A ChatGPT admin turns on developer mode / custom MCP connectors under workspace permissions (exact labels vary by ChatGPT plan). 2. **Settings > Apps & Connectors > Create**. Name it **Nightfall MCP Gateway**. Set the connector URL to the MCP endpoint URL from Setup. Authentication: OAuth. Leave static client fields empty. 3. Scan tools and complete Nightfall sign-in when prompted. Publish when you are ready. ChatGPT can further restrict which of the gateway's tools that app may call. Nightfall still decides which servers and tools exist at all. Prefer doing tool governance in Nightfall so Cursor, Claude, and ChatGPT see the same set. On Enterprise/Edu, refresh the app's action list when you enable new Nightfall servers. On Business, published apps may be frozen; you may need to recreate the app to pick up new tools. Members authenticate individually on first use. Publish only the gateway app for services you already route through Nightfall; do not also enable ChatGPT's direct connector for the same GitHub or Linear instance if you want a single path. *** ## Server detail **Server info** can include Alias, Canonical name, Remote URL, MCP URL, Transport, Additional headers, PAT auth header, Created, Last validated, Last tools refresh, Validation, Check results, OAuth client ID, Scopes, and **Discovered OAuth endpoints**. **Remove server** and **Validate now** sit in the header next to **Connect**. If the alias is wrong: **Server not found**. *** ## Consent page (what users see in the browser) URL shape: `/mcp/authorize` with `request_id` and `short_code` from the client. * Missing params: **This link is invalid**. Restart from the MCP client. * Loading: **Signing you in...** * Main: **Connect to Nightfall MCP Gateway**. Copy explains that an MCP client is requesting access; decline if you did not start it. * **Logged in as {email}**. **Switch account**. **Deny** / **Approve**. * After deny: **Access declined**. Close the tab. * Failure: **Couldn't complete this request**. Close the tab and connect again. Questions on that page go to your Nightfall admin or . *** ## If something fails | What you see | What to do | | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **MCP Gateway isn't enabled for your organization** | Nightfall rep. Then **Check again**. | | **Still not enabled - check back again shortly.** | Provisioning still running. | | **Your MCP endpoint is unavailable right now** | Wait for tenant provisioning to finish. | | Catalog **Enable** disabled, uncertified tooltip | Use **Add custom server**. | | **Popup blocked** | Allow popups, click **Connect** again. | | **Token expired** | Connect again on that server. | | Tools missing in the client | Server blocked, tool disabled, or you still need **Connect** / **Set my PAT**. Validation may be **Tools discovery failed** or **Awaiting first user OAuth**. | | **No tools cached** on the Tools tab | **Refresh tools** on Enabled Servers. | | Client cannot authenticate | Confirm you pasted the URL from Setup. Cursor uses `url`, Windsurf uses `serverUrl`, VS Code uses `servers` + `type: http`, Claude Code uses the CLI. | Command palette (when you have access): **Go to MCP Gateway Setup**, **Go to Enabled Servers**, **Go to Server Catalog**, **Go to Gateway Tools**, **Go to Gateway Audit**, **Go to Gateway Users**. *** ## How this relates to MCP Server Visibility [MCP Server Visibility](/data-exfiltration-prevention/ai-agent-security/ai-governance/mcp-server-visibility.md) is the inventory of what endpoints already run, including servers nobody approved. The gateway is only the servers you enable here, plus the credentials and the call log. A usual split: find shadow MCP on Visibility, decide what is allowed, enable that set on the gateway, point clients at Setup, and use Audit (and Visibility notifications) for everything else. File-configured clients (Cursor, Claude Code, VS Code, Windsurf) can still be pointed at a vendor URL instead of Setup. This tab does not override those files. Claude.org connectors and ChatGPT workspace apps are admin-controlled on the higher plans. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://help.nightfall.ai/data-exfiltration-prevention/ai-agent-security/ai-governance/mcp-gateway.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.