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 reference covers every option along the way.

Before you start

An organization administrator. 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 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.

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.
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.
Reachable through a tunnel connects a server inside a private network. See Tunneled MCP 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.

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.

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 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. 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 <org>-speakeasy in the organization’s oldest project and <org>-<project>-speakeasy elsewhere.

The marketplace name is what the team types after the plugin slug (<plugin>@<marketplace>). It is separate from the GitHub repository name, <org>-<project>-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:

{
  "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 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.

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 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.
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 <plugin-slug>@<marketplace-name>. 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. Connect MCP servers to OpenCode through its own mcp configuration block, as described in OpenCode. 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, plus any upstream connection 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.

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.