Conector MCP vía API: configuración, OAuth y uso de tool calls

El Conector MCP vía API permite que tu aplicación de IA (por ejemplo, Claude) se conecte directamente a servidores MCP remotos, sin necesidad de instalar un cliente MCP independiente.
Esto simplifica la integración y acelera la adopción de MCP en entornos donde ya trabajas con APIs.

1. Configuración básica

Para habilitar el conector MCP en la API de Claude (o un cliente compatible), es necesario incluir el parámetro mcp_servers en la petición a la API junto con los datos de configuración de cada servidor.

Ejemplo en cURL:

curl https://api.anthropic.com/v1/messages \

  -H "Content-Type: application/json" \

  -H "X-API-Key: $ANTHROPIC_API_KEY" \

  -H "anthropic-version: 2023-06-01" \

  -H "anthropic-beta: mcp-client-2025-04-04" \

  -d '{

    "model": "claude-sonnet-4-20250514",

    "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"

      }

    ]

  }'

Campos clave:

• type: siempre "url" en esta versión.
• url: endpoint HTTPS del servidor MCP.
• name: identificador único del servidor, usado para diferenciar herramientas en las respuestas.

2. Autenticación con OAuth

Si el servidor MCP requiere autenticación, se debe incluir el authorization_token en la configuración del servidor.

Ejemplo:

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


Cómo obtener el token:

1. 1. Usar la herramienta MCP Inspector (npx @modelcontextprotocol/inspector).
      
      
   2. Seleccionar el tipo de transporte (SSE o Streamable HTTP).
      
      
   3. Configurar los ajustes de autenticación.
      
      
   4. Completar el flujo OAuth y copiar el access_token.
      
      
   5. Pegarlo en el campo authorization_token.

3. Uso de tool calls

Una vez conectado, el cliente MCP puede:

• Descubrir herramientas disponibles en el servidor.
  
  
• Ejecutar tool calls enviando parámetros desde la API.

Ejemplo de bloque de uso de herramienta en la respuesta:

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


Ejemplo de bloque de resultado:

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

4. Ventajas del conector MCP vía API

• No requiere instalar un cliente MCP local.
• Compatible con múltiples servidores en una sola petición.
• Soporte para OAuth y control de herramientas permitidas.
• Integra herramientas externas de forma segura y en tiempo real.

Conclusión