# MCP registries and gateways: allowlisting servers for an organization

URL: https://developertoolkit.ai/en/ecosystem/mcp/registry-and-gateways/
Description: Vet MCP servers against the Official MCP Registry, publish an approved catalog, enforce it in Claude Code, Codex and Cursor, and audit calls through a gateway.

An organization allowlists MCP servers in four layers: vet each server against the Official MCP Registry and the vendor's repository, record approved servers in one reviewed catalog, enforce the catalog in each agent's managed configuration, and route calls through a gateway where audit logs are needed. The Official MCP Registry is a preview index, not a vetted list.

Your security team approved GitHub and Sentry MCP in the spring. Six months later, `claude mcp list` on a random laptop shows eleven servers, including a `figma` entry that points at a package from an unrelated publisher, and a Codex user has a Postgres server nobody reviewed. Nobody broke a rule, because there was no rule a tool could enforce, and nobody can say which servers ran against production data last week.

This page is for the **tech lead** who owns the approved list and the **CTO** who needs to show auditors that it holds. It assumes you have read [securing MCP servers](/en/ecosystem/mcp/mcp-security/), which covers scanning and read-only modes for a single server. The per-tool policy files that carry this list sit in [enforcing one policy across every coding agent](/en/org/managed-policy/).

## What an organization MCP allowlist gives you

- A repeatable vetting routine that uses the Official MCP Registry for identity and the vendor's repository for trust, with a prompt that runs it.
- A decision table for choosing between a fixed server set, an approved catalog and a denylist.
- One catalog file that renders into Claude Code `allowedMcpServers`, Codex `requirements.toml` and a Cursor review checklist.
- A gateway route for teams that need one entry point, secret scanning and call logs.
- Mechanical checks that prove the allowlist holds on every machine, and a list of what breaks during rollout.

## What is the Official MCP Registry, and what does it not do?

The [Official MCP Registry](https://github.com/modelcontextprotocol/registry) is a public index of MCP server metadata: name, version, packages and remote URLs. Its own README calls it "an app store for MCP servers". It launched in preview on 2025-09-08 and its API has been frozen at v0.1 since 2025-10-24; general availability has not been announced (checked 2026-09-26, and again on 2026-10-12, when the README's status was unchanged and the latest release was v1.8.1 of 2026-08-06). On 2026-09-26 it listed 36,176 servers at their latest version, counted through the registry API by this site's research.

Three properties decide how you use it:

| Property | What it means for your allowlist |
| --- | --- |
| **Namespace verification only.** `io.github.<user>/…` names require the publisher to authenticate as that GitHub user; `com.example/…` names require DNS or HTTP proof of the domain. | A name like `io.github.getsentry/sentry-mcp` proves who published the entry. It does not prove the server is safe or the one you meant. |
| **Minimal moderation.** The registry's moderation policy says it does not remove "low-quality or buggy servers" or "servers with security vulnerabilities", and that "consumers should assume minimal-to-no moderation". | Registry presence is never an approval. Several `*/github`, `*/figma` and `*/sentry` entries come from publishers unrelated to those vendors. |
| **Versions can lag packages.** On 2026-09-26 Serena's registry entry was 1.5.3 while PyPI had 1.7.0, and Next.js DevTools was 0.3.6 against npm 0.4.0. | Pin versions from the package registry you install from, not from the MCP Registry. |

The registry expects **aggregators** downstream of it: services that copy its data "on a regular but infrequent basis (e.g., once per hour)" and add value such as ratings or security scanning. An aggregator that also serves the registry's OpenAPI is a **subregistry**. That is the model for a private registry: your own filtered, reviewed copy, not a live dependency on the public index.

A registry entry is not the same thing as an MCP Server Card. SEP-2127 reached Final on 2026-10-06 (Extensions Track, extension id `io.modelcontextprotocol/server-card`): a standard, self-contained format that describes a server before a client connects, with its available transports, protocol versions and connection guidance. The spec revision is still 2026-07-28 (checked 2026-10-12). Treat a card as the server's own description, like its README, and keep the identity check in the vetting steps below.

## Which allowlist pattern fits your organization?

Choose the pattern before you write any file. The stricter patterns cost developers flexibility, so match them to risk, not to habit.

| Pattern | What developers can do | Choose it when | Claude Code mechanism |
| --- | --- | --- | --- |
| **Fixed set** | Use exactly the servers you deploy; add nothing | Regulated code, contractors, CI runners | `managed-mcp.json` |
| **Approved catalog** | Add any server on the list; everything else is blocked | Most product teams | `allowedMcpServers` + `allowManagedMcpServersOnly: true` |
| **Provided plus own** | Get your remote servers automatically and keep their own | Early rollout, low-risk repositories | `managedMcpServers` |
| **Denylist only** | Add anything except known-bad servers | Only as a stopgap while you build the catalog | `deniedMcpServers` |

The rest of this page builds the **approved catalog**, because it is the pattern most organizations end up on and the other three are subsets of its steps.

## How do you vet a server against the registry?

1. **Search the registry, then keep only the vendor's namespace.** The registry API returns every entry that matches the product name, with its packages and remote URLs; the `select` line keeps the vendor's namespace:

   ```bash
   # terminal; needs curl and jq
   curl -s "https://registry.modelcontextprotocol.io/v0.1/servers?search=sentry&version=latest" \
     | jq '.servers[]
           | select(.server.name | startswith("io.github.getsentry/"))
           | {name: .server.name, version: .server.version,
           repo: .server.repository.url,
           packages: [.server.packages[]?.identifier],
           remotes: [.server.remotes[]?.url]}'
   ```

   On 2026-09-26 the vendor's entry was `io.github.getsentry/sentry-mcp` 0.42.0, with the npm package `@sentry/mcp-server` and the remote `https://mcp.sentry.dev/mcp`. Remove the `select` line to see every other result for `sentry`: each one is a candidate for your denylist, not your allowlist.

2. **Confirm the identity outside the registry.** The `repository.url` must belong to the vendor's GitHub organization, and the vendor's own README must name the same package or URL. Check the package itself with `npm view <package> name version repository.url deprecated` or `https://pypi.org/pypi/<package>/json`.

3. **Prefer the remote URL when the vendor offers one.** A vendor-hosted HTTP server with OAuth runs no code on the laptop, and URL patterns are easier to enforce than exact commands. Record the read-only variant where one exists, such as GitHub's `https://api.githubcopilot.com/mcp/readonly`.

4. **Scan and classify.** Run the scan from [securing MCP servers](/en/ecosystem/mcp/mcp-security/) and mark the server **read-only** or **write-capable**. Write-capable servers that touch production need a named security sign-off.

5. **Record the decision in the catalog** (next section), with the evidence: registry name, repository, pinned version, transport, read-only switch and approver.

**Copy-paste prompt: vet an MCP server for the organization catalog**

```text
Vet the MCP server "Sentry" for our organization's MCP catalog. Do not
install, start or connect to it.

1. Query https://registry.modelcontextprotocol.io/v0.1/servers?search=sentry&version=latest
   and list every entry: name, version, repository URL, packages, remotes.
2. Identify the one entry whose repository belongs to the vendor's own GitHub
   organization. Explain why each other entry is not the vendor's.
3. For the vendor entry, check the package with `npm view <package> name
   version repository.url deprecated` (or the PyPI JSON API) and report any
   difference between the registry version and the package version.
4. State whether a vendor-hosted remote URL exists and whether a read-only
   URL, flag or scope exists.
5. Output one YAML block in the format of mcp-catalog/servers.yaml with
   fields: name, registry_name, repository, transport, url or command,
   version, read_only, evidence. List any write tools in a comment next to
   read_only. Leave approver empty.
```

## Build the approved catalog as your private registry

For most organizations, the private registry is a reviewed file in a policy repository, not a server. It is the single source for every tool's configuration, and a pull request is the approval record.

```yaml
# mcp-catalog/servers.yaml — one entry per approved server
- name: github
  registry_name: io.github.github/github-mcp-server
  repository: https://github.com/github/github-mcp-server
  transport: http
  url: https://api.githubcopilot.com/mcp/readonly
  version: remote        # vendor-hosted; nothing to pin
  read_only: true
  evidence: "registry entry + vendor README checked 2026-09-26"
  approver: "@acme/platform-security"
- name: sentry
  registry_name: io.github.getsentry/sentry-mcp
  repository: https://github.com/getsentry/sentry-mcp
  transport: http
  url: https://mcp.sentry.dev/mcp
  version: 0.42.0        # registry entry and npm @sentry/mcp-server, 2026-09-26
  read_only: false       # write tools listed in the approving pull request
  evidence: "registry entry + npm view @sentry/mcp-server, 2026-09-26"
  approver: "@acme/platform-security"
- name: playwright
  registry_name: io.github.microsoft/playwright-mcp
  repository: https://github.com/microsoft/playwright-mcp
  transport: stdio
  command: [npx, "@playwright/mcp@0.0.82"]
  version: 0.0.82
  read_only: true
  evidence: "npm view @playwright/mcp version, 2026-09-26"
  approver: "@acme/frontend-leads"
```

Give developers the exact install command next to each entry. Each line below matches the Claude Code allowlist and the Codex identity in the next section: the URLs fit their patterns, and the commands match argument by argument.

```bash
# terminal; Claude Code
claude mcp add --transport http github https://api.githubcopilot.com/mcp/readonly
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp
claude mcp add playwright -- npx @playwright/mcp@0.0.82

# terminal; Codex
codex mcp add github --url https://api.githubcopilot.com/mcp/readonly
codex mcp add sentry --url https://mcp.sentry.dev/mcp
codex mcp add playwright -- npx @playwright/mcp@0.0.82
```

In Codex, the requirement key must match the name the developer uses, so `name` is part of the contract, not a label.

Two other catalog forms are worth knowing:

- **A plugin marketplace.** Claude Code has no built-in MCP registry that users browse. Anthropic's managed-MCP documentation suggests distributing approved servers as plugins in a [team plugin marketplace](/en/ecosystem/plugins/team-marketplace/) so developers install them from `/plugin`.
- **A subregistry.** If you run many internal servers, host an aggregator that copies the public registry hourly with `updated_since`, filters it to your approved names and adds your own servers. Publishing your own servers to the public registry is covered in [building your own MCP server](/en/ecosystem/mcp/custom-mcp-development/).

## Enforce the catalog in each agent

Every tool enforces the list at a different point, with different matching rules. Render all three files from `servers.yaml`, and gate them in CI with the parity check from [enforcing one policy across every coding agent](/en/org/managed-policy/).

**Claude Code**

Put the allowlist in a managed settings source: server-managed settings from the claude.ai admin console, a deployed `managed-settings.json`, an MDM profile or a registry policy. `allowManagedMcpServersOnly: true` stops users from widening the list in their own settings; denylists still merge from every scope.

```json
{
  "allowManagedMcpServersOnly": true,
  "allowedMcpServers": [
    { "serverUrl": "https://api.githubcopilot.com/mcp/readonly" },
    { "serverUrl": "https://mcp.sentry.dev/*" },
    { "serverCommand": ["npx", "@playwright/mcp@0.0.82"] }
  ],
  "deniedMcpServers": [
    { "serverUrl": "https://*.untrusted.example.com/*" }
  ]
}
```

The matching rules decide whether the list is real:

- Once the list has one `serverUrl` entry, every remote server must match a URL pattern; once it has one `serverCommand` entry, every stdio server must match a command exactly, argument by argument. `["npx", "-y", "server"]` does not match `["npx", "server"]`.
- A `serverName` entry is not a security control, because users choose the name.
- A denylist match always wins.
- To push remote servers to everyone without taking exclusive control, list them under `managedMcpServers` (v2.1.259 or later, per the Claude Code managed-MCP documentation and changelog, checked 2026-09-26). Entries must be `https://` HTTP or SSE servers with no `command`, and they load without an allowlist entry.
- For a fixed set, deploy `managed-mcp.json` to `/Library/Application Support/ClaudeCode/` (macOS), `/etc/claude-code/` (Linux and WSL) or `C:\Program Files\ClaudeCode\` (Windows). It cannot be delivered through server-managed settings.

**Codex**

Codex reads admin constraints from `requirements.toml`. The system file is `/etc/codex/requirements.toml` on Unix and `%ProgramData%\OpenAI\Codex\requirements.toml` on Windows; Codex also reads requirement layers from MDM and enterprise-managed sources. Each approved server is a table keyed by its **name**, with an `identity`:

```toml
[mcp_servers.github.identity]
url = "https://api.githubcopilot.com/mcp/readonly"

[mcp_servers.sentry.identity]
url = { match = "prefix", value = "https://mcp.sentry.dev/" }

[mcp_servers.playwright.identity]
command = { executable = "npx", args = [{ match = "exact", value = "@playwright/mcp@0.0.82" }] }
```

Behaviour, read from the Codex source at the `rust-v0.157.1` tag and `main` on 2026-09-26:

- Once `mcp_servers` is present, Codex **disables every configured server whose name has no entry**, or whose command or URL does not match that entry's identity. A login or connection attempt then fails with "the MCP server is disabled by managed requirements".
- A plain `url = "…"` is an exact string match. Use `{ match = "prefix", … }` or `{ match = "regex", expression = … }` for anything looser; a regex must match the whole value.
- A plain `command = "npx"` pins only the executable and ignores arguments, so it approves every `npx` server. Use the `executable` plus `args` form, which requires the same number of arguments in the same order.
- Plugins carry their own table: `[plugins."<plugin>@<marketplace>".mcp_servers.<name>.identity]`.

**Cursor**

Cursor's organization-level MCP controls could not be verified on 2026-09-26, because cursor.com was unreachable from the environment this page was checked in. The Cursor SDK 1.0.32 type definitions list `team` and `mdm` among its settings sources, so team-level and MDM-delivered settings exist; confirm in your admin dashboard whether they can restrict MCP servers to a list, and record the answer with the date.

Until then, enforce the catalog around Cursor rather than inside it:

- Commit a project-scope `.cursor/mcp.json` that contains only catalog servers, and put it under `CODEOWNERS`.
- Point that file at a gateway profile (next section) so one reviewed entry carries the whole catalog.
- Run the canary check in the verification section on a Cursor machine each release.

## When do you need an MCP gateway?

A gateway is a process that sits between the agent and the MCP servers: the agent connects to one entry, and the gateway starts or proxies the servers behind it. Add one when you need at least one of these:

- **One entry point for several tools.** One profile serves Claude Code, Cursor and other clients, so the tool-level allowlist shrinks to one gateway entry.
- **Isolation.** Stdio servers run in containers instead of in the developer's session.
- **Central controls.** Secret scanning on arguments and responses, signature checks on server images, and call logs in one place.

[Docker MCP Gateway](https://github.com/docker/mcp-gateway) is the verified option on this site. As of 2026-09-26, `docker/mcp-gateway` had 1.6k GitHub stars and its catalog repository `docker/mcp-registry` had 558 stars and 1.5k forks from server submissions (GitHub). Its `gateway run` defaults matter for audit:

| Flag | Default | What it does |
| --- | --- | --- |
| `--log-calls` | on | Logs each tool call with the tool name and argument shape only; raw argument values are not logged |
| `--block-secrets` | on | Scans tool-call arguments and text responses for secret-like values before and after execution |
| `--verify-signatures` | on for Docker MCP images | Requires images referenced by digest and verifies them before pull or run |
| `--block-network` | off | Restricts the servers' network access further |

**Claude Code**

```bash
# terminal; vendor lines from the docker/mcp-gateway README
docker mcp catalog pull mcp/docker-mcp-catalog
docker mcp profile create --name dev-tools \
  --server catalog://mcp/docker-mcp-catalog/github
docker mcp client connect claude-code --profile dev-tools --global
```

Then allowlist the gateway command itself, exactly as the client runs it, so no other stdio server gets through:

```json
{ "serverCommand": ["docker", "mcp", "gateway", "run", "--profile", "dev-tools"] }
```

This entry is an example. Read the command that `docker mcp client connect` actually wrote (`claude mcp list`, then `claude mcp get <name>`) and copy that into the allowlist, because the entry must match argument by argument.

**Codex**

```bash
# terminal; assembled from the README's manual client entry
codex mcp add MCP_DOCKER -- docker mcp gateway run --profile dev-tools
```

Whether `docker mcp client connect` supports Codex was not verified, so add the entry by hand. The matching requirement is:

```toml
[mcp_servers.MCP_DOCKER.identity]
command = { executable = "docker", args = [
  { match = "exact", value = "mcp" },
  { match = "exact", value = "gateway" },
  { match = "exact", value = "run" },
  { match = "exact", value = "--profile" },
  { match = "exact", value = "dev-tools" },
] }
```

**Cursor**

```bash
# terminal; vendor line from the docker/mcp-gateway README
docker mcp profile create --name dev-tools \
  --server catalog://mcp/docker-mcp-catalog/github --connect cursor
```

Commit the resulting gateway entry in `.cursor/mcp.json` and review changes to it like code.

Outside Docker Desktop, run `docker mcp feature enable profiles` first. Profiles can be pushed to and pulled from an OCI registry, which is how one reviewed profile reaches every machine.

Two other gateway routes appear in the research for this site but were not tested here: the LiteLLM proxy lists an MCP gateway alongside its model gateway, and a [Claude apps gateway](/en/claude-code/team/llm-gateway/) policy is one of the managed sources Claude Code reads `managedMcpServers` from. Verify either against its own documentation before you rely on it.

**Traps when you allowlist MCP servers**

- **Registry name is not vendor identity.** Unrelated publishers register lookalike names. Match the repository to the vendor's GitHub organization.
- **A gateway moves the allowlist, it does not remove it.** Once agents trust the gateway entry, the gateway profile is the real allowlist. Review profile changes like policy changes.
- **Call logs are not an activity record.** Docker's call log keeps tool names and argument shape, not values. Use the upstream service's audit log (GitHub, Sentry) to see what was changed.
- **Codex names are contract.** A developer who registers GitHub as `gh` instead of `github` gets it disabled, even with an approved URL.
- **Upgrading Claude Code can widen a fixed set.** Since v2.1.259 (Claude Code changelog), `allowedMcpServers` no longer filters `managed-mcp.json` servers unless they use `${VAR}` expansion. If you relied on it to hide some of them, add `deniedMcpServers` entries instead.
- **Blocked servers vanish silently.** Claude Code drops a blocked server from `/mcp` and `claude mcp list` without saying why. Announce every removal.

A gateway also changes context cost: one entry can expose every tool in its profile. Keep profiles per team, measure with `/context` in Claude Code before and after you connect it, and use the techniques in [reducing MCP token cost](/en/ecosystem/mcp/reducing-mcp-token-cost/) when the tool list grows.

## Audit which servers actually run

Enforcement says what may run; audit says what did. Collect both signals in one place.

- **Claude Code telemetry.** With [OpenTelemetry export](/en/ecosystem/observability/agent-telemetry/) configured, set `OTEL_LOG_TOOL_DETAILS=1` so tool events include MCP server and tool names. Aggregate them by server to see real usage per team.
- **Gateway logs.** Ship the gateway's call log to the same collector and alert on calls to tools outside the profile you expect.
- **Upstream audit logs.** For write-capable servers, the service's own audit log is the record of what changed.

**Copy-paste prompt: monthly MCP allowlist review**

```text
Monthly MCP allowlist review. Inputs: mcp-catalog/servers.yaml, the rendered
managed-settings.json and requirements.toml in this repository, and the CSV
export mcp-usage.csv (columns: date, team, tool, mcp_server, mcp_tool, count).

1. List catalog servers with zero calls in the last 30 days. Propose removal.
2. List any mcp_server in the usage export that is not in the catalog. For
   each, say which enforcement path should have blocked it.
3. For every catalog entry, compare the pinned version with the current
   package version (npm view / PyPI JSON) and flag version bumps that need a
   new review.
4. Confirm the three files agree on names, URLs and commands.
Output a Markdown table per section and a list of pull requests to open.
Do not edit any file.
```

## How do you prove the allowlist holds on every machine?

Nobody reads every tool call. Check the configuration mechanically on a canary machine per platform, then on a sample of the fleet each release.

1. **Negative test in Claude Code.** With `managed-mcp.json` deployed, `claude mcp add --transport http test https://example.com/mcp` must fail with `Cannot add MCP server: enterprise MCP configuration is active and has exclusive control over MCP servers`. Under an allowlist, adding an unlisted server must fail with `not allowed by enterprise policy`. The URL does not need to exist; the policy check rejects the command first.

2. **Inventory check.** `claude mcp list` shows only catalog servers. If a user's own server still appears under `managed-mcp.json`, Claude Code is not reading the file: check the path and its directory permissions. `/status` shows `managedMcpServers` entries it dropped and why.

3. **Name-mismatch test in Codex.** Register an approved URL under a wrong name and confirm Codex disables it. This proves the requirements file is loaded, not only that the right servers happen to be configured.

4. **Gateway check.** Call one tool through the gateway and confirm the call appears in the collector with the team and tool name.

5. **Sign-off.** The tech lead owns the catalog and approves additions; the security owner signs off every write-capable server with production reach; the platform team owns deployment and the checks above. Record each release's results in the policy repository.

The measure to report upward is **enforcement coverage**: the share of sampled machines where the negative tests pass, per tool. Anything below 100% is a deployment bug, not a policy question.

## What breaks when you roll out an MCP allowlist?

**Developers lose a server with no message.** Claude Code removes blocked servers from `/mcp` silently. Recovery: publish the catalog and the removal list before rollout, and point people at the negative-test message so they recognise policy.

**Codex disables an approved server.** The name differs from the requirement key, or the arguments differ (`npx -y …` against an identity without `-y`). Recovery: publish the exact `codex mcp add` line per catalog entry and render requirements from the same file.

**CI jobs fail at startup.** A job that passes `--mcp-config` on a machine with `managed-mcp.json` exits with `You cannot dynamically configure MCP servers when an enterprise MCP config is present`. Recovery: give CI runners their own managed file that contains the servers the job needs.

**A managed server from settings never loads.** `managedMcpServers` rejects `http://` URLs, `command` entries and `${VAR}` references, and Claude Code before v2.1.259 ignores the key. Recovery: read `/status`, fix the entry, and set a minimum client version in your rollout.

**Users widened the list anyway.** `allowManagedMcpServersOnly` is missing, so user-level allowlists merged in. Recovery: add the flag. With more than one managed source, reading the lock across sources needs v2.1.273 or later, according to the Claude Code managed-MCP documentation (checked 2026-09-26).

**A gateway profile change shipped without review.** Someone added a server to the shared profile, and every client picked it up. Recovery: keep profiles in the policy repository, push them to the OCI registry from CI only, and treat a profile diff like an allowlist diff.

## Where to go next with MCP governance

- [Enforcing one policy across every coding agent](/en/org/managed-policy/) — Ship the catalog inside one versioned policy for Claude Code, Codex, Cursor and Copilot.
- [Securing MCP servers](/en/ecosystem/mcp/mcp-security/) — Scanning, read-only modes and prompt-injection tests for each server on the list.
- [MCP security for CTOs](/en/cto-scorecard-guide/mcp-security/) — How to authorize each identity and tool, and what to report upward.
- [Agent identity and secrets](/en/org/agent-identity-and-secrets/) — Which credential each MCP server should hold, and how to rotate it.
- [Team plugin marketplace](/en/ecosystem/plugins/team-marketplace/) — Distribute approved servers as plugins developers install from /plugin.
- [Introduction to MCP](/en/ecosystem/mcp/) — Transports, scopes and config shapes, if you are new to MCP.
