Conectar Claude con una API interna: herramientas directas o MCP

Para conectar Claude con una API interna, empieza por decidir quién ejecutará la operación. Si tu aplicación ya autentica al usuario, conserva la conversación y accede al sistema interno, puede recibir una petición tool_use, ejecutar una llamada acotada y devolver tool_result. No necesitas añadir MCP para conseguirlo. Si varios clientes necesitan compartir las mismas herramientas, un servidor MCP permite mantener esa interfaz en un solo lugar. Herramientas de cliente en Claude API.

La integración está completa cuando puedes relacionar la petición de Claude con un usuario autorizado, una operación del sistema interno y un resultado comprobable. Que el modelo diga «he consultado el expediente» o que aparezca un conector configurado no demuestra esa cadena.

Esta guía utiliza una consulta de soporte: «¿En qué estado está el expediente EXP-204?». El ejemplo implementa la lectura y la devolución del resultado; después explica cómo ampliar el diseño a cambios aprobados. Las comprobaciones del código se realizaron únicamente con datos ficticios y sin conexión: no son una prueba de acceso a una API, de una sesión MCP ni de seguridad desplegada.

Elige la ruta según dónde se ejecuta el trabajo

Una API HTTP existente no se convierte en MCP por añadir su URL a Claude. Necesitas una interfaz que describa las herramientas y ejecute sus operaciones. Puedes incorporarla a tu aplicación o publicarla mediante un servidor MCP, según el cliente que vaya a consumirla.

El conector MCP de la API y los conectores de usuario tienen configuración, autenticación y condiciones de uso distintas. La ayuda oficial de los conectores de usuario incluye actualmente Free, con un conector personalizado, además de los planes de pago; en organizaciones también intervienen las funciones de administración y la autorización de los miembros. Tener acceso a una de estas rutas no configura automáticamente las demás.

Para una primera integración dentro de tu producto, las herramientas directas evitan mantener un servidor de protocolo adicional. MCP empieza a compensar cuando el equipo responsable de la API necesita conservar una interfaz común entre clientes. En ambos casos siguen haciendo falta autorización, límites de salida y registros de ejecución: la elección del protocolo no resuelve esos requisitos.

Expón una tarea pequeña, no toda la API administrativa

La herramienta del ejemplo se llama consultar_expediente. Acepta un identificador y devuelve estado, fecha de actualización y referencia del resultado. No admite una URL, SQL, comandos ni un cuerpo HTTP arbitrario. Tampoco recibe usuario_id u organizacion_id del modelo: esos valores proceden de la autenticación del backend.

Antes de programarla, acuerda estos detalles con quien mantiene la API:

Es una propuesta de contrato para una API ficticia, no nombres de endpoints de Anthropic. En un sistema multicliente, la organización o tenant debe restringir la consulta antes de obtener los datos. No basta con quitar el campo de organización del resultado después de leer una fila ajena.

El servidor tampoco debe considerar readOnlyHint una autorización. Las anotaciones de herramientas MCP son metadatos y se tratan como información no confiable. Una herramienta anunciada como de lectura puede tener una implementación incorrecta; comprueba el método y los permisos en el código que ejecuta la operación. Especificación de herramientas MCP, revisión 2026-07-28.

Implementa la consulta y devuelve el resultado a Claude

Con herramientas directas, el recorrido es: enviar la definición, recibir tool_use, validar la llamada, consultar el sistema interno y añadir los resultados a la conversación. La aplicación ejecuta la herramienta; el modelo solicita la operación. Tratamiento oficial de llamadas a herramientas.

Define la entrada y el adaptador HTTP

El siguiente código JavaScript contiene la definición, un adaptador HTTP y el ejecutor. Puedes guardar el bloque como expedientes.mjs en tu proyecto. No inicia ningún cliente de Claude ni realiza llamadas por sí solo. Para una integración real, tu capa de autenticación debe proporcionar contexto y la credencial de servicio; el registro registrar debe persistir los eventos en un sistema de auditoría. Ninguno de esos datos debe salir del texto generado por Claude.

La API ficticia devuelve organizacion_id, expediente_id, estado, actualizado_en y resultado_id. Los dos primeros permiten comprobar que la respuesta corresponde al recurso autorizado. La API debe verificar también los encabezados de identidad conforme a su propio mecanismo de confianza: un encabezado enviado por cualquier cliente no identifica a un usuario.

export const herramienta = {
  name: "consultar_expediente",
  description: "Consulta el estado de un expediente accesible al usuario.",
  input_schema: {
    type: "object",
    properties: {
      expediente_id: { type: "string", pattern: "^EXP-[0-9]{1,8}$" }
    },
    required: ["expediente_id"],
    additionalProperties: false
  }
};

export function crearApi(baseUrl, credencialServicio, transporte) {
  const origen = new URL(baseUrl);
  if (origen.protocol !== "https:" || origen.pathname !== "/" ||
      origen.username || origen.password || origen.search || origen.hash) {
    throw new Error("ORIGEN_INVALIDO");
  }
  return {
    async leer(contexto, expedienteId) {
      const ruta = `/v1/organizaciones/${encodeURIComponent(contexto.organizacion_id)}` +
        `/expedientes/${encodeURIComponent(expedienteId)}`;
      const respuesta = await transporte(new URL(ruta, origen), {
        method: "GET",
        redirect: "error",
        signal: AbortSignal.timeout(5000),
        headers: {
          Authorization: `Bearer ${credencialServicio}`,
          "X-Usuario-Id": contexto.usuario_id,
          "X-Organizacion-Id": contexto.organizacion_id,
          Accept: "application/json"
        }
      });
      if (!respuesta.ok) throw new Error("API_NO_DISPONIBLE");
      const lector = respuesta.body.getReader();
      const partes = [];
      let bytes = 0;
      try {
        while (true) {
          const { done, value } = await lector.read();
          if (done) break;
          bytes += value.byteLength;
          if (bytes > 16384) {
            await lector.cancel();
            throw new Error("RESPUESTA_EXCESIVA");
          }
          partes.push(value);
        }
      } finally {
        lector.releaseLock();
      }
      const contenido = new Uint8Array(bytes);
      let posicion = 0;
      for (const parte of partes) {
        contenido.set(parte, posicion);
        posicion += parte.byteLength;
      }
      return JSON.parse(new TextDecoder().decode(contenido));
    }
  };
}

export async function ejecutar(llamada, contexto, api, registrar) {
  const expedienteId = llamada.input?.expediente_id;
  let resultado;
  let decision = "rechazada";
  let resultadoId = null;
  try {
    if (llamada.name !== herramienta.name ||
        !llamada.input || typeof llamada.input !== "object" ||
        Object.keys(llamada.input).length !== 1 ||
        typeof expedienteId !== "string" || !/^EXP-[0-9]{1,8}$/.test(expedienteId)) {
      throw new Error("ENTRADA_INVALIDA");
    }
    if (typeof contexto?.usuario_id !== "string" ||
        !/^[a-z0-9-]{1,64}$/.test(contexto.usuario_id) ||
        typeof contexto.organizacion_id !== "string" ||
        !/^[a-z0-9-]{1,64}$/.test(contexto.organizacion_id) ||
        !Array.isArray(contexto.permisos) || !contexto.permisos.includes("expedientes:leer")) {
      throw new Error("NO_AUTORIZADO");
    }
    const dato = await api.leer(contexto, expedienteId);
    if (dato.organizacion_id !== contexto.organizacion_id ||
        dato.expediente_id !== expedienteId ||
        !["abierto", "en_revision", "cerrado"].includes(dato.estado) ||
        typeof dato.actualizado_en !== "string" ||
        !Number.isFinite(Date.parse(dato.actualizado_en)) ||
        typeof dato.resultado_id !== "string" ||
        !/^RES-[A-Za-z0-9-]{1,64}$/.test(dato.resultado_id)) {
      throw new Error("RESULTADO_INVALIDO");
    }
    resultadoId = dato.resultado_id;
    decision = "completada";
    resultado = {
      expediente_id: dato.expediente_id,
      estado: dato.estado,
      actualizado_en: dato.actualizado_en,
      resultado_id: resultadoId
    };
  } catch (error) {
    const publicos = ["ENTRADA_INVALIDA", "NO_AUTORIZADO", "RESULTADO_INVALIDO"];
    resultado = { error: publicos.includes(error.message) ? error.message : "CONSULTA_FALLIDA" };
  }
  await registrar({
    llamada_id: llamada.id,
    usuario_id: contexto?.usuario_id ?? null,
    organizacion_id: contexto?.organizacion_id ?? null,
    herramienta: herramienta.name,
    expediente_id: typeof expedienteId === "string" && /^EXP-[0-9]{1,8}$/.test(expedienteId)
      ? expedienteId : null,
    decision,
    resultado_id: resultadoId
  });
  return {
    type: "tool_result",
    tool_use_id: llamada.id,
    is_error: decision !== "completada",
    content: JSON.stringify(resultado)
  };
}

export async function continuar(mensajes, respuesta, contexto, api, registrar) {
  const llamadas = respuesta.content.filter(bloque => bloque.type === "tool_use");
  if (llamadas.length === 0) throw new Error("SIN_LLAMADA");
  if (llamadas.length > 4 || llamadas.some(bloque => typeof bloque.id !== "string") ||
      new Set(llamadas.map(bloque => bloque.id)).size !== llamadas.length) {
    throw new Error("LLAMADAS_INVALIDAS");
  }
  const resultados = [];
  for (const llamada of llamadas) {
    resultados.push(await ejecutar(llamada, contexto, api, registrar));
  }
  return [
    ...mensajes,
    { role: "assistant", content: respuesta.content },
    { role: "user", content: resultados }
  ];
}

Para el adaptador real, transporte puede ser fetch del backend; para comprobar el ejecutor sin conexión, es una función ficticia. El origen es configuración de confianza y la herramienta no lo puede cambiar. El adaptador limita el tiempo y el volumen de la respuesta, rechaza redirecciones y utiliza un único método y una ruta determinada.

El ejemplo comprueba un permiso general de lectura y delega a la API la autorización sobre el expediente concreto. Si tu servicio interno solo conoce una cuenta de servicio con acceso a todos los expedientes, tienes que añadir esa comprobación de recurso antes de leer: copiar el usuario a un encabezado no la implementa. El ejecutor filtra la respuesta por campos y no devuelve correos, notas privadas ni credenciales.

continuar está pensado para una respuesta con herramientas de cliente como la del ejemplo. Conserva todo respuesta.content, incluidos los bloques de texto, y coloca el mensaje con resultados inmediatamente después. No utiliza solo content[0]. Cada resultado conserva exactamente el ID de la petición correspondiente. Las respuestas que mezclan herramientas de servidor todavía pendientes tienen reglas adicionales de continuación; aplica la rama documentada para ese caso en lugar de reutilizar esta función sin cambios. Orden de mensajes y resultados.

Relaciona la petición con el resultado del sistema interno

En una petición a Messages API, envías herramienta dentro de tools, junto con el modelo, el presupuesto de salida y los mensajes. El modelo elegido y la autenticación de la API se configuran en tu cliente, fuera de la herramienta. Esta es una respuesta ilustrativa, no una llamada realizada:

{
  "stop_reason": "tool_use",
  "content": [
    { "type": "text", "text": "Voy a consultar el estado del expediente." },
    {
      "type": "tool_use",
      "id": "toolu_ejemplo_204",
      "name": "consultar_expediente",
      "input": { "expediente_id": "EXP-204" }
    }
  ]
}

Supón que la autenticación del backend proporciona el usuario operador-7, la organización org-norte y el permiso expedientes:leer. El adaptador solicita GET /v1/organizaciones/org-norte/expedientes/EXP-204. Si la API autoriza ese recurso y devuelve la respuesta esperada, el mensaje añadido a Claude contiene:

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_ejemplo_204",
      "is_error": false,
      "content": "{\"expediente_id\":\"EXP-204\",\"estado\":\"en_revision\",\"actualizado_en\":\"2026-10-07T08:30:00Z\",\"resultado_id\":\"RES-204-8\"}"
    }
  ]
}

La siguiente petición a Messages API utiliza los mensajes devueltos por continuar y las definiciones de herramientas. Claude ya dispone del dato para explicar que el expediente sigue en revisión. Si vuelve a solicitar una herramienta, la aplicación repite el tratamiento dentro de un límite total de llamadas y tiempo; no mantiene un bucle infinito.

toolu_ejemplo_204 relaciona la solicitud con su tool_result. RES-204-8 identifica el resultado en el sistema interno y debe permitir consultar su evidencia o registro. En una lectura, esa referencia acredita la consulta y su versión temporal; no es un ID de cambio. En una escritura necesitas además el ID de la operación y el estado final. Si el backend no genera estas referencias, incorpóralas a su contrato o usa su identificador equivalente: inventarlas en el modelo o solo en la respuesta visible no demuestra la ejecución.

Cuando falla la autorización, el ejecutor devuelve is_error: true y NO_AUTORIZADO, sin consultar la API. Un resultado de otra organización se descarta aunque la API lo haya devuelto. Si falla la persistencia de auditoría, la función propaga el error y no presenta la lectura como un éxito registrado. Esta decisión debe integrarse en el manejo de errores de tu aplicación.

Si eliges MCP, cambia el adaptador y conserva las reglas de negocio

El servidor MCP puede reutilizar la misma operación acotada, pero debe obtener la identidad desde su autenticación, no desde argumentos de la herramienta. La autenticación de un servidor HTTP protegido verifica token, audiencia o recurso, caducidad y permisos; el acceso a la API interna necesita su propia autorización. No reenvíes sin más el token recibido del cliente MCP al servicio interno. Autorización MCP.

Para diagnosticar un fallo, distingue la respuesta del servidor MCP de la respuesta de tu API interna. En el esquema de autorización HTTP de MCP, un token inválido o caducado corresponde a 401, mientras que permisos insuficientes corresponden a 403. Corregir la credencial del conector no amplía por sí solo los permisos del servicio interno. La aplicación obtiene y renueva el token por su flujo de autorización aprobado; no lo entrega al modelo ni lo incluye en la URL.

No copies la definición de Anthropic literalmente al protocolo. Claude API usa input_schema; una definición MCP utiliza inputSchema y, si declara la forma de salida, outputSchema. Los resultados mcp_tool_use y mcp_tool_result del conector de la API tampoco son los bloques tool_use y tool_result del ejecutor anterior. Mantén un adaptador para cada interfaz.

Conector de Messages API y catálogo fijado

Para la ruta remota habitual del conector MCP de Claude API, necesitas un servidor HTTPS alcanzable por la infraestructura de Anthropic, con transporte HTTP o SSE compatible. El conector admite herramientas; no es acceso general a todas las primitivas MCP ni ejecuta directamente un proceso local stdio.

La documentación consultada el 7 de octubre de 2026 mantiene mcp-client-2025-11-20 y añade mcp-client-2026-09-15 para fijar el catálogo. Esta última beta incluye la funcionalidad anterior. mcp-client-2025-04-04 está obsoleta. Utiliza la cabecera correspondiente a la función que necesites y consérvala en las continuaciones. Configuración y beta del catálogo.

Estos campos ilustran la parte MCP de una petición, con una URL y un token de marcador. No son una petición completa ni credenciales utilizables:

{
  "mcp_servers": [
    {
      "type": "url",
      "name": "expedientes",
      "url": "https://mcp.example.com/mcp",
      "authorization_token": "TOKEN_DE_EJEMPLO"
    }
  ],
  "tools": [
    {
      "type": "mcp_toolset",
      "mcp_server_name": "expedientes",
      "default_config": { "enabled": false },
      "configs": {
        "consultar_expediente": { "enabled": true }
      }
    }
  ]
}

Cada entrada de mcp_servers debe corresponder a exactamente un mcp_toolset. Por defecto las herramientas están habilitadas; aquí se desactivan todas salvo la consulta elegida. Comprueba el nombre exacto: una configuración referida a una herramienta inexistente genera una advertencia, no necesariamente un error de petición. No trates una respuesta HTTP correcta como prueba de que se aplicó la selección deseada.

La beta del catálogo devuelve bloques mcp_tool_listing. Puedes conservar las definiciones recibidas en MCPToolset.tools para fijar lo que Claude verá, manteniendo el mensaje completo del asistente al continuar. Fijar un catálogo no fija los permisos ni la implementación del servidor. Una herramienta con el mismo nombre puede cambiar por detrás. Contrasta el catálogo aprobado, los esquemas y la identidad del servidor en tu control de cambios; aplica la autorización de recurso cuando se ejecute la llamada.

Una API privada no exige abrir toda tu red

Si tu backend ya puede llegar a la API privada, las herramientas directas permiten mantener la ejecución allí y enviar a Claude únicamente el resultado seleccionado. Para un servidor MCP remoto, que la URL se abra desde tu portátil conectado a una VPN no demuestra que Anthropic pueda alcanzarla.

Anthropic documenta también túneles MCP privados: son una vista previa de investigación que requiere acceso, con conexiones salientes mediante una infraestructura de proxy y Cloudflare. Permiten una ruta privada para Messages API y Managed Agents bajo sus condiciones de espacio de trabajo, enrutamiento y certificados. No equivalen a un conector de claude.ai disponible para cualquier cuenta y siguen necesitando la autorización del servicio interno.

El túnel no convierte todo el tratamiento en local: el modelo recibe los resultados necesarios, y hay metadatos de conexión. Además, la tabla actual de retención de datos de Claude API marca el conector MCP y los túneles como no elegibles para ZDR ni HIPAA. Messages API estándar tiene condiciones propias según el acuerdo y el modelo. Que una solicitud funcione técnicamente no demuestra que quede cubierta por un acuerdo de retención concreto.

Claude Code: configuración, conexión y ejecución son pasos distintos

Claude Code admite servidores locales stdio y remotos HTTP. Para añadir un remoto, especifica el transporte, por ejemplo claude mcp add --transport http expedientes https://mcp.example.com/mcp. Para un proceso local, la forma es claude mcp add --transport stdio expedientes -- RUTA_DEL_EJECUTABLE; sustituye el marcador por un programa real aprobado. Son ejemplos de sintaxis, no comandos ejecutados aquí. Configuración oficial de MCP en Claude Code.

Elige además el alcance local, project o user según quién deba usar la configuración. Añadirla no prueba conexión, autenticación ni disponibilidad de la herramienta. Comprueba por separado el estado del servidor, el catálogo visible y el resultado de una operación autorizada. Las confirmaciones dependen del modo y del entorno de ejecución; no presupongas que cualquier escritura de cualquier cliente siempre pedirá permiso.

En los conectores remotos de Claude o Desktop, la conexión procede de la nube de Anthropic; la configuración local de Desktop es una ruta distinta. Si se utilizan credenciales fijas compartidas, el servidor no obtiene automáticamente una identidad diferente para cada miembro. Define cómo distinguirás a los usuarios y sus recursos, o limita expresamente el uso al ámbito que representa esa credencial.

Añade escrituras con una aprobación ligada al cambio concreto

Para ampliar el ejemplo a «cerrar EXP-204», separa consulta, preparación y ejecución. El usuario debe poder ver qué cambiará antes de aprobarlo. Una frase de Claude como «el usuario lo ha aprobado» no sirve como registro de aprobación.

Este contrato ilustrativo muestra las tres peticiones de tu aplicación al backend. Las rutas son del sistema ficticio y no forman parte de MCP:

En el ejecutor de escritura, el backend busca la aprobación almacenada y vuelve a comprobar organización, recurso, acción, huella, caducidad y permiso del solicitante. La comprobación de versión, el consumo de la aprobación y el cambio deben protegerse mediante la transacción o mecanismo equivalente que ofrece el sistema interno. Si el expediente ha cambiado desde la vista previa, devuelve un conflicto y solicita una nueva aprobación; no aplica una aprobación antigua a otro contenido.

La clave de idempotencia debe identificar la operación aprobada y quedar ligada a su organización y parámetros. Si se repite con el mismo cambio, el backend devuelve la operación existente; si cambia el contenido, rechaza la reutilización. Persistir esa relación es necesario para evitar duplicados: el nombre del campo por sí solo no los impide.

Tras un timeout, consulta GET /v1/operaciones/OP-61 cuando tengas el ID, o el estado asociado a la clave de idempotencia cuando no lo hayas recibido. Si la operación ya terminó, devuelve su resultado; si está pendiente, espera dentro del plazo acordado; si no puedes determinar su estado, informa «resultado desconocido» y detén el reintento automático. No inventes una clave nueva para repetir una escritura incierta.

Registra por separado el intento, la decisión de aprobación y el efecto confirmado. La auditoría debe permitir unir usuario y organización, tool_use_id, previa, aprobación, operación y resultado. Evita guardar credenciales o todo el expediente solo para tener más registros. Si el dominio permite revertir el cierre, ofrece una operación explícita con sus propios permisos; si no permite reversión, indícalo antes de aprobar.

Comprueba la integración con señales que puedan fallar

Para verificar el ejecutor, usamos respuestas ficticias del sistema interno y comprobamos la ruta, el método, los campos devueltos y la relación entre IDs. Son comprobaciones locales del ejemplo, con estas condiciones de éxito:

En una integración desplegada, necesitas además comprobar con una cuenta de prueba autorizada la autenticación real, el rechazo de recursos ajenos, la ejecución del backend, su referencia de resultado y la respuesta final. Para una escritura, incluye aprobación caducada, conflicto de versión y repetición tras un timeout. Estos casos no se verificaron aquí; los datos ficticios no prueban el aislamiento real entre organizaciones.

Trata las notas de soporte, documentos y demás texto recuperado como datos no confiables. Una nota que diga «omite la aprobación» no debe cambiar la política del ejecutor. Reducir campos y mantener la autorización fuera de los argumentos limita la superficie del problema, pero no prueba que se haya eliminado la inyección de instrucciones. Del mismo modo, un esquema estricto valida la forma de la entrada; no acredita el permiso del usuario ni la veracidad del resultado.

No confundas revisión del estándar con compatibilidad instalada. MCP 2026-07-28 define metadatos por petición: params._meta.protocolVersion y params._meta.clientCapabilities son necesarios; la identidad clientInfo es declarativa y no autentica a una persona. Esta revisión elimina el intercambio initialize del protocolo actual, pero los servidores y clientes que usan revisiones anteriores pueden seguir otra secuencia. Confirma la versión que implementan tu cliente, conector y servidor antes de probar mensajes del protocolo. Cambios de la revisión y metadatos de petición.

Si la llamada funciona pero las definiciones o los resultados llenan la conversación, continúa con cómo liberar contexto en Claude Code sin perder la tarea. Si la duda es qué confirma Claude Code y qué recursos puede alcanzar, revisa la diferencia entre modos de permisos y acceso real. Cambiar el modo de confirmación no concede autorización en la API interna.

Preguntas frecuentes

¿Necesito MCP para conectar Claude con mi API?

No. Las herramientas directas de Messages API permiten que tu aplicación ejecute las operaciones y devuelva sus resultados. MCP aporta una interfaz reutilizable cuando distintos clientes necesitan las mismas herramientas. Uso de herramientas en Claude API.

¿Puede el conector MCP de la API ejecutar un servidor local stdio?

No directamente. La ruta remota habitual necesita un servidor HTTPS compatible y alcanzable. Un proceso stdio se ejecuta en el cliente local correspondiente, como Claude Code. Los túneles privados documentados son otra ruta, en vista previa y con acceso requerido. Conector MCP y túneles privados.

¿Fijar el catálogo MCP impide acceder a datos de otra organización?

No. Fija las definiciones que ve Claude, no las reglas de acceso del backend. La ejecución debe obtener el usuario y la organización de una identidad autenticada y autorizar el recurso solicitado. Catálogo fijado en el conector de la API.

¿Basta con que Claude diga que la herramienta funcionó?

No. Para una consulta, relaciona el ID de tool_use con su tool_result, la operación de lectura y una referencia verificable del backend. Para un cambio, comprueba además la aprobación y el estado final de la operación. Una respuesta automática sin llamada puede ser válida como explicación, pero no acredita que se hayan leído datos internos.

¿Qué hago si una escritura agota el tiempo de espera?

Comprueba su estado mediante el ID de operación o la misma clave de idempotencia. Un timeout no demuestra que el cambio haya fallado. Si no puedes determinar el resultado, detén la repetición automática y muestra el estado desconocido; repetir con otra clave puede duplicar el efecto.