Agregar servidores MCP administrados basados en espacios de nombres de conectores (versión preliminar)

Paso 1: Explorar conectores

1. En Microsoft Foundry, abra el proyecto y seleccione Tools en el panel de navegación izquierdo.
2. Seleccione + Agregar herramienta para abrir el catálogo de herramientas.
3. Navegue o busque el conector que desea usar. El catálogo enumera todos los conectores admitidos con detalles como el publicador, los tipos de autenticación admitidos y las acciones disponibles.
4. Seleccione el conector para abrir su página de detalles.

Paso 2: Configurar la conexión

1. En la página de detalles del conector, seleccione Configurar.
2. Rellene las credenciales que requiere el conector. Foundry genera el formulario a partir de la definición del conector. En el caso de los conectores de OAuth2 , Foundry muestra un vínculo de autorización: inicia sesión con la cuenta que quieres usar y, a continuación, autoriza la conexión.
3. Seleccione Conectar para guardar las credenciales y establecer la conexión.

Paso 3: Selección de acciones del conector

1. Una vez establecida la conexión, revise la lista de acciones disponibles (por ejemplo, Create issue for GitHub o Send message for Slack).
2. Seleccione las acciones que quiere que su agente pueda ejecutar.
3. Puede cambiar la selección de acción más adelante editando el servidor MCP en la vista Herramientas .

Paso 4: Agregar la herramienta

1. Revise la configuración: el nombre del conector, la conexión y las acciones seleccionadas.
2. Seleccione Agregar herramienta.

Foundry crea un servidor MCP administrado y lo agrega al agente. Puede verlo y editarlo en cualquier momento desde Herramientas del proyecto.

Paso 1: Adquisición de tokens

Necesita dos tokens independientes: uno para el Catálogo de herramientas de Foundry (un punto de conexión de Azure Machine Learning) y otro para la API de Azure Resource Manager que administra las conexiones del proyecto.

# Token for the Foundry Tools Catalog (AzureML endpoint)
CATALOG_TOKEN=$(az account get-access-token \
  --resource https://ai.azure.com \
  --query accessToken -o tsv)

# Token for Azure Resource Manager (connection and agent management)
ARM_TOKEN=$(az account get-access-token \
  --resource https://management.azure.com \
  --query accessToken -o tsv)

Paso 2: Detección del conector

El catálogo siempre se sirve desde la eastus región, independientemente de la región del proyecto. Elija uno de los escenarios siguientes.

Escenario 1: Enumeración de todos los conectores admitidos

Úselo para examinar el catálogo completo. El catálogo tiene más de 1000 conectores; use skip para paginar. La respuesta incluye totalCount para que pueda determinar cuántas páginas se van a capturar.

RESPONSE=$(curl -sS -X POST \
  "https://eastus.api.azureml.ms/asset-gallery/v1.0/tools" \
  -H "Authorization: Bearer $CATALOG_TOKEN" \
  -H "Content-Type: application/json" \
  -H "x-ms-user-agent: AzureMachineLearningWorkspacePortal/12.0" \
  -d '{
    "freeTextSearch": "*",
    "filters": [
      { "field": "entityContainerId", "operator": "eq", "values": ["connectors-registry-prod-bl"] },
      { "field": "type",              "operator": "eq", "values": ["tools"] },
      { "field": "kind",              "operator": "eq", "values": ["Versioned"] },
      { "field": "labels",            "operator": "eq", "values": ["latest"] }
    ],
    "includeTotalResultCount": true,
    "pageSize": 100,
    "skip": 0
  }')

# Print name, title, and detected auth type for each connector
echo "$RESPONSE" | jq -r '
  .totalCount as $total |
  "Total connectors: \($total)",
  (.value[] | "\(.annotations.name)\t\(.properties.title)\t\(
    .properties["x-ms-connection-parameters"] |
    if . == null then "None"
    elif ([.[].type] | any(. == "oauthSetting")) then "OAuth2"
    elif ([.[].type] | any(. == "securestring")) then "CustomKeys"
    else "None" end
  )")
'

Escenario 2: Recuperación de detalles de un conector específico

Use un filtro exacto eq en annotations/name para capturar un único conector y sus metadatos completos, incluido x-ms-connection-parameters.

CONNECTOR_NAME="github"   # replace with the connector's annotations.name value

RESPONSE=$(curl -sS -X POST \
  "https://eastus.api.azureml.ms/asset-gallery/v1.0/tools" \
  -H "Authorization: Bearer $CATALOG_TOKEN" \
  -H "Content-Type: application/json" \
  -H "x-ms-user-agent: AzureMachineLearningWorkspacePortal/12.0" \
  -d "{
    \"freeTextSearch\": \"*\",
    \"filters\": [
      { \"field\": \"entityContainerId\", \"operator\": \"eq\",  \"values\": [\"connectors-registry-prod-bl\"] },
      { \"field\": \"type\",              \"operator\": \"eq\",  \"values\": [\"tools\"] },
      { \"field\": \"kind\",              \"operator\": \"eq\",  \"values\": [\"Versioned\"] },
      { \"field\": \"labels\",            \"operator\": \"eq\",  \"values\": [\"latest\"] },
      { \"field\": \"annotations/name\",  \"operator\": \"eq\",  \"values\": [\"$CONNECTOR_NAME\"] }
    ],
    \"includeTotalResultCount\": true,
    \"pageSize\": 1
  }")

Después de ejecutar cualquiera de los escenarios, extraiga las variables que necesita para los pasos siguientes:

# Replace .value[0] with the correct index if the search returns multiple results
ENTITY_ID=$(echo "$RESPONSE" | jq -r '.value[0].entityId')
CONNECTOR_NAME=$(echo "$RESPONSE" | jq -r '.value[0].annotations.name')

echo "entityId:       $ENTITY_ID"
echo "connectorName:  $CONNECTOR_NAME"

Paso 3: Crear la conexión del proyecto

Establezca las variables restantes (ENTITY_ID y CONNECTOR_NAME se establecieron en el paso 2):

SUBSCRIPTION_ID=<your-subscription-id>
RESOURCE_GROUP=<your-resource-group>
ACCOUNT_NAME=<your-foundry-account-name>
PROJECT_NAME=<your-project-name>
CONNECTION_NAME=<name-for-this-connection>

CONNECTION_URL="https://management.azure.com/subscriptions/$SUBSCRIPTION_ID\
/resourceGroups/$RESOURCE_GROUP\
/providers/Microsoft.CognitiveServices/accounts/$ACCOUNT_NAME\
/projects/$PROJECT_NAME\
/connections/$CONNECTION_NAME?api-version=2025-04-01-preview"

Realice la solicitud PUT de creación. Los campos obligatorios son connectorName, el toolEntityId del paso 2 y metadata.connectionproperties con el nombre del conector como un objeto JSON serializado en una cadena.

curl -sS -X PUT "$CONNECTION_URL" \
  -H "Authorization: Bearer $ARM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "properties": {
      "authType": "OAuth2",
      "category": "RemoteTool",
      "connectorName": "'"$CONNECTOR_NAME"'",
      "target": "https://placeholder",
      "credentials": {},
      "peRequirement": "NotRequired",
      "metadata": {
        "type": "gateway_connector",
        "toolEntityId": "'"$ENTITY_ID"'",
        "connectionproperties": "{\"connectorName\":\"'"$CONNECTOR_NAME"'\"}"
      }
    }
  }'

Una respuesta correcta devuelve HTTP 200 con overallStatus: "Unauthenticated". El estado permanece Unauthenticated hasta que se completen tanto el paso 4 (consentimiento de OAuth) como el paso 6 (registrar acciones).

Paso 4: Obtener un vínculo de consentimiento de OAuth

Cada usuario final que llama al agente debe completar un consentimiento de OAuth único. Llame a listConsentLinks para generar una URL de autorización por usuario.

CALLER_OID=$(az ad signed-in-user show --query id -o tsv)
CALLER_TID=$(az account show --query tenantId -o tsv)

CONSENT_RESPONSE=$(curl -sS -X POST \
  "$CONNECTION_URL&action=listConsentLinks" \
  -H "Authorization: Bearer $ARM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": [{
      "objectId":      "'"$CALLER_OID"'",
      "parameterName": "token",
      "redirectUrl":   "https://ai.azure.com/nextgen/authConsentPopup",
      "tenantId":      "'"$CALLER_TID"'"
    }]
  }')

CONSENT_URL=$(echo "$CONSENT_RESPONSE" | jq -r '.value[0].link')
echo "Open this URL in a browser to authorize the connector:"
echo "$CONSENT_URL"

Abra la dirección URL en un explorador, inicie sesión en el servicio del conector y apruebe el mensaje de consentimiento. El navegador redirige a una página en blanco de Foundry cuando el consentimiento se completa correctamente; la pasarela ha almacenado el token.

Paso 5: Enumerar las operaciones disponibles

Obtenga el catálogo de operaciones para el conector desde Logic Apps. La región eastus se comparte con la galería de recursos.

OPERATIONS_URL="https://management.azure.com/subscriptions/$SUBSCRIPTION_ID\
/providers/Microsoft.Web/locations/eastus/managedApis/$CONNECTOR_NAME\
/apiOperations?api-version=2016-06-01"

curl -sS "$OPERATIONS_URL" -H "Authorization: Bearer $ARM_TOKEN" \
  | jq -r '.value[] | select(.properties.isWebhook != true and .properties.isNotification != true)
                    | "\(.name)\t\(.properties.summary)"'

Cada fila muestra un nombre de operación (el valor que se pasa a mcpserverConfigProperties.operations[].name en el siguiente paso) y su descripción legible. Omitir las operaciones de webhook y notificación: son desencadenadores, no acciones invocables por agente.

Para inspeccionar el esquema de entrada de una operación específica, expanda inputsDefinition:

OPERATION_NAME=<operation-name>   # for example, GetFileMetadata

curl -sS "https://management.azure.com/subscriptions/$SUBSCRIPTION_ID\
/providers/Microsoft.Web/locations/eastus/managedApis/$CONNECTOR_NAME\
/apiOperations/$OPERATION_NAME?api-version=2016-06-01&\$expand=properties/inputsDefinition" \
  -H "Authorization: Bearer $ARM_TOKEN" \
  | jq '.properties.inputsDefinition'

Utiliza properties y required de inputsDefinition para crear el agentParameters[].schema de cada operación en el siguiente paso. ¿Asignar inputsDefinition.properties[name].title ? x-ms-summary, y copie type y description tal cual.

Paso 6: Registrar las acciones del conector

Emita un segundo PUT con el mismo nombre de conexión. El cuerpo es idéntico al paso 3 más un campo adicional metadata.mcpserverConfigProperties : un objeto JSON con cadena que enumera las operaciones que el agente puede invocar y el esquema de parámetros de cada operación.

# Build mcpserverConfigProperties as a JSON string.
# Replace the operations[] array with the ops you chose in Step 5.
MCP_CONFIG=$(jq -c -n \
  --arg conn "$CONNECTION_NAME" \
  --arg name "$CONNECTOR_NAME" '
  {
    description: "",
    state:       "Enabled",
    connectors: [{
      name:           $name,
      connectionName: $conn,
      displayName:    $name,
      description:    "",
      operations: [
        {
          name:        "GetFileMetadata",
          displayName: "Get file metadata using id",
          description: "",
          userParameters:  [],
          agentParameters: [{
            name: "id",
            schema: {
              type:           "string",
              description:    "The unique identifier of the file.",
              "x-ms-summary": "File Id"
            }
          }]
        }
      ]
    }]
  }')

curl -sS -X PUT "$CONNECTION_URL" \
  -H "Authorization: Bearer $ARM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "properties": {
      "authType": "OAuth2",
      "category": "RemoteTool",
      "connectorName": "'"$CONNECTOR_NAME"'",
      "target": "https://placeholder",
      "credentials": {},
      "peRequirement": "NotRequired",
      "metadata": {
        "type": "gateway_connector",
        "toolEntityId": "'"$ENTITY_ID"'",
        "connectionproperties": "{\"connectorName\":\"'"$CONNECTOR_NAME"'\"}",
        "mcpserverConfigProperties": '"$(jq -Rs . <<< "$MCP_CONFIG")"'
      }
    }
  }'

La respuesta reescribe target como la URL real del servidor MCP gestionado; por ejemplo, https://app-XX.<region>.logic.azure.com/api/connectorGateways/<envId>/mcpServerConfigs/<connectionName>/mcp. Una vez que se hayan completado tanto este PUT como el consentimiento del paso 4, overallStatus cambia a Connected.

Paso 7: Usa la conexión de tu agente

Obtenga la dirección URL del servidor MCP gestionado desde la conexión. Después del paso 6, target es la URL real de la puerta de enlace (ya no https://placeholder).

SERVER_URL=$(curl -sS "$CONNECTION_URL" \
  -H "Authorization: Bearer $ARM_TOKEN" | jq -r '.properties.target')

echo "serverURL: $SERVER_URL"

agente Prompt (SDK de Python):

from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import MCPTool
from azure.identity import DefaultAzureCredential

PROJECT_ENDPOINT = "https://<account>.services.ai.azure.com/api/projects/<project>"

client = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential()
)

agent = client.agents.create_agent(
    model="gpt-4o",
    name="my-connector-agent",
    instructions="You are a helpful assistant.",
    tools=MCPTool(
        server_label=CONNECTION_NAME,
        server_url=SERVER_URL,
        project_connection_id=CONNECTION_NAME
    ).definitions
)
print(f"Created agent: {agent.id}")

Para ver otros lenguajes y opciones en tiempo de ejecución, consulte Conexión de agentes a servidores MCP.

Toolbox (SDK de Python):

toolbox_version = client.beta.toolboxes.create_toolbox_version(
    toolbox_name="my-toolbox",
    description="Toolbox with connector MCP server",
    tools=[
        MCPTool(
            server_label=CONNECTION_NAME,
            server_url=SERVER_URL,
            project_connection_id=CONNECTION_NAME,
            require_approval="never",
        )
    ],
)
print(f"Created toolbox: {toolbox_version.name}, version: {toolbox_version.version}")

Para obtener la configuración y la implementación completas del cuadro de herramientas, consulte Creación y uso de un cuadro de herramientas de Foundry.

La CLI para desarrolladores de Azure (azd) proporciona comandos para crear y administrar conexiones de conector a través de la extensión microsoft.foundry. La azd ruta de acceso admite conectores de OAuth2 , que son los conectores admitidos en Foundry en la actualidad.

Paso 1: Instalación de requisitos previos

azd auth login

# Install the Foundry extensions for azd
azd extension install microsoft.foundry

azd ai project set "https://<account>.services.ai.azure.com/api/projects/<project>"

Paso 2: Creación de la conexión de OAuth2

azd ai connection create registra el conector como una conexión de proyecto con authType=OAuth2 y los metadatos de puerta de enlace necesarios. Pase el nombre del catálogo del conector con --connector-name (por ejemplo, box, linkedinv2, outlook, github).

El nombre del conector es el valor annotations.name que devuelve la API de Foundry Tools Catalog. Cambie al pivote de la API REST y siga paso 2: Detectar el conector para enumerar cada conector o buscar uno específico.

azd ai connection create <connection-name> `
  --connector-name <connector-name>

Por ejemplo, para crear una conexión con el conector Box:

azd ai connection create my-box-conn `
  --connector-name box

Paso 3: Completar el consentimiento de OAuth

La conexión se crea en estado Unauthenticated, y la URL de consentimiento se proporciona en los detalles de la conexión en el momento de su creación. Inspeccione la conexión para recuperarla:

azd ai connection show my-box-conn

Abra la dirección URL de consentimiento devuelta en un explorador e inicie sesión una vez. Después de registrar el consentimiento, las llamadas MCP posteriores se realizan correctamente y overallStatus se realiza la transición a Connected.

Paso 4: Registrar las acciones del conector

Utiliza --metadata mcpserverConfigProperties=<json> para declarar qué operaciones del conector puede invocar el agente y qué parámetros controla el modelo.

Los valores de connectorName, operationNamey los nombres de parámetro de cada operación proceden de foundry Tools Catalog API. Cambie al pivote de la API REST y use el paso 2: Detección del conector para recuperar los metadatos completos de un conector: las operaciones se enumeran en properties.actions[]y los parámetros de cada operación se enumeran en parameters[].

En el ejemplo siguiente se registra una sola operación de GetEmailsV2 en una conexión de Outlook:

$mcp = @{
  connectors = @(@{
    connectorName = "outlook"
    operations = @(@{
      operationName = "GetEmailsV2"
      agentParameters = @(
        @{ name = "folderPath";      required = $true  },
        @{ name = "top";             required = $false },
        @{ name = "fetchOnlyUnread"; required = $false }
      )
    })
  })
} | ConvertTo-Json -Depth 10 -Compress

azd ai connection update my-outlook-conn `
  --metadata "mcpserverConfigProperties=$mcp"

Paso 5: Utilice la conexión desde un agente

Una vez creada la conexión y registrado el consentimiento, haga referencia a ella desde el agente de la misma manera que cualquier otro servidor MCP administrado. La forma más sencilla es añadir la conexión a una Foundry Toolbox y vincular la toolbox a tu agente:

# my-toolbox.yaml
description: Toolbox with connector MCP servers
connections:
  - name: my-box-conn
  - name: my-outlook-conn

azd ai toolbox create my-toolbox `
  --from-file .\my-toolbox.yaml

Para la estructura y el despliegue de agentes de extremo a extremo con azd, consulte Crear y usar una caja de herramientas de Foundry.

Administración de la conexión

# List connections in the project
azd ai connection list

# Show details for one connection
azd ai connection show <connection-name>

# Delete a connection
azd ai connection delete <connection-name> --force