> ## 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. # Update a plugin > Partial update: omitted fields stay unchanged. Updating a hosted MCP server in any way takes a tenant-level administrator (403). ## OpenAPI ````yaml /0.18/openapi.json post /api/v1/plugins/{id} openapi: 3.0.3 info: title: 2501 Public API version: v1 description: >- The stable, versioned HTTP API for driving 2501 as code. See the API Overview for authentication, the org_id rule, cursor pagination, and the error envelope. servers: - url: https://{command_center_host} variables: command_center_host: default: your-command-center-host description: Your Command Center host security: - bearerAuth: [] paths: /api/v1/plugins/{id}: post: tags: - Plugins summary: Update a plugin description: >- Partial update: omitted fields stay unchanged. Updating a hosted MCP server in any way takes a tenant-level administrator (403). parameters: - schema: type: string required: true name: id in: path requestBody: required: true content: application/json: schema: type: object properties: name: type: string minLength: 1 maxLength: 255 description: >- No control characters such as a line break. Unique, ignoring case, within the plugin's organization and against tenant-wide plugins; a tenant-wide plugin's name is unique across the tenant (409, details.reason plugin_name_conflict). description: type: string maxLength: 2000 description: >- What the plugin is for; the agent reads it to decide when to use the plugin. Required for an HTTP API, up to 1,800 characters. connection: oneOf: - $ref: '#/components/schemas/PluginEndpointConnectionInput' - $ref: '#/components/schemas/PluginHostedServerConnectionInput' - $ref: '#/components/schemas/PluginHttpApiConnectionInput' - nullable: true description: >- Replaces the whole connection; it cannot be removed. A plugin without a connection can take one, and an MCP endpoint and a hosted MCP server can swap, only in an update that leaves the plugin disabled. An HTTP API never becomes an MCP server, or the reverse (400): create a new plugin. Switching to a hosted MCP server takes a tenant-level administrator (403). enabled: type: boolean description: >- Turns the plugin on or off for every agent that holds it, from their next turn; off keeps the assignments. org_id: type: string nullable: true description: >- Moves the plugin to that organization. Returns 409 (details.reason plugin_move_blocked) while agents outside it still hold it; details.agent_ids lists them. trusted_issuer: type: string maxLength: 2048 format: uri description: >- OAuth only: the authorization server the MCP server names, trusted from this save on. Ignored when the plugin already trusts one. additionalProperties: false responses: '200': description: The updated plugin content: application/json: schema: $ref: '#/components/schemas/Plugin' '400': description: >- Bad request - a field is missing, malformed, or not allowed (VALIDATION_FAILED, BAD_REQUEST, INVALID_CURSOR) content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: >- No credentials, or a key that is invalid, revoked, or expired (UNAUTHORIZED) content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: >- Authenticated but not allowed (FORBIDDEN, ORG_ACCESS_DENIED, STEP_UP_REFUSED, TWO_FACTOR_ENROLLMENT_REQUIRED, LICENSE_CAP_REACHED, LICENSE_EXPIRED) content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: No such row that this caller can see (NOT_FOUND) content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: >- The write conflicts with existing data (CONFLICT, DUPLICATE_KEY, FOREIGN_KEY_VIOLATION, RESOURCE_IN_USE) content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: PluginEndpointConnectionInput: type: object properties: transport: type: string enum: - streamable-http - http-sse description: >- A remote MCP server: streamable-http, or http-sse for one on the older SSE transport. url: type: string format: uri description: >- The MCP server address: http or https, without a user name, password or #fragment. Metadata and link-local addresses are refused. authentication: oneOf: - type: object properties: method: type: string enum: - anonymous required: - method additionalProperties: false - type: object properties: method: type: string enum: - bearer credential_id: type: string description: >- The Secret or Vault path credential the plugin sends, of the plugin's organization or tenant-wide. Required to enable the plugin. A tenant-wide credential takes a tenant-level administrator (403): the plugin sends it to the address it names. required: - method additionalProperties: false - type: object properties: method: type: string enum: - oauth scopes: type: array items: type: string pattern: ^[\x21\x23-\x5B\x5D-\x7E]+$ description: The scopes the account asks for when it signs in. audience: type: string minLength: 1 maxLength: 2048 description: >- The API the tokens are for, sent as the `audience` parameter of the authorization and token requests, as Auth0 asks for. metadata_url: type: string maxLength: 2048 format: uri description: >- Where the authorization server publishes its metadata, for a server whose metadata does not live at its issuer, such as Azure AD B2C. Discovery reads it instead of the server the MCP server names, and the plugin trusts the issuer it names. grant: type: string enum: - authorization_code - client_credentials description: >- client_credentials signs in as a service account, with the client's own credentials and nobody to consent; it needs a pre-registered client with a client secret or a private key. Absent or authorization_code, a person authorizes in a browser. client: oneOf: - type: object properties: registration: type: string enum: - pre_registered description: A client registered with the provider beforehand. client_id: type: string minLength: 1 description: The client id the provider issued. client_secret_credential_id: type: string description: >- The Secret or Vault path credential holding the client secret, which makes the client confidential. Not with private_key. private_key: type: object properties: credential_id: type: string description: >- The Secret or Vault path credential holding the PKCS #8 PEM private key key_id: type: string minLength: 1 maxLength: 256 description: The `kid` the provider knows the public key by algorithm: type: string enum: - RS256 - ES256 description: RS256 when absent. required: - credential_id additionalProperties: false description: >- Authenticate the client with a JWT signed by its private key (`private_key_jwt`, RFC 7523) instead of a client secret. RS256 unless `algorithm` says otherwise. callback: type: string enum: - shared - per_provider description: >- Where the provider sends the browser back after consent: `per_provider`, a callback address of the plugin's authorization server alone, so a provider that does not name itself in its answer can sign in a client without a secret; absent or `shared`, the address every provider shares. required: - registration - client_id additionalProperties: false - type: object properties: registration: type: string enum: - automatic description: >- A Client ID Metadata Document when the provider supports one, otherwise dynamic registration of a public client. required: - registration additionalProperties: false - type: object properties: registration: type: string enum: - dynamic description: >- Dynamic registration even where the provider reads metadata documents, for a provider that cannot reach Command Center. required: - registration additionalProperties: false description: How the OAuth client is registered with the provider. required: - method - client additionalProperties: false - type: object properties: method: type: string enum: - api-key header_name: type: string pattern: ^[!#$%&'*+.^_`|~0-9A-Za-z-]+$ description: >- HTTP authentication header. Reserved HTTP transport and MCP session headers are not accepted. credential_id: type: string description: >- The Secret or Vault path credential the plugin sends, of the plugin's organization or tenant-wide. Required to enable the plugin. A tenant-wide credential takes a tenant-level administrator (403): the plugin sends it to the address it names. required: - method - header_name additionalProperties: false description: >- How the plugin authenticates: anonymous sends no credential, bearer sends one as Authorization: Bearer, api-key sends one in header_name, and oauth signs in with an account per organization. required: - transport - url - authentication additionalProperties: false PluginHostedServerConnectionInput: type: object properties: transport: type: string enum: - stdio description: 'A hosted MCP server: a container image the engine starts.' image: type: string maxLength: 255 pattern: >- ^(?:[A-Za-z0-9-]+(?:\.[A-Za-z0-9-]+)*(?::\d+)?\/)?[a-z0-9]+(?:(?:[._]|__|-+)[a-z0-9]+)*(?:\/[a-z0-9]+(?:(?:[._]|__|-+)[a-z0-9]+)*)*(?::\w[\w.-]{0,127})?(?:@sha256:[a-f0-9]{64})?$ description: An image reference such as registry.example.com/team/server:1.2. args: type: array items: type: string maxLength: 4096 maxItems: 64 description: >- The image's own arguments, after its entrypoint: at most 64, each up to 4,096 characters. env: type: array items: anyOf: - type: object properties: name: type: string maxLength: 128 pattern: ^[A-Za-z_][A-Za-z0-9_]*$ description: >- Letters, digits and underscores, not starting with a digit. value: type: string maxLength: 4096 description: >- A plain value, up to 4,096 characters, readable by every role: use credential_id for a secret. required: - name - value additionalProperties: false - type: object properties: name: type: string maxLength: 128 pattern: ^[A-Za-z_][A-Za-z0-9_]*$ description: >- Letters, digits and underscores, not starting with a digit. credential_id: type: string description: >- A Secret or Vault path credential, resolved when the server starts. required: - name - credential_id additionalProperties: false maxItems: 64 description: 'Environment variables: at most 64, each name set once.' required: - transport - image - args - env additionalProperties: false PluginHttpApiConnectionInput: type: object properties: transport: type: string enum: - http-api description: An HTTP API the agent calls directly. base_url: type: string format: uri description: >- Every request goes to a relative path under it, so it cannot carry query parameters. http or https, without a user name, password or #fragment. location: oneOf: - type: object properties: kind: type: string enum: - main description: The engine's own executor. required: - kind - type: object properties: kind: type: string enum: - satellite description: A registered cluster. cluster_id: type: string minLength: 1 description: The cluster, in the plugin's organization. required: - kind - cluster_id description: >- Where requests leave from: main, the engine's own executor, or satellite, a registered cluster named by cluster_id in the plugin's organization. Fixed once the plugin is created; create a new plugin to use another location. authentication: oneOf: - type: object properties: method: type: string enum: - anonymous required: - method additionalProperties: false - type: object properties: method: type: string enum: - bearer credential_id: type: string minLength: 1 description: >- The Secret or Vault path credential the plugin sends, of the plugin's organization or tenant-wide. Required. A tenant-wide credential takes a tenant-level administrator (403): the plugin sends it to the address it names. required: - method - credential_id additionalProperties: false - type: object properties: method: type: string enum: - api-key header_name: type: string pattern: ^[!#$%&'*+.^_`|~0-9A-Za-z-]+$ description: >- HTTP authentication header. Reserved HTTP transport and MCP session headers are not accepted. credential_id: type: string minLength: 1 description: >- The Secret or Vault path credential the plugin sends, of the plugin's organization or tenant-wide. Required. A tenant-wide credential takes a tenant-level administrator (403): the plugin sends it to the address it names. required: - method - header_name - credential_id additionalProperties: false description: >- How the plugin authenticates: anonymous sends no credential, bearer sends one as Authorization: Bearer, and api-key sends one in header_name. required: - transport - base_url - location - authentication additionalProperties: false Plugin: type: object properties: description: type: string description: >- What the plugin is for; the agent reads it to decide when to use the plugin. connection: oneOf: - $ref: '#/components/schemas/PluginEndpointConnection' - $ref: '#/components/schemas/PluginHostedServerConnection' - $ref: '#/components/schemas/PluginHttpApiConnection' - nullable: true description: >- Null for a legacy plugin without an endpoint, or a stored connection that cannot be read, which cannot be enabled until its connection is saved again. document_count: type: integer description: An HTTP API's API documents. Only the plugin list carries it. hosted_server: type: boolean description: >- Whether the plugin runs a hosted MCP server, also when its stored connection is unreadable and sent as null. id: type: string name: type: string enabled: type: boolean description: >- Off stops every agent from using the plugin and keeps the assignments. tenant_id: type: string org_id: type: string nullable: true description: Null for a tenant-wide plugin. created_at: type: string format: date-time updated_at: type: string format: date-time required: - description - connection - hosted_server - id - name - enabled - tenant_id - org_id - created_at - updated_at Error: type: object properties: code: type: string example: VALIDATION_FAILED message: type: string example: Validation failed request_id: type: string example: req_3702b7e7-... field: type: string description: Set when one input is at fault errors: type: array items: type: object properties: field: type: string message: type: string required: - field - message description: Set when several inputs are at fault details: type: object additionalProperties: nullable: true required: - code - message - request_id PluginEndpointConnection: type: object properties: transport: type: string enum: - streamable-http - http-sse description: >- A remote MCP server: streamable-http, or http-sse for one on the older SSE transport. url: type: string description: >- The MCP server address: http or https, without a user name, password or #fragment. Metadata and link-local addresses are refused. authentication: oneOf: - type: object properties: method: type: string enum: - anonymous required: - method - type: object properties: method: type: string enum: - bearer credential_id: type: string description: >- The Secret or Vault path credential the plugin sends, of the plugin's organization or tenant-wide. Required to enable the plugin. A tenant-wide credential takes a tenant-level administrator (403): the plugin sends it to the address it names. required: - method - type: object properties: method: type: string enum: - oauth scopes: type: array items: type: string pattern: ^[\x21\x23-\x5B\x5D-\x7E]+$ description: The scopes the account asks for when it signs in. audience: type: string minLength: 1 maxLength: 2048 description: >- The API the tokens are for, sent as the `audience` parameter of the authorization and token requests, as Auth0 asks for. metadata_url: type: string description: >- Where the authorization server publishes its metadata, for a server whose metadata does not live at its issuer, such as Azure AD B2C. Discovery reads it instead of the server the MCP server names, and the plugin trusts the issuer it names. grant: type: string enum: - authorization_code - client_credentials description: >- client_credentials signs in as a service account, with the client's own credentials and nobody to consent; it needs a pre-registered client with a client secret or a private key. Absent or authorization_code, a person authorizes in a browser. client: oneOf: - type: object properties: registration: type: string enum: - pre_registered description: A client registered with the provider beforehand. client_id: type: string minLength: 1 description: The client id the provider issued. client_secret_credential_id: type: string description: >- The Secret or Vault path credential holding the client secret, which makes the client confidential. Not with private_key. private_key: type: object properties: credential_id: type: string description: >- The Secret or Vault path credential holding the PKCS #8 PEM private key key_id: type: string minLength: 1 maxLength: 256 description: The `kid` the provider knows the public key by algorithm: type: string enum: - RS256 - ES256 description: RS256 when absent. required: - credential_id description: >- Authenticate the client with a JWT signed by its private key (`private_key_jwt`, RFC 7523) instead of a client secret. RS256 unless `algorithm` says otherwise. callback: type: string enum: - shared - per_provider description: >- Where the provider sends the browser back after consent: `per_provider`, a callback address of the plugin's authorization server alone, so a provider that does not name itself in its answer can sign in a client without a secret; absent or `shared`, the address every provider shares. required: - registration - client_id - type: object properties: registration: type: string enum: - automatic description: >- A Client ID Metadata Document when the provider supports one, otherwise dynamic registration of a public client. required: - registration - type: object properties: registration: type: string enum: - dynamic description: >- Dynamic registration even where the provider reads metadata documents, for a provider that cannot reach Command Center. required: - registration description: How the OAuth client is registered with the provider. required: - method - client - type: object properties: method: type: string enum: - api-key header_name: type: string description: The header the credential is sent in. credential_id: type: string description: >- The Secret or Vault path credential the plugin sends, of the plugin's organization or tenant-wide. Required to enable the plugin. A tenant-wide credential takes a tenant-level administrator (403): the plugin sends it to the address it names. required: - method - header_name description: >- How the plugin authenticates: anonymous sends no credential, bearer sends one as Authorization: Bearer, api-key sends one in header_name, and oauth signs in with an account per organization. required: - transport - url - authentication PluginHostedServerConnection: type: object properties: transport: type: string enum: - stdio description: 'A hosted MCP server: a container image the engine starts.' image: type: string description: An image reference such as registry.example.com/team/server:1.2. args: type: array items: type: string maxItems: 64 description: >- The image's own arguments, after its entrypoint: at most 64, each up to 4,096 characters. env: type: array items: anyOf: - type: object properties: name: type: string description: >- Letters, digits and underscores, not starting with a digit. value: type: string description: >- A plain value, up to 4,096 characters, readable by every role: use credential_id for a secret. required: - name - value - type: object properties: name: type: string description: >- Letters, digits and underscores, not starting with a digit. credential_id: type: string description: >- A Secret or Vault path credential, resolved when the server starts. required: - name - credential_id maxItems: 64 description: 'Environment variables: at most 64, each name set once.' required: - transport - image - args - env PluginHttpApiConnection: type: object properties: transport: type: string enum: - http-api description: An HTTP API the agent calls directly. base_url: type: string description: >- Every request goes to a relative path under it, so it cannot carry query parameters. http or https, without a user name, password or #fragment. location: oneOf: - type: object properties: kind: type: string enum: - main description: The engine's own executor. required: - kind - type: object properties: kind: type: string enum: - satellite description: A registered cluster. cluster_id: type: string description: The cluster, in the plugin's organization. required: - kind - cluster_id description: >- Where requests leave from: main, the engine's own executor, or satellite, a registered cluster named by cluster_id in the plugin's organization. Fixed once the plugin is created; create a new plugin to use another location. authentication: oneOf: - type: object properties: method: type: string enum: - anonymous required: - method - type: object properties: method: type: string enum: - bearer credential_id: type: string description: >- The Secret or Vault path credential the plugin sends, of the plugin's organization or tenant-wide. Required. A tenant-wide credential takes a tenant-level administrator (403): the plugin sends it to the address it names. required: - method - credential_id - type: object properties: method: type: string enum: - api-key header_name: type: string description: The header the credential is sent in. credential_id: type: string description: >- The Secret or Vault path credential the plugin sends, of the plugin's organization or tenant-wide. Required. A tenant-wide credential takes a tenant-level administrator (403): the plugin sends it to the address it names. required: - method - header_name - credential_id description: >- How the plugin authenticates: anonymous sends no credential, bearer sends one as Authorization: Bearer, and api-key sends one in header_name. required: - transport - base_url - location - authentication securitySchemes: bearerAuth: type: http scheme: bearer description: >- An API key minted in Command Center (Settings -> API Keys), sent as `Authorization: Bearer 2501_ak_...`. A Command Center session cookie is also accepted. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.