# Roll out MCP servers to a team with plugins

Handing every teammate an MCP server URL and a credential does not scale. Each person configures each client by hand, nobody knows who has what, and removing access means chasing down local config files.

Plugins replace that with one managed bundle per role. Granting a role access to a server adds the server to the role's plugin, the plugin is published to a private GitHub-backed marketplace, and the team's AI clients install from that marketplace. Later access changes flow through the same path.

This guide walks the whole rollout: registering a server, granting a role, setting up the marketplace, connecting each client, verifying the result, and keeping it current. The [Plugins](/docs/ai-control-plane/mcp-gateway/plugins) reference covers every option along the way.

## Before you start

- An [organization administrator](/docs/ai-control-plane/org-admin/roles-and-permissions). Granting access and publishing the marketplace require the `project:write` scope, and renaming the marketplace requires `org:admin`.
- A role for the team. Roles come from [directory sync](/docs/ai-control-plane/identity/identities/directory-sync-and-roles) or are created under **Organization settings > Team > Roles & Permissions**. Creating a role also creates a plugin of the same name in the organization's oldest active project and assigns the plugin to that role.
- A GitHub account for whoever connects the marketplace to Claude, Cursor, or ChatGPT.

Work in the project that holds the role's plugin. To distribute from another project, first [set up a role plugin in that project](/docs/ai-control-plane/mcp-gateway/plugins#set-up-a-role-plugin-in-another-project).

## Register or build an MCP server

Open **MCP Gateway > MCP** and select **Add new**. The **Add MCP server** page offers one option per kind of server:

- **From the catalog** installs a reviewed third-party server. See [MCP Catalog](/docs/ai-control-plane/mcp-gateway/catalog).
- **Hosted remotely** opens the **New remote MCP server** form, which takes an **MCP server URL** and an optional **Display name**. **Verify connectivity** checks the URL before the server is created. See [Remote MCP servers](/docs/ai-control-plane/mcp-gateway/remote-servers).
- **Reachable through a tunnel** connects a server inside a private network. See [Tunneled MCP servers](/docs/ai-control-plane/mcp-gateway/tunneled-servers).
- **From your API**, **From an existing source**, and **Write custom code** build a server from an OpenAPI document or TypeScript functions. See [Building MCP servers](/docs/ai-control-plane/mcp-gateway/building-servers).

Finish the server's authentication setup before rolling it out. How a server authenticates decides what the plugin carries, as described in [Connect the team's clients](#connect-the-teams-clients).

## Grant a role access

Open the server and select its **Team Access** tab. Select **Grant access > Role**, choose the team's role, and leave **Connect** set to **All tools** or narrow it to specific tools.

A role grant with **Connect** access is what triggers automatic distribution. Speakeasy adds the server to every plugin in the project that is assigned to that role, then requests a marketplace publish. View and manage access alone do not add the server to a plugin. Granting access never creates a plugin; it only fills the plugins that already exist for the role.

The role's row now shows its plugin under **Distributed via**. Select the plugin and check that the server appears under **MCP servers**. A server shows **Published** once the marketplace includes it and **Unpublished** until then. The server's **Overview** tab also shows how many plugins it is published to.

See [Automatic MCP distribution](/docs/ai-control-plane/identity/identities/automatic-mcp-distribution) for how grants, removals, and manual plugin edits interact.

> **Assignments gate device delivery only**
> A plugin's **Assignments** control delivery to devices running the [device
> agent](/docs/ai-control-plane/reference/device-agent). They do not restrict
> marketplace installs. Anyone with access to the marketplace can install any
> published plugin in Claude Code, Claude Cowork, Cursor, or Codex. Server
> authorization still decides which tools each person can call, so a teammate
> who installs another role's plugin is refused on tool calls their roles don't
> allow.

## Set up the marketplace

Every project publishes its plugins to one private GitHub repository that Speakeasy creates and manages. Each publish overwrites the repository, so make changes in the dashboard rather than in GitHub.

Open **MCP Gateway > Plugins**. The **Your project marketplace** card shows the repository and its status: **Not published**, **Needs syncing**, or **Up to date**.

### Name the marketplace

On a project that has never published, select **Publish now** on the marketplace card. The **Marketplace settings** dialog asks for a **Marketplace name**, which uses lowercase letters, digits, and hyphens and cannot start or end with a hyphen. The default is `-speakeasy` in the organization's oldest project and `--speakeasy` elsewhere.

The marketplace name is what the team types after the plugin slug (`@`). It is separate from the GitHub repository name, `--plugins`. Once the project has published, the name stays fixed until it is changed with **Rename** on the marketplace card.

> **Use the marketplace name, not the repository name**
> In Claude Code settings, the `extraKnownMarketplaces` key and the `@` suffix
> in `enabledPlugins` must both be the marketplace name shown in the dashboard,
> not the GitHub repository name. A mismatch fails silently: Claude Code
> reports no error and the plugin never installs or updates.

### Add GitHub collaborators

After the name is saved, the **Publish Plugins** dialog opens. Under **GitHub Usernames**, add the people who will connect the marketplace to Claude, Cursor, or ChatGPT, then select **Publish**. To add people later, select **Manage collaborators** on the marketplace card and then **Add collaborators**.

Collaborators are added as repository admins, which Cursor requires before it serves the marketplace to a team. GitHub emails each new collaborator an invitation. Accept it from the email or from GitHub notifications before connecting any client. Until someone accepts, the card warns that the marketplace has no active collaborators.

Only administrators who import the marketplace need GitHub access. Team members who receive plugins through Claude Cowork, a Cursor team marketplace served from Cursor, or a ChatGPT workspace do not need an invitation. Members who register the marketplace themselves with the Codex CLI do.

### Sync

Speakeasy publishes automatically when a plugin or its servers change, batching changes made within a few seconds of each other. To publish pending changes immediately, select **Sync changes** on the marketplace card or **Sync** on a plugin's **Overview**. Continue once the card reads **Up to date**.

## Connect the team's clients

Every client starts from the same place. On **MCP Gateway > Plugins**, open the role plugin's **Install** menu and select **GitHub installation (preferred)**. The **Install instructions** sheet asks where the team runs the plugin and then shows that client's steps with the organization's values filled in.

> **Keep install URLs and settings private**
> Install snippets can contain credentials. The Claude Code marketplace URL
> carries an access token, and a private server without OAuth is published with
> an embedded API key. Share snippets only through an approved private channel,
> never in a public repository, ticket, or chat.

How a server authenticates inside the plugin depends on the server. OAuth servers and servers with a user session issuer prompt each person to sign in. A private server without OAuth carries an API key minted at publish time. A public server with environment-backed headers reads those values from each person's environment.

### Claude Code

Select **Claude Code** in the sheet. The settings snippet registers the marketplace, enables the plugin, and turns on automatic updates:

```json
{
  "env": {
    "FORCE_AUTOUPDATE_PLUGINS": "1"
  },
  "extraKnownMarketplaces": {
    "<marketplace-name>": {
      "autoUpdate": true,
      "source": {
        "source": "git",
        "url": "<marketplace-url>"
      }
    }
  },
  "enabledPlugins": {
    "<plugin-slug>@<marketplace-name>": true
  }
}
```

Choose where the snippet goes:

- **My organization** applies it to everyone through Claude Code managed settings. In the Claude organization settings, open the **Claude Code** tab, find **Managed settings**, select **Manage**, and merge the snippet in. Only an Owner or Primary Owner of the Claude organization can edit managed settings.
- **Just me** targets a single machine's `~/.claude/settings.json`. Merge the snippet into the existing file, preserving other settings, or create the file with it. For a team, send each member the snippet privately.

Restart Claude Code and open `/plugin` to check the install. [Anthropic](/docs/ai-control-plane/mcp-gateway/plugins/anthropic) covers the observability plugin and telemetry settings that usually go in the same managed settings.

### Claude Cowork

Select **Claude Cowork** in the sheet. A Claude Owner or Primary Owner adds the marketplace repository from the Claude organization settings with **Add plugins > Sync from GitHub**, selecting the repository the sheet names. The Claude GitHub App must be installed on that repository; if the repository doesn't appear in the picker, install the app and retry.

Set each plugin's installation preference once it syncs. **Required** pre-installs the plugin and members can't remove it; **Installed by default** lets members opt out. Then start a new Cowork session and check the plugin's servers. The Claude-side menu path is described in [Anthropic](/docs/ai-control-plane/mcp-gateway/plugins/anthropic#claude-cowork).

### Cursor

Select **Cursor** in the sheet and copy the repository URL. A Cursor team admin imports it as a team marketplace from the Cursor dashboard, then marks the role's plugin as required or leaves it optional. Turn on **Serve Marketplace From Cursor** so members install without their own GitHub access, and **Enable Auto Refresh** so published changes arrive without a manual refresh.

Cursor team marketplaces have their own access controls in place of plugin assignments. See [Cursor](/docs/ai-control-plane/mcp-gateway/plugins/cursor) for the full import and its settings.

### Codex

Codex can receive the marketplace two ways:

- Through a ChatGPT workspace. A workspace admin imports the repository under **Admin > Plugins** and sets each plugin's installation policy per role. Imported plugins reach nobody until a policy is set. See [OpenAI](/docs/ai-control-plane/mcp-gateway/plugins/openai).
- Through the Codex CLI on a single machine. Select **OpenAI Codex** in the sheet for the commands: `codex plugin marketplace add` with the repository URL, then an entry in `~/.codex/config.toml` that enables `@`. This path reads the private repository directly, so each person needs an accepted collaborator invitation.

> **OpenCode and OpenClaw don't receive servers from plugins**
> Neither client has a plugin marketplace, and the dashboard's install paths
> for them deliver only the [observability
> plugin](/docs/ai-control-plane/mcp-gateway/plugins#platform-plugins). Connect
> MCP servers to OpenCode through its own `mcp` configuration block, as described
> in [OpenCode](/docs/ai-control-plane/mcp-gateway/plugins/opencode#connect-mcp-servers).
> OpenClaw has no plugin path for MCP servers.

## Verify the rollout

Check the rollout from a team member's machine, not only an administrator's:

- **Plugin installed.** In Claude Code, open `/plugin` and check **Installed**. In Codex, run `/plugins`. In Cursor and Claude Cowork, check the organization or team plugins list.
- **Servers listed.** Start a new session and confirm the role's servers appear with their tools. A session that was already running keeps the configuration it started with.
- **Sign-in works.** Use a tool from each server. Servers that require sign-in open the [authorization flow](/docs/ai-control-plane/mcp-gateway/access/user-sessions#what-an-mcp-client-experiences), plus any [upstream connection](/docs/ai-control-plane/mcp-gateway/access/upstream-credentials#what-the-end-user-sees) the server needs.
- **Calls are logged.** Open **Observability > Tool Logs** and filter by **MCP Server** or **User**. The call appears with the member's identity and client. See [Tool logs](/docs/ai-control-plane/observe/tool-logs).

A server that appears in the published plugin but not in the client points to the client's install or update. A server that appears but refuses calls points to sign-in or to the role's **Team Access** grant.

## Keep the plugin current

Access changes flow through the same path as the first grant:

- **Adding a server.** Grant the role **Connect** access on the new server. Speakeasy adds it to the role's plugins and publishes.
- **Removing a server.** Remove the role from the server's **Team Access**. Speakeasy removes the server from the role's plugins unless another role assigned to the same plugin still has access. Tool calls are refused right away, even from clients that still hold the older plugin.
- **Editing a plugin directly.** Removing a server from a plugin's **MCP servers** section sticks until a later grant adds it again. Servers with **Platform tools** are never added automatically; add them with **Add Server**.

Each publish gives every changed plugin a new version, so clients always see it as newer. How each client picks the change up:

- **Claude Code** updates marketplace plugins when `autoUpdate` is on, and `FORCE_AUTOUPDATE_PLUGINS` keeps them updating even when the Claude Code auto-updater is disabled. Restart Claude Code to load the new version.
- **Cursor** picks up changes automatically with **Enable Auto Refresh** on and the Cursor GitHub App installed on the repository; otherwise a team admin selects **Refresh**. Members run **Developer: Reload Window**.
- **ChatGPT and Codex** marketplaces sync from GitHub once a day. Select **Sync now** in the OpenAI admin dashboard for an immediate update.
- **Claude Cowork** reads the synced repository. Start a new session to load changes.
- **ZIP installs** are frozen copies. Download a fresh package and replace the local one.

## Further reading

- [Plugins](/docs/ai-control-plane/mcp-gateway/plugins) is the reference for the marketplace, plugin detail pages, packaging, and assignments.
- [Automatic MCP distribution](/docs/ai-control-plane/identity/identities/automatic-mcp-distribution) covers how roles, grants, and plugins stay in step.
- [Team access](/docs/ai-control-plane/mcp-gateway/access/team-access) explains how grants, blocks, and tool narrowing combine.
- [Device agent](/docs/ai-control-plane/reference/device-agent) delivers plugins per device and honors assignments.

---

Index of every Speakeasy page for agents: [llms.txt](https://www.speakeasy.com/llms.txt). AI control plane and MCP gateway content in one file: [llms-full.txt](https://www.speakeasy.com/llms-full.txt). Any page is available as markdown by appending `.md` to its URL or by requesting it with `Accept: text/markdown`.