root.agentConnectors object

An agent connector represents a mechanism to enable agents to access information from systems outside of Microsoft 365, often via an MCP Server. Other mechanisms include using OpenAPI descriptions for calling external HTTP APIs. The role of the agent connector is to provide the necessary configuration information to agents or other M365 applications to connect to these external systems. An agent connector can be provided for use by other elements described within the same Unified App Manifest, or as a standalone resource that can be referenced in the Unified App Manifest of other M365 applications.

Properties that reference this object type:

• root.agentConnectors

Syntax

Syntax

{
  "id": "{string}",
  "reusable": {boolean},
  "displayName": "{string}",
  "description": "{string}",
  "toolSource": {
    "plugin": {
      plugin object
    },
    "remoteMcpServer": {
      remoteMcpServer object
    },
    "localMcpServer": {
      localMcpServer object
    }
  }
}

Schema

{
  "type": "object",
  "description": "An agent connector represents a mechanism to enable agents to access information from systems outside of Microsoft 365, often via an MCP Server. Other mechanisms include using OpenAPI descriptions for calling external HTTP APIs. The role of the agent connector is to provide the necessary configuration information to agents or other M365 applications to connect to these external systems. An agent connector can be provided for use by other elements described within the same Unified App Manifest, or as a standalone resource that can be referenced in the Unified App Manifest of other M365 applications.",
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identifier for the agent connector",
      "maxLength": 64
    },
    "reusable": {
      "type": "boolean",
      "description": "Indicates whether this connector can be reused by other applications.",
      "default": false
    },
    "displayName": {
      "type": "string",
      "description": "A user-friendly name for the connector, which can be displayed in UIs.",
      "maxLength": 128
    },
    "description": {
      "type": "string",
      "description": "A brief description of the connector\u0027s purpose and functionality.",
      "maxLength": 4000
    },
    "toolSource": {
      "type": "object",
      "description": "Configuration details for connectors that provide tools for agents, either via a plugin, a remote MCP server or a local MCP server. One and only one of the above properties MUST be defined within a tool source object.",
      "properties": {
        "plugin": {
          "type": "object",
          "description": "Configuration details for connectors that leverage a Plugin Manifest. Either both id and file properties must be provided (for external plugin reference), or only the description property must be provided (for inline plugin manifest).",
          "properties": {
            "id": {
              "type": "string",
              "description": "The unique identifier of the plugin that provides the tools.",
              "maxLength": 64
            },
            "file": {
              "$ref": "#/definitions/relativePath",
              "description": "The relative path to the plugin manifest file within the app package."
            },
            "description": {
              "type": "object",
              "description": "An inlined Plugin Manifest object for simple plugins that do not require a separate file. It should conform to the Plugin Manifest schema https://learn.microsoft.com/microsoft-365-copilot/extensibility/api-plugin-manifest-2.3."
            }
          },
          "additionalProperties": false
        },
        "remoteMcpServer": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "mcpServerUrl": {
              "$ref": "#/definitions/httpsUrl",
              "description": "The URL of the remote MCP Server."
            },
            "mcpToolDescription": {
              "type": "object",
              "description": "Configuration for MCP tool descriptions, either by file reference or inline content (but not both). When this property is present it indicates that dynamic discovery will not be used.",
              "properties": {
                "file": {
                  "$ref": "#/definitions/relativePath",
                  "description": "The relative path to the MCP tool description file within the app package."
                },
                "description": {
                  "type": "object",
                  "description": "An inline JSON object containing the tool descriptions directly. The contents match the results of calling the \u0027tools/list\u0027 method on the MCP Server."
                }
              },
              "additionalProperties": false
            },
            "authorization": {
              "type": "object",
              "description": "Authorization configuration for connecting to the local MCP server. The design mirrors that of Plugin Manifests https://learn.microsoft.com/microsoft-365-copilot/extensibility/api-plugin-manifest-2.",
              "additionalProperties": false,
              "properties": {
                "type": {
                  "type": "string",
                  "enum": [
                    "None",
                    "OAuthPluginVault",
                    "ApiKeyPluginVault",
                    "DynamicClientRegistration"
                  ],
                  "description": "The type of authorization required to invoke the MCP server. Supported values are: \u0027None\u0027 (anonymous access), \u0027OAuthPluginVault\u0027 (OAuth flow with referenceId), \u0027ApiKeyPluginVault\u0027 (API Key with referenceId), \u0027DynamicClientRegistration\u0027 (dynamic client registration with referenceId)."
                },
                "referenceId": {
                  "type": "string",
                  "maxLength": 128,
                  "description": "A reference identifier used when type is OAuthPluginVault, ApiKeyPluginVault, or DynamicClientRegistration. The referenceId value is acquired independently when providing the necessary authorization configuration values. This mechanism exists to prevent the need for storing secret values in the plugin manifest."
                }
              },
              "required": [
                "type"
              ],
              "if": {
                "properties": {
                  "type": {
                    "enum": [
                      "OAuthPluginVault",
                      "ApiKeyPluginVault",
                      "DynamicClientRegistration"
                    ]
                  }
                }
              },
              "then": {
                "required": [
                  "referenceId"
                ]
              }
            }
          },
          "required": [
            "mcpServerUrl"
          ]
        },
        "localMcpServer": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "mcpServerIdentifier": {
              "type": "string",
              "maxLength": 128,
              "description": "The unique identifier of the local MCP Server deployed via some secure mechanism to the user\u0027s desktop."
            },
            "mcpToolDescription": {
              "type": "object",
              "additionalProperties": false,
              "description": "Configuration for MCP tool descriptions, either by file reference or inline content (but not both). When this property is present it indicates that dynamic discovery will not be used.",
              "properties": {
                "file": {
                  "$ref": "#/definitions/relativePath",
                  "description": "The relative path to the MCP tool description file within the app package."
                },
                "description": {
                  "type": "object",
                  "description": "An inline JSON object containing the tool descriptions directly. The contents match the results of calling the \u0027tools/list\u0027 method on the MCP Server."
                }
              }
            },
            "authorization": {
              "type": "object",
              "description": "Authorization configuration for connecting to the local MCP server. The design mirrors that of Plugin Manifests https://learn.microsoft.com/microsoft-365-copilot/extensibility/api-plugin-manifest-2.3",
              "properties": {
                "type": {
                  "type": "string",
                  "enum": [
                    "None",
                    "OAuthPluginVault",
                    "ApiKeyPluginVault",
                    "DynamicClientRegistration"
                  ],
                  "description": "The type of authorization required to invoke the MCP server. Supported values are: \u0027None\u0027 (anonymous access), \u0027OAuthPluginVault\u0027 (OAuth flow with referenceId), \u0027ApiKeyPluginVault\u0027 (API Key with referenceId), \u0027DynamicClientRegistration\u0027 (dynamic client registration with referenceId)."
                },
                "referenceId": {
                  "type": "string",
                  "maxLength": 128,
                  "description": " (maxLength: 128)\tA reference identifier used when type is OAuthPluginVault, ApiKeyPluginVault, or DynamicClientRegistration. The referenceId value is acquired independently when providing the necessary authorization configuration values. This mechanism exists to prevent the need for storing secret values in the plugin manifest."
                }
              },
              "additionalProperties": false,
              "required": [
                "type"
              ],
              "if": {
                "properties": {
                  "type": {
                    "enum": [
                      "OAuthPluginVault",
                      "ApiKeyPluginVault",
                      "DynamicClientRegistration"
                    ]
                  }
                }
              },
              "then": {
                "required": [
                  "referenceId"
                ]
              }
            }
          },
          "required": [
            "mcpServerIdentifier"
          ]
        }
      },
      "additionalProperties": false
    }
  },
  "required": [
    "id",
    "displayName"
  ],
  "additionalProperties": false
}

Properties

id

Unique identifier for the agent connector

Type
string

Required
✅

Constraints
Maximum string length: 64.

Supported values

reusable

Indicates whether this connector can be reused by other applications.

Type
boolean

Required
—

Constraints

Supported values
Default value: False.

displayName

A user-friendly name for the connector, which can be displayed in UIs.

Type
string

Required
✅

Constraints
Maximum string length: 128.

Supported values

description

A brief description of the connector's purpose and functionality.

Type
string

Required
—

Constraints
Maximum string length: 4000.

Supported values

toolSource

Configuration details for connectors that provide tools for agents, either via a plugin, a remote MCP server or a local MCP server. One and only one of the above properties MUST be defined within a tool source object.

Type
toolSource

Required
—

Constraints

Supported values