Skip to main content
A plugin can include MCP servers (for example an issue tracker), so everyone who installs it gets the same server configuration without setting it up from scratch. After installing it, you supply any credentials the server needs, such as an API key or an OAuth sign-in. A connection can be personal or shared, depending on where the plugin is installed and the installation’s Access setting.

​
The declaration

Declare servers in a root .mcp.json as an mcpServers map. The manifest’s inline mcpServers field takes the same map without the wrapper.
Placeholders. ${NAME} in url or headers is filled in by the installer from the server’s Connect sheet. ${NAME:-default} supplies a fallback when nothing is saved. A plugin server reads only values saved on its installation, not same-named session secrets. Never write a real token into a declaration: it is stored as written. A server can instead run a local command (command, args, env); it takes none of the HTTP credential fields above.
The MCP servers page documents the Customize form for a standalone server. A plugin’s server uses the field names above, and its URL, transport, and headers show read-only on the installed row.

​
Who holds the credential

​
Setups

Each setup combines one entry from the declaration above with where the plugin is installed and how it is distributed: Required installs it for everyone in the scope, Offered lets each organization or member install it. Both are set on the plugin in Customize.

​
1. Per-user OAuth for everyone

For a server that supports OAuth, use the example-mcp entry and install the plugin as Required at the enterprise or organization. tokenScope: "user" defaults Access to Personal, so each member signs in once, from Customize → MCPs or the first session that needs it.

​
2. One organization service account

Use the example-mcp-service-account entry and install the plugin at the organization.
  • The Authorization header holds a placeholder, so the row shows Connect. An org admin enters the token; members never see it.
  • If the server rejects the token (401), the row says Check the credential. If the server also advertises OAuth, the row adds Sign in with OAuth instead.
  • For a service account that signs in with OAuth, drop the header, set tokenScope: "org", and connect that account’s login.

​
3. One key per organization

Put the example-mcp-service-account entry in an enterprise plugin and set it to Offered to organizations.
  • Each organization that installs it owns its installation, so its admin fills in ${EXAMPLE_MCP_SERVICE_ACCOUNT_TOKEN} with that organization’s key.
  • Nothing is connected at the enterprise, and no organization sees another’s key.
  • A Required enterprise plugin creates one enterprise-owned installation instead: one key for all organizations.

​
4. Both in one plugin

Ship both entries, as in the declaration above, and offer the plugin. Each organization that installs it gets two rows: one members sign into, one the org admin connects. Distinct server names let the plugin’s skills say which server to use.