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

Choose a connection

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 a plugin

1

Open the form

Open Plugins and choose Add MCP.
2

Describe the server

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

Review the connection

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

Choose access

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

Save

Save the plugin. Assign it from an agent’s page before expecting that agent to use its tools.
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. 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.

Choose authentication

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.

Connect an OAuth account

1

Save the OAuth settings

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

Authorize the account

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

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. User accounts renew during use when the provider supplies a refresh token. Enable the refresh-token grant for a pre-registered client. 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

1

Register the client

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.
2

Create the credential

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

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.
4

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. These settings also apply to user OAuth connections. The provider must support the selected client authentication method. 2501 does not run pasted npx or uvx commands. Build a container image with the server and pinned dependencies, set an ENTRYPOINT that speaks MCP over stdio, and push it to a reachable registry. Ensure its files are readable by the runtime user and it writes temporary files under /tmp (HOME also points there).

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. See the deployment requirements for Kubernetes and Docker Swarm.

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. 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 can be retried on a later task turn after a three-second delay.

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.
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.
1

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.
2

Replace the legacy connection

The new runtime does not start the removed built-in plugins. 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.
3

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.

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: Remove the old engine variables after migration. On Kubernetes, allow the vCenter address range in the hosted pods’ network policy before checking the connection.