> ## Documentation Index > Fetch the complete documentation index at: https://docs.2501.ai/llms.txt > Use this file to discover all available pages before exploring further. # Plugins > Connect agents to tools, choose their credentials, and check access 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. ```mermaid theme={null} flowchart LR A[Choose a server] --> B[Save the plugin] B --> C[Connect an account if needed] C --> D[Assign to an agent] D --> E[Check connection] E --> F[Use tools in a task] ``` ## 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` | 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](https://docs.2501.ai/0.19/deployment/kubernetes.md#hosted-mcp-servers) or [Docker Swarm](https://docs.2501.ai/0.19/deployment/docker-swarm.md#hosted-mcp-servers). Use a [Central](https://docs.2501.ai/0.19/configure/centrals.md) when an agent needs a dedicated environment for command-line tools. ## 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. ## Choose 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. ### 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. > [!NOTE] > > 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. ### 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:///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//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:///.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. | 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. | See the deployment requirements for [Kubernetes](https://docs.2501.ai/0.19/deployment/kubernetes.md#hosted-mcp-servers) and [Docker Swarm](https://docs.2501.ai/0.19/deployment/docker-swarm.md#hosted-mcp-servers). ## 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. ## 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. > [!WARNING] > > 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](https://docs.2501.ai/0.19/api/overview.md). For an older plugin without an endpoint, configure its replacement connection while the plugin is disabled, then check it before enabling it. ## Upgrading from the legacy runtime > [!WARNING] > > 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](https://docs.2501.ai/0.19/deployment/upgrade.md#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: | Old engine setting | Hosted plugin setting | | - | - | | `VMWARE_MCP_IMAGE` | Image: `/vmware-mcp:` | | `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. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.