Saltar al contenido principal
Utiliza herramientas MCP cuando quieras que la API de MKA1 llame a herramientas de un servidor MCP externo durante una respuesta. Define el servidor MCP en tools. Limita qué herramientas puede llamar el modelo con allowed_tools. Usa require_approval cuando quieras que tu aplicación se pause y pregunte al usuario final antes de ejecutar la herramienta. Utiliza X-On-Behalf-Of para el usuario final de la API de MKA1. Pasa las credenciales del servidor MCP en la definición de la herramienta MCP.

​
Llamar a una herramienta MCP directamente

Establece require_approval en 'never' cuando la herramienta pueda ejecutarse de inmediato. 
import { SDK } from '@meetkai/mka1';
import type * as components from '@meetkai/mka1/models/components';

const mka1 = new SDK({
  bearerAuth: `Bearer ${YOUR_API_KEY}`,
});

const response = await mka1.llm.responses.create(
  {
    model: 'gpt-5',
    instructions:
      'Eres un asistente de gestión de proyectos con acceso a Linear vía MCP. Usa las herramientas de Linear cuando el usuario pregunte sobre tareas, bugs o proyectos. Mantén la respuesta final concisa.',
    input: 'Lista mi incidencia de Linear más reciente asignada a mí.',
    store: true,
    stream: false,
    tools: [
      {
        type: 'mcp',
        serverLabel: 'Linear MCP',
        serverDescription: 'Accede a incidencias de Linear a través de MCP.',
        serverUrl: 'https://mcp.linear.app/mcp',
        allowedTools: ['issues.list'],
        headers: {
          Authorization: `Bearer ${process.env.LINEAR_API_KEY}`,
        },
        requireApproval: 'never',
      },
    ],
  },
  { headers: { 'X-On-Behalf-Of': '<end-user-id>' } },
);

// Las llamadas a herramientas MCP aparecen como elementos function_call en la salida
const mcpCalls = response.output.filter(
  (item): item is components.MCPToolCall => item.type === 'mcp_call',
);

const assistantText = response.output
  .filter(
    (item): item is components.OutputMessage =>
      item.type === 'message' && item.role === 'assistant',
  )
  .flatMap(item =>
    item.content.flatMap(content =>
      content.type === 'output_text' ? [content.text] : [],
    ),
  )
  .join('\n\n')
  .trim();

console.log(assistantText);
Este es el flujo más simple. El modelo llama a la herramienta MCP permitida y devuelve el mensaje final del asistente en una sola solicitud. El array output de la respuesta contiene:
  1. function_call — la llamada del modelo a la herramienta descubierta por MCP
  2. function_call_output — los datos devueltos por el servidor MCP
  3. message — la respuesta de texto del modelo resumiendo los resultados

​
Requerir aprobación del usuario final

Establece require_approval en 'always' cuando tu aplicación deba detenerse y esperar una decisión de aprobación. En este flujo, crea la respuesta en modo background, haz polling y busca un elemento mcp_approval_request en output. 
import { SDK } from '@meetkai/mka1';
import type * as components from '@meetkai/mka1/models/components';

const mka1 = new SDK({
  bearerAuth: `Bearer ${YOUR_API_KEY}`,
});

// Paso 1: Crea una respuesta en background con aprobación requerida
let pendingResponse = await mka1.llm.responses.create(
  {
    model: 'gpt-5',
    instructions:
      'Eres un asistente de gestión de proyectos con acceso a Linear vía MCP. Usa las herramientas de Linear cuando el usuario pregunte sobre tareas, bugs o proyectos. Mantén la respuesta final concisa.',
    input: 'Lista mi incidencia de Linear más reciente asignada a mí.',
    background: true,
    store: true,
    stream: false,
    tools: [
      {
        type: 'mcp',
        serverLabel: 'Linear MCP',
        serverDescription: 'Accede a incidencias de Linear a través de MCP.',
        serverUrl: 'https://mcp.linear.app/mcp',
        allowedTools: ['issues.list'],
        headers: {
          Authorization: `Bearer ${process.env.LINEAR_API_KEY}`,
        },
        requireApproval: 'always',
      },
    ],
  },
  { headers: { 'X-On-Behalf-Of': '<end-user-id>' } },
);

// Paso 2: Haz polling hasta que aparezca una solicitud de aprobación
let approvalRequest: components.MCPApprovalRequest | undefined;

while (
  pendingResponse.status === 'queued' ||
  pendingResponse.status === 'in_progress'
) {
  approvalRequest = pendingResponse.output.find(
    (item): item is components.MCPApprovalRequest =>
      item.type === 'mcp_approval_request',
  );

  if (approvalRequest) break;

  await new Promise(resolve => setTimeout(resolve, 1000));

  pendingResponse = await mka1.llm.responses.get(
    { responseId: pendingResponse.id },
    { headers: { 'X-On-Behalf-Of': '<end-user-id>' } },
  );
}

if (!approvalRequest) {
  throw new Error(`No se encontró ninguna solicitud de aprobación. La respuesta terminó con ${pendingResponse.status}.`);
}

// Paso 3: Muestra al usuario lo que el modelo quiere hacer
console.log('Servidor:', approvalRequest.serverLabel);
console.log('Herramienta:', approvalRequest.name);
console.log('Argumentos:', approvalRequest.arguments);

// Paso 4: Envía la aprobación (o rechazo) para continuar
const approve = true; // Reemplaza con la decisión de tu UI

const continuedResponse = await mka1.llm.responses.create(
  {
    model: 'gpt-5',
    previousResponseId: pendingResponse.id,
    input: [
      {
        type: 'mcp_approval_response',
        approvalRequestId: approvalRequest.id,
        approve,
      },
    ],
    store: true,
    stream: false,
  },
  { headers: { 'X-On-Behalf-Of': '<end-user-id>' } },
);

const assistantText = continuedResponse.output
  .filter(
    (item): item is components.OutputMessage =>
      item.type === 'message' && item.role === 'assistant',
  )
  .flatMap(item =>
    item.content.flatMap(content =>
      content.type === 'output_text' ? [content.text] : [],
    ),
  )
  .join('\n\n')
  .trim();

console.log(assistantText);
Si el usuario final rechaza la llamada a la herramienta, envía approve: false. También puedes incluir un campo reason en el elemento mcp_approval_response. Para interfaces de aprobación, muestra:
  • server_label — qué servidor MCP se está utilizando
  • name — qué herramienta quiere llamar el modelo
  • arguments — qué argumentos planea enviar

​
Referencia de definición de herramienta MCP

ParámetroTipoPredeterminadoDescripción
type"mcp"—Requerido. Identifica esto como una herramienta MCP.
server_labelstring—Requerido. Nombre visible para el servidor MCP.
server_urlstring—URL del endpoint del servidor MCP.
server_descriptionstring—Descripción opcional del propósito del servidor.
allowed_toolsstring[]—Limita qué herramientas puede llamar el modelo.
headersobject—Cabeceras para pasar al servidor MCP (por ejemplo, tokens de autenticación).
require_approval"always" | "never""always"Si se debe pausar para aprobación del usuario final antes de llamar.
connector_idstring—Usa un conector preconfigurado en vez de una URL de servidor personalizada.
Las credenciales pasadas en headers se ocultan automáticamente en las respuestas almacenadas y en los eventos de streaming.

​
Próximos pasos