Plugins

Plugins give agents tools for working with services such as your cloud platform or ticketing system. Connect an HTTP API or an existing MCP server. Alternatively, let 2501 run a hosted MCP server from your container image.

Choose a connection

Connection	What you provide	Example
Remote MCP server	The address of a service you operate or subscribe to	`https://tools.example.com/mcp`
Hosted MCP server	An image containing the server	`registry.example.com/ops/mcp-server:1.2`
HTTP API	A base URL and optional API documentation	`https://api.example.com/v1/`

Use HTTPS for external servers. Internal HTTP addresses are supported when they resolve to a permitted private address. A hosted server’s image must run non-root and exchange MCP messages over standard input/output (stdio). Connect HTTP-only servers as remote servers instead. For deployment requirements, see Kubernetes or Docker Swarm. Use a Central when an agent needs a dedicated environment for command-line tools.

Give a Kubernetes MCP server only the permissions its tools need. Read-only access can still read Secrets and return their values to the model and task history. Deny Secret reads in both the server configuration and Kubernetes RBAC. Restrict network access to an unauthenticated internal MCP endpoint.

Add an MCP plugin

Open the form

Open Plugins and choose Add MCP.

Describe the server

Paste its URL, README configuration or docker run command into MCP URL. Wait for detection to finish.

Review the connection

Check the detected name and authentication. For a hosted server, also check its image, arguments and environment variables.

Choose access

Select the credential or OAuth settings below, then choose the plugin’s scope and enabled state.

Save

Save the plugin. Assign it from an agent’s page before expecting that agent to use its tools.

The MCP URL field also takes what a README hands out: an mcpServers entry (Claude, Cursor, Windsurf), a servers entry (VS Code), comments included, or a command line such as claude mcp add or docker run. A pasted docker run command, in a configuration or on its own, fills in the hosted MCP server instead: its image, its arguments, and its -e variables. A variable whose name holds a secret word, such as GITHUB_TOKEN, API_KEY, PGPASSWORD, SSH_PASSPHRASE or accessToken, becomes a credential to choose, and its pasted value is not kept; a name where that word is only part of another, such as BASE_PATH or MAX_TOKENS, stays a plain value. Detection reads the server’s tool list without calling tools. It does not retain tokens pasted in a remote server configuration. For hosted servers, secret-looking environment variables become credential selections: choose a saved credential instead of pasting a token. Plain environment values are visible to people who can read the plugin. A saved plugin does not start a hosted server immediately. Its first task or connection check starts it, which may take longer while the image downloads. For an npx or uvx server, build a container image with the server and pinned dependencies. Set an ENTRYPOINT that speaks MCP over stdio, then push the image to a reachable registry. Make its files readable by the runtime user. Use /tmp for temporary files (HOME also points there). A server published only on npm or PyPI needs an image built for it. Build it in your own pipeline, through your package mirror, and pin the version so that an installation does not change on its own:

FROM node:24-slim
RUN npm install -g @upstash/context7-mcp@4.1.1
ENTRYPOINT ["context7-mcp"]

A hosted server is shared by tasks in one organization and stops after 30 minutes without a call. The engine permits 32 running servers. After a failed start, subsequent uses retry with delays from 5 seconds up to 5 minutes. The MCP handshake allows 60 seconds by default; administrators can adjust MCP_HOSTED_HANDSHAKE_TIMEOUT_MS. A connection check waits up to 45 seconds for startup, so check again if it reports that the server is still starting.

Manage plugins

Only administrators can create, edit, enable, disable or delete plugins. Organization administrators manage their organization’s plugins, with read-only access to tenant-wide plugins. For hosted servers, they can only turn off their organization’s server. Tenant-level administrators also manage tenant-wide plugins and hosted server configuration. Other users have read-only access. Go to Command Center → Plugins. The table shows each plugin’s state, description, kind, authentication, how many agents of the organization use it (Used by), scope, and when it was created or last updated. The HTTP API tab shows the base URL, document count and location in place of the description and kind. Open a row to reach the plugin’s page, where Delete removes an unassigned plugin. The plugin page keeps scope, enabled state and Save Changes in its top bar. Its name, description, connection and authentication fields appear in one form. Create a plugin through the public API with a custom name, an optional description, and an anonymous connection:

{
  "name": "Customer VMware MCP",
  "description": "Read-only inventory endpoint",
  "org_id": "<organization ID>",
  "connection": {
    "transport": "streamable-http",
    "url": "https://mcp.example.com/mcp",
    "authentication": { "method": "anonymous" }
  }
}

Add an HTTP API plugin

Open Plugins, select the HTTP API tab, then select Add HTTP API. Enter a name and Base URL. Under Run HTTP API from, choose Main executor or a cluster in the selected organization. The location cannot change after creation. Create another plugin to use another location. Choose Anonymous, Bearer token or API key header authentication. For a token or API key, select a saved Secret or Vault path credential. Add API documentation if needed, save the plugin, then assign it to an agent. Select Check connection to test reachability from the selected executor. For HTTPS, this includes the TLS handshake. The check sends no HTTP request or credential, so it does not verify API authentication or operation permissions.

Choose MCP authentication

In the form	What to supply	Who uses it
Bearer token	A saved Secret or Vault path, for example `Inventory token`	Every assigned agent
API key	A credential and header, for example `X-Api-Key`	Every assigned agent
OAuth	The provider’s client settings, then Connect account	Assigned agents in the connected organization
Anonymous / Agent managed	No connection credential	Use when the service supports this mode

Bearer and API-key credentials belong to the plugin. You do not need to assign that credential separately to every agent. For a server that accepts each agent’s token as a tool argument, choose Anonymous / Agent managed and assign that token to the agent’s accessible credentials. Give the agent only credentials that this server may receive. For these connections and hosted servers, {{secret:<name>}} resolves an accessible credential immediately before sending the call. An inaccessible credential blocks the call before transmission. Bearer, API-key and OAuth plugins reject these placeholders because they authenticate with their configured credentials.

Connect an OAuth account

Save the OAuth settings

Select OAuth, complete the requested client settings and save the plugin.

Authorize the account

Choose Connect account and follow the sign-in page or device-code instructions.

Check the connection

Return to an assigned agent and choose Check connection.

For a plugin shared across organizations, connect an account in each organization that uses it. If the browser return cannot load, use Paste the address your browser ended on to complete the sign-in. Reconnect account replaces the previous authorization.

Only administrators who can edit the plugin can connect its account. Hosted server configuration requires a tenant-level administrator. An organization administrator can turn off their organization’s hosted server, but cannot edit it or turn it back on.

For a pre-registered client, copy the exact redirect URL shown in the form. Keep Command Center and engine BASE_URL set to that public Command Center origin. Store the client secret as a credential. Automatic registration uses a client metadata document when supported; choose Dynamic registration when the provider supports registration but cannot fetch that document from Command Center. Otherwise use a pre-registered client. The equivalent API configuration for a pre-registered public client is:

{
  "connection": {
    "transport": "streamable-http",
    "url": "https://mcp.example.com/mcp",
    "authentication": {
      "method": "oauth",
      "scopes": ["read"],
      "client": {
        "registration": "pre_registered",
        "client_id": "your-client-id"
      }
    }
  }
}

A pre-registered client becomes confidential when it names an existing Secret or Vault path credential in client.client_secret_credential_id, and client_secret_basic or client_secret_post is then chosen from what the provider advertises. The credential must be readable by every organization the plugin serves, so a tenant-wide plugin needs a tenant-wide credential, and agents need no grant for it. This credential holds the client secret, not an access token. When less than a minute or a tenth of its lifetime is left, whichever is longer, the next connection check renews an access token if the provider supplied a refresh token. A running task checks its connections before each turn, when the token must also outlast the turn, seven minutes at most, and again before each call. An MCP server that answers 401 processed nothing: the token is renewed however long it has left, and a call is sent again once with it; a connection it refused reconnects with the new token at the next turn, and a connection check tries again at once. Concurrent checks share one exchange and keep the same authorized account, across engine processes too, so a refresh token the provider rotates is used once. An open task session takes the new token without reconnecting, and the renewal does not appear as an account change. Automatic registration asks for refresh support: the metadata document declares it, and dynamic registration requests it when the provider advertises it. For a pre-registered client, enable the provider’s refresh-token grant if you want automatic renewal. Nothing renews an account in the background: an access token that expired while nobody used the plugin reads Connected, renews on next use when the account holds a refresh token or is a service account, and Reconnect needed when it holds neither. GET /api/v1/plugins/{id}/oauth says which in authorization.renewable. If renewal is refused, use Reconnect account. For missing permissions, add the required scopes and authorize again. Access tokens must fit within 8192 characters. An issuer mismatch requires checking the provider configuration before reconnecting.

Connect Microsoft Entra ID

In Entra App registrations, create a registration. Choose a Web redirect URI. Copy the exact Redirect URL to register with your provider from the plugin form.

Create the credential

Under Certificates & secrets, create a client secret. Store its value as a 2501 Secret credential.

Grant permissions

Under API permissions, add the MCP server’s delegated permissions and grant admin consent if required. For device-code sign-in, also enable Allow public client flows under Authentication.

Connect in 2501

Select a pre-registered OAuth client. Enter the Application (client) ID, select the secret credential, and enter the scopes below. Save, then choose Connect account.

Use the MCP server’s scope, such as api://<application ID>/mcp.read. Add offline_access for renewal and openid profile to display the account name. Do not mix that API’s scopes with Microsoft Graph scopes. Use your tenant’s issuer, https://login.microsoftonline.com/<tenant ID>/v2.0. The common and organizations endpoints allow sign-in from multiple tenants and do not support service accounts. For a service account, grant the MCP server’s Application permission and admin consent instead. Select Sign in as a service account and use the single scope api://<application ID>/.default.

Connect an OAuth service account

A service account uses the OAuth client credentials grant without browser consent. Select Sign in as a service account, then supply a pre-registered client ID and its Secret or Vault path credential. Save and connect the account in each organization that uses the plugin. The provider must support client credentials. 2501 requests a new token when renewal is needed during use. In the API, a service account is "grant": "client_credentials" on an OAuth authentication whose client is pre-registered with a client_secret_credential_id.

Advanced setting	When to use it
`audience`	The provider requires the target API, as Auth0 does. 2501 sends it on authorization, token and device requests.
`metadata_url`	The provider publishes its metadata at another HTTPS URL, as Azure AD B2C does for a user flow.
Client authentication: Private key (JWT) (`private_key_jwt`)	Authenticate with a private key instead of a client secret. Choose a Secret or Vault path containing a PKCS #8 PEM key. Supply the provider’s key ID if required. Select RS256 (default) or ES256.

These settings also apply to user OAuth connections. The provider must support the selected client authentication method.

Run hosted MCP servers without internet access

Copy the server’s image into a reachable registry and use that image reference in the plugin. Its tools must also reach the services they use.

Platform	Registry access
Kubernetes	Set `MCP_HOSTED_IMAGE_PULL_SECRETS` in `engine.extraEnv` to comma-separated Secret names in the hosted pods’ namespace. If unset, it uses the executor pull secret. An empty value lets the namespace’s default service account supply pull secrets.
Docker Swarm	Add the registry login to `auths` in the `registry-auth` secret’s Docker `config.json`, or pull or load the image on every eligible manager. Credential helpers are not supported.

On Docker, the engine pulls an image the machine lacks with the login docker login stored for that registry in the engine’s Docker configuration: config.json in the directory DOCKER_CONFIG names, or ~/.docker, inside the engine’s container, so mount the file into it and point DOCKER_CONFIG at its directory. Credential helpers are not read. Otherwise pull or load the image on the engine’s machine first (docker pull, or docker load from a saved image): the engine uses an image the machine already has. See the deployment requirements for Kubernetes and Docker Swarm.

Assign plugins to an agent

Anyone who can edit an agent can add or remove its plugins. In Command Center, the create form preselects enabled plugins that need no account connection. These include anonymous plugins, hosted servers, and Bearer or API-key plugins with a saved credential. An agent created through the public API, CSV or JSON import, or AI Assistant receives only the plugins named in that request. A plugin the agent’s organization cannot use - unknown, not visible to you, or scoped to another organization - is refused with 400 BAD_REQUEST before anything is saved. field names the request field (plugin_id or plugin_ids) and details.plugin_ids lists the refused plugins.

Check an assigned connection

On the agent’s plugin list, Check connection tests access and lists tools without calling them. Success confirms connectivity at that moment. It does not prove permission to perform every operation or guarantee future availability.

Result	Next action
Authentication required or refused	Connect the account or check the selected credential’s permissions.
Server still starting	Wait for startup, then check again.
Image cannot be pulled	Ask your installation administrator to check registry access.
Connection or certificate failure	Check the address, network route and certificate trust.

Task details contain MCP connection history for investigating failures during execution.

If a plugin call loses its response, inspect the operation before trying again. It may already have changed the remote service.

A task accepts at most 200 plugin tools in assignment order. A plugin that exceeds the remaining budget and later plugins are skipped. Tool descriptions are truncated to 2,000 characters. Each input schema is limited to 16 KiB, and each plugin’s accepted definitions to 256 KiB. Reduce the assigned tools or server definitions when tools are missing. Failed connections are retried at the next task turn. That turn waits at most three seconds for a reconnection already in progress.

Change or remove access

An organization plugin is available in that organization; a tenant-wide plugin can be assigned across organizations. Assignment and enablement are separate: saving a plugin does not assign it, and disabling it prevents use by assigned agents.

Turning off or deleting a hosted plugin stops its server, including calls still running. Coordinate the change with the people using it.

Remove all agent assignments before deleting a plugin. Deleting an assigned plugin returns 409 CONFLICT and preserves both the plugin and its assignments; the message names the assigned agents, up to five, and details.agent_ids lists their IDs. Archiving an agent removes its plugin assignments. Moving a plugin to an organization returns 409 CONFLICT while agents outside it are still assigned. Assigning an organization plugin to another organization returns a client error. The plugin 409 CONFLICT answers carry details.reason: plugin_in_use, plugin_move_blocked, or plugin_name_conflict (with field: "name"). Manage automation through the public API reference. For an older plugin without an endpoint, configure its replacement connection while the plugin is disabled, then check it before enabling it. Changing the connection or organization scope can clear connected OAuth accounts and provider trust. Disable an assigned plugin before changing these settings, then reconnect the affected organizations. Use Forget trusted provider only after confirming an intended provider change; its accounts must connect again.

Upgrading from the legacy runtime

Back up the database before upgrading. The upgrade changes the plugin assignment table, which the previous engine cannot read. Returning to the previous version requires restoring that backup, including after an automatic Swarm rollback. Redeploying the previous image alone is insufficient. See Go back.

Stop the old runtime

Stop the old engine and let its calls and cleanup finish. Verify that its plugin containers or pods are gone. Remove any that remain after a forced stop. Keep shared MCP services and independent executors running.

Replace the legacy connection

A legacy plugin reports Migration required until you replace its connection. Disable it, add an MCP endpoint and save. Alternatively, create a hosted plugin under a new name and assign it to the same agents.

Check and enable

Select the replacement credentials or connect each organization’s OAuth account. Check the connection, then enable the replacement. Disable or delete the old plugin if you created another one.

Upgrading from 0.17

Plugin assignments belong to agents. When upgrading from 0.17, each specialty’s plugins are assigned directly to its agents. Manage these assignments on each agent’s page.

VMware settings

Copy the release’s vmware-mcp image into your registry and create a hosted plugin with no arguments. Move the old engine’s VMWARE_* settings into the hosted server’s GOVC_* variables according to their purpose:

Old engine setting	Hosted plugin setting
`VMWARE_MCP_IMAGE`	Image: `<registry>/vmware-mcp:<version>`
Each `VMWARE_*` variable on the engine	The `GOVC_*` variable below that holds the same setting. List the old ones with `kubectl set env deploy/<engine> --list \| grep VMWARE_` (`oc` on OpenShift), then remove them from the engine; on an installation from the chart they can only be in the `engine-extra-env` Secret.
`VMWARE_*` value for the vCenter or ESXi address	`GOVC_URL`
`VMWARE_*` value for the account name	`GOVC_USERNAME`
`VMWARE_*` value for the password	`GOVC_PASSWORD`: select a Secret or Vault path credential
`VMWARE_*` value for accepting a self-signed certificate	`GOVC_INSECURE=1`, only if required

Remove the old engine variables after migration. On Kubernetes, allow the vCenter address range in the hosted pods’ network policy before checking the connection.

API

Deploy

Configure

Choose a connection

Add an MCP plugin

Manage plugins

Add an HTTP API plugin

Choose MCP authentication

Connect an OAuth account

Connect Microsoft Entra ID

Connect an OAuth service account

Run hosted MCP servers without internet access

Assign plugins to an agent

Check an assigned connection

Change or remove access

Upgrading from the legacy runtime

Upgrading from 0.17

VMware settings

​Choose a connection

​Add an MCP plugin

​Manage plugins

​Add an HTTP API plugin

​Choose MCP authentication

​Connect an OAuth account

​Connect Microsoft Entra ID

​Connect an OAuth service account

​Run hosted MCP servers without internet access

​Assign plugins to an agent

​Check an assigned connection

​Change or remove access

​Upgrading from the legacy runtime

​Upgrading from 0.17

​VMware settings

Choose a connection

Add an MCP plugin

Manage plugins

Add an HTTP API plugin

Choose MCP authentication

Connect an OAuth account

Connect Microsoft Entra ID

Connect an OAuth service account

Run hosted MCP servers without internet access

Assign plugins to an agent

Check an assigned connection

Change or remove access

Upgrading from the legacy runtime

Upgrading from 0.17

VMware settings