Conector MCP

La función de conector "Model Context Protocol", o MCP, de Claude te permite conectarte a servidores MCP remotos directamente desde la API de Messages sin un cliente MCP separado.



Características principales

• Integración directa con la API: Conéctate a servidores MCP sin implementar un cliente MCP
• Soporte para llamadas a herramientas: Accede a herramientas MCP a través de la API de Messages
• Configuración flexible de herramientas: Habilita todas las herramientas, crea una lista de permitidos con herramientas específicas o una lista de denegados con herramientas no deseadas
• Configuración por herramienta: Configura herramientas individuales con ajustes personalizados
• Autenticación OAuth: Soporte para tokens OAuth Bearer para servidores autenticados
• Múltiples servidores: Conéctate a múltiples servidores MCP en una sola solicitud



Cuándo usa Claude las herramientas MCP

Una vez que un servidor MCP está conectado, Claude llama a sus herramientas cuando la solicitud del usuario corresponde a la capacidad descrita de una herramienta, ya sea de forma explícita ("busca en Jira los bugs abiertos") o implícita ("¿qué está bloqueando el lanzamiento?" con un servidor de Jira conectado).

Claude no llama a una herramienta MCP para preguntas de conocimiento general sobre un servicio conectado. Preguntar "¿cómo funcionan las bases de datos de Notion?" con un servidor de Notion conectado se responde directamente; preguntar "¿qué hay en mi base de datos de Proyectos?" activa la herramienta.

Puedes orientar con qué facilidad Claude llama a las herramientas MCP a través de tu indicación del sistema. Consulta Cuándo usa Claude las herramientas para obtener orientación general y ejemplos de redacción.



Limitaciones

• Del conjunto de funciones de la especificación MCP, actualmente solo se admiten las llamadas a herramientas.
• El servidor debe estar expuesto públicamente a través de HTTP (admite los transportes Streamable HTTP y SSE). Los servidores STDIO locales no se pueden conectar directamente.



Uso del conector MCP en la API de Messages

El conector MCP utiliza dos componentes:

1. Definición del servidor MCP (arreglo mcp_servers): Define los detalles de conexión del servidor (URL, autenticación)
2. MCP Toolset (arreglo tools): Configura qué herramientas habilitar y cómo configurarlas



Ejemplo básico

Este ejemplo habilita todas las herramientas de un servidor MCP con la configuración predeterminada:

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=1000,
    messages=[{"role": "user", "content": "What tools do you have available?"}],
    mcp_servers=[
        {
            "type": "url",
            "url": "https://example-server.modelcontextprotocol.io/sse",
            "name": "example-mcp",
            "authorization_token": "YOUR_TOKEN",
        }
    ],
    tools=[{"type": "mcp_toolset", "mcp_server_name": "example-mcp"}],
    betas=["mcp-client-2025-11-20"],
)

print(response)



Configuración del servidor MCP

Cada servidor MCP en el arreglo mcp_servers define los detalles de conexión:

{
  "type": "url",
  "url": "https://example-server.modelcontextprotocol.io/sse",
  "name": "example-mcp",
  "authorization_token": "YOUR_TOKEN"
}



Descripción de los campos



Configuración del MCP toolset

El MCPToolset se encuentra en el arreglo tools y configura qué herramientas del servidor MCP están habilitadas y cómo deben configurarse.



Estructura básica

{
  "type": "mcp_toolset",
  "mcp_server_name": "example-mcp",
  "default_config": {
    "enabled": true,
    "defer_loading": false
  },
  "configs": {
    "specific_tool_name": {
      "enabled": true,
      "defer_loading": true
    }
  }
}



Descripción de los campos



Opciones de configuración de herramientas

Cada herramienta (ya sea configurada en default_config o en configs) admite los siguientes campos:

Para ver el directorio completo de herramientas proporcionadas por Anthropic y propiedades opcionales como defer_loading, consulta la Referencia de herramientas. Para buscar en conjuntos grandes de herramientas, consulta la herramienta de búsqueda de herramientas.



Combinación de configuraciones

Los valores de configuración se combinan con esta precedencia (de mayor a menor):

1. Ajustes específicos de la herramienta en configs
2. default_config a nivel de conjunto
3. Valores predeterminados del sistema

Ejemplo:

{
  "type": "mcp_toolset",
  "mcp_server_name": "google-calendar-mcp",
  "default_config": {
    "defer_loading": true
  },
  "configs": {
    "search_events": {
      "enabled": false
    }
  }
}

Resulta en:

• search_events: enabled: false (de configs), defer_loading: true (de default_config)
• Todas las demás herramientas: enabled: true (predeterminado del sistema), defer_loading: true (de default_config)



Patrones de configuración comunes



Habilitar todas las herramientas con la configuración predeterminada

El patrón más simple: habilitar todas las herramientas de un servidor:

{
  "type": "mcp_toolset",
  "mcp_server_name": "google-calendar-mcp"
}



Lista de permitidos: habilitar solo herramientas específicas

Establece enabled: false como predeterminado y luego habilita explícitamente herramientas específicas:

{
  "type": "mcp_toolset",
  "mcp_server_name": "google-calendar-mcp",
  "default_config": {
    "enabled": false
  },
  "configs": {
    "search_events": {
      "enabled": true
    },
    "create_event": {
      "enabled": true
    }
  }
}



Lista de denegados: deshabilitar herramientas específicas

Habilita todas las herramientas de forma predeterminada y luego deshabilita explícitamente las herramientas no deseadas. Se recomienda incluir en la lista de denegados las herramientas de escritura o destructivas al crear asistentes de solo lectura, o cuando quieras un paso de confirmación humana antes de los cambios de estado:

{
  "type": "mcp_toolset",
  "mcp_server_name": "google-calendar-mcp",
  "configs": {
    "delete_all_events": {
      "enabled": false
    },
    "share_calendar_publicly": {
      "enabled": false
    }
  }
}



Mixto: lista de permitidos con configuración por herramienta

Combina la lista de permitidos con una configuración personalizada para cada herramienta:

{
  "type": "mcp_toolset",
  "mcp_server_name": "google-calendar-mcp",
  "default_config": {
    "enabled": false,
    "defer_loading": true
  },
  "configs": {
    "search_events": {
      "enabled": true,
      "defer_loading": false
    },
    "list_events": {
      "enabled": true
    }
  }
}

En este ejemplo:

• search_events está habilitada con defer_loading: false
• list_events está habilitada con defer_loading: true (heredado de default_config)
• Todas las demás herramientas están deshabilitadas



Reglas de validación

La API aplica estas reglas de validación:

• El servidor debe existir: El mcp_server_name en un MCPToolset debe coincidir con un servidor definido en el arreglo mcp_servers
• El servidor debe usarse: Cada servidor MCP definido en mcp_servers debe ser referenciado por exactamente un MCPToolset
• Toolset único por servidor: Cada servidor MCP solo puede ser referenciado por un MCPToolset
• Nombres de herramientas desconocidos: Si un nombre de herramienta en configs no existe en el servidor MCP, se registra una advertencia en el backend pero no se devuelve ningún error (los servidores MCP pueden tener disponibilidad dinámica de herramientas)



Tipos de contenido de respuesta

Cuando Claude usa herramientas MCP, la respuesta incluye dos nuevos tipos de bloques de contenido:



Bloque de uso de herramienta MCP

{
  "type": "mcp_tool_use",
  "id": "mcptoolu_014Q35RayjACSWkSj4X2yov1",
  "name": "echo",
  "server_name": "example-mcp",
  "input": { "param1": "value1", "param2": "value2" }
}



Bloque de resultado de herramienta MCP

{
  "type": "mcp_tool_result",
  "tool_use_id": "mcptoolu_014Q35RayjACSWkSj4X2yov1",
  "is_error": false,
  "content": [
    {
      "type": "text",
      "text": "Hello"
    }
  ]
}



Múltiples servidores MCP

Puedes conectarte a múltiples servidores MCP incluyendo múltiples definiciones de servidor en mcp_servers y un MCPToolset correspondiente para cada uno en el arreglo tools:

{
  "model": "claude-opus-5",
  "max_tokens": 1000,
  "messages": [
    {
      "role": "user",
      "content": "Use tools from both mcp-server-1 and mcp-server-2 to complete this task"
    }
  ],
  "mcp_servers": [
    {
      "type": "url",
      "url": "https://mcp.example1.com/sse",
      "name": "mcp-server-1",
      "authorization_token": "TOKEN1"
    },
    {
      "type": "url",
      "url": "https://mcp.example2.com/sse",
      "name": "mcp-server-2",
      "authorization_token": "TOKEN2"
    }
  ],
  "tools": [
    {
      "type": "mcp_toolset",
      "mcp_server_name": "mcp-server-1"
    },
    {
      "type": "mcp_toolset",
      "mcp_server_name": "mcp-server-2",
      "default_config": {
        "defer_loading": true
      }
    }
  ]
}

Con muchas herramientas disponibles, Claude selecciona basándose en los nombres y descripciones de las herramientas. Las descripciones claras y específicas de las herramientas mejoran la precisión de la selección. Para conjuntos grandes de herramientas (docenas de herramientas en varios servidores), considera habilitar defer_loading con la herramienta de búsqueda de herramientas para que solo se muestren las herramientas relevantes por consulta.



Autenticación

Para los servidores MCP que requieren autenticación OAuth, necesitarás obtener un token de acceso. La beta del conector MCP admite pasar un parámetro authorization_token en la definición del servidor MCP. Se espera que los consumidores de la API manejen el flujo OAuth y obtengan el token de acceso antes de realizar la llamada a la API, y que actualicen el token según sea necesario.



Obtener un token de acceso para pruebas

El inspector MCP puede guiarte a través del proceso de obtener un token de acceso para fines de prueba.

1. Ejecuta el inspector con el siguiente comando. Necesitas tener Node.js instalado en tu máquina.

   npx @modelcontextprotocol/inspector

   

2. En la barra lateral de la izquierda, para "Transport type", selecciona "SSE" o "Streamable HTTP".

3. Ingresa la URL del servidor MCP.

4. En el área de la derecha, haz clic en el botón "Open Auth Settings" después de "Need to configure authentication?".

5. Haz clic en "Quick OAuth Flow" y autoriza en la pantalla de OAuth.

6. Sigue los pasos en la sección "OAuth Flow Progress" del inspector y haz clic en "Continue" hasta llegar a "Authentication complete".

7. Copia el valor de access_token.

8. Pégalo en el campo authorization_token de tu configuración del servidor MCP.



Uso del token de acceso

Una vez que hayas obtenido un token de acceso usando cualquiera de los flujos OAuth anteriores, puedes usarlo en tu configuración del servidor MCP:

{
  "mcp_servers": [
    {
      "type": "url",
      "url": "https://example-server.modelcontextprotocol.io/sse",
      "name": "authenticated-server",
      "authorization_token": "YOUR_ACCESS_TOKEN_HERE"
    }
  ]
}

Para obtener explicaciones detalladas del flujo OAuth, consulta la sección de Autorización en la especificación MCP.



Helpers MCP del lado del cliente

Si gestionas tu propia conexión de cliente MCP (por ejemplo, con servidores stdio locales, prompts MCP o recursos MCP), los SDK proporcionan funciones auxiliares que convierten entre tipos MCP y tipos de la API de Claude. Esto elimina el código de conversión manual cuando usas un SDK de MCP para tu lenguaje (por ejemplo, el SDK de MCP para TypeScript) junto con el SDK de Anthropic.



Instalación

Instala tanto el SDK de Anthropic como el SDK de MCP:

pip install "anthropic[mcp]"



Helpers disponibles

Importa los helpers para tu lenguaje:

from anthropic.lib.tools.mcp import (
    async_mcp_tool,
    mcp_message,
    mcp_resource_to_content,
    mcp_resource_to_file,
)

Los nombres de los helpers y las firmas exactas siguen las convenciones de cada lenguaje; esta tabla muestra las formas de TypeScript:



Usar herramientas MCP

Convierte herramientas MCP para usarlas con el tool runner del SDK, que maneja la ejecución de herramientas automáticamente:

from anthropic.lib.tools.mcp import async_mcp_tool
from mcp import ClientSession
from mcp.client.stdio import StdioServerParameters, stdio_client

client = AsyncAnthropic()


async def main() -> None:
    # Conectarse a un servidor MCP
    server_params = StdioServerParameters(command="mcp-server")
    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as mcp_client:
            await mcp_client.initialize()

            # Listar las herramientas y convertirlas para la API de Claude
            tools_result = await mcp_client.list_tools()
            runner = client.beta.messages.tool_runner(
                model="claude-opus-5",
                max_tokens=1024,
                messages=[
                    {"role": "user", "content": "What tools do you have available?"},
                ],
                tools=[async_mcp_tool(tool, mcp_client) for tool in tools_result.tools],
            )

            final_message = await runner.until_done()
            print(final_message)


asyncio.run(main())



Usar prompts MCP

Convierte mensajes de prompt MCP al formato de mensajes de la API de Claude:

from anthropic.lib.tools.mcp import mcp_message

prompt = await mcp_client.get_prompt(name="my-prompt")
response = await client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[mcp_message(message) for message in prompt.messages],
)

print(response)



Usar recursos MCP

Convierte recursos MCP en bloques de contenido para incluir en mensajes, o en objetos de archivo para cargar:

from anthropic.lib.tools.mcp import (
    mcp_resource_to_content,
    mcp_resource_to_file,
)

# Como un bloque de contenido en un mensaje
resource = await mcp_client.read_resource(uri="file:///path/to/doc.txt")
response = await client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                mcp_resource_to_content(resource),
                {"type": "text", "text": "Summarize this document"},
            ],
        }
    ],
)
print(response)

# Como una carga de archivo
file_resource = await mcp_client.read_resource(
    uri="file:///path/to/data.json",
)
uploaded = await client.beta.files.upload(
    file=mcp_resource_to_file(file_resource),
)
print(uploaded.id)



Manejo de errores

Las funciones de conversión lanzan UnsupportedMCPValueError si un valor MCP no es compatible con la API de Claude (en Go, los helpers devuelven un UnsupportedValueError; en Java y C#, lanzan AnthropicInvalidDataException). Esto puede ocurrir con tipos de contenido no compatibles, tipos MIME o enlaces de recursos (resuelve los enlaces de recursos con tu cliente MCP antes de convertir).



Solicitudes por lotes

Puedes incluir mcp_servers en solicitudes de la API de Message Batches. Las llamadas a herramientas MCP a través de la API de Batches tienen el mismo precio que las de las solicitudes regulares de la API de Messages.



Retención de datos

El conector MCP no está cubierto por los acuerdos de ZDR. Los datos intercambiados con servidores MCP, incluidas las definiciones de herramientas y los resultados de ejecución, se retienen de acuerdo con la política estándar de retención de datos de Anthropic.

Para conocer la elegibilidad de ZDR en todas las funciones, consulta API y retención de datos.



Guía de migración

Si estás usando el encabezado beta obsoleto mcp-client-2025-04-04, sigue esta guía para migrar a la nueva versión.



Cambios principales

1. Nuevo encabezado beta: Cambia de mcp-client-2025-04-04 a mcp-client-2025-11-20
2. Configuración de herramientas reubicada: La configuración de herramientas ahora se encuentra en el arreglo tools como objetos MCPToolset, no en la definición del servidor MCP
3. Configuración más flexible: El nuevo patrón admite listas de permitidos, listas de denegados y configuración por herramienta



Pasos de migración

Antes (obsoleto):

{
  "model": "claude-opus-5",
  "max_tokens": 1000,
  "messages": [
    // ...
  ],
  "mcp_servers": [
    {
      "type": "url",
      "url": "https://mcp.example.com/sse",
      "name": "example-mcp",
      "authorization_token": "YOUR_TOKEN",
      "tool_configuration": {
        "enabled": true,
        "allowed_tools": ["tool1", "tool2"]
      }
    }
  ]
}

Después (actual):

{
  "model": "claude-opus-5",
  "max_tokens": 1000,
  "messages": [
    // ...
  ],
  "mcp_servers": [
    {
      "type": "url",
      "url": "https://mcp.example.com/sse",
      "name": "example-mcp",
      "authorization_token": "YOUR_TOKEN"
    }
  ],
  "tools": [
    {
      "type": "mcp_toolset",
      "mcp_server_name": "example-mcp",
      "default_config": {
        "enabled": false
      },
      "configs": {
        "tool1": {
          "enabled": true
        },
        "tool2": {
          "enabled": true
        }
      }
    }
  ]
}



Patrones de migración comunes



Versión obsoleta: mcp-client-2025-04-04

La versión anterior del conector MCP incluía la configuración de herramientas directamente en la definición del servidor MCP:

{
  "mcp_servers": [
    {
      "type": "url",
      "url": "https://example-server.modelcontextprotocol.io/sse",
      "name": "example-mcp",
      "authorization_token": "YOUR_TOKEN",
      "tool_configuration": {
        "enabled": true,
        "allowed_tools": ["example_tool_1", "example_tool_2"]
      }
    }
  ]
}



Descripción de los campos obsoletos