Usar herramientas MCP

Utiliza herramientas MCP cuando quieras que la API de MKA1 llame 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 detenga y pida aprobación al usuario final antes de ejecutar la herramienta. Utiliza X-On-Behalf-Of para identificar al usuario final de la API de MKA1. Pasa las credenciales del servidor MCP upstream en la definición de la herramienta MCP.

Llamar directamente a una herramienta MCP

Establece require_approval en 'never' cuando la herramienta pueda ejecutarse de inmediato.

mka1 llm responses create --body '{
  "model": "meetkai:functionary-es-mini",
  "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",
      "server_label": "Linear MCP",
      "server_description": "Accede a incidencias de Linear a través de MCP.",
      "server_url": "https://mcp.linear.app/mcp",
      "allowed_tools": ["issues.list"],
      "headers": {
        "Authorization": "Bearer <linear-api-key>"
      },
      "require_approval": "never"
    }
  ]
}' \
  -H 'X-On-Behalf-Of: <end-user-id>'

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: 'meetkai:functionary-es-mini',
    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);

import OpenAI from 'openai';

const openai = new OpenAI({
  apiKey: '<mka1-api-key>',
  baseURL: 'https://apigw.mka1.com/api/v1/llm/',
  defaultHeaders: { 'X-On-Behalf-Of': '<end-user-id>' },
});

const response = await openai.responses.create({
  model: 'meetkai:functionary-es-mini',
  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',
      server_label: 'Linear MCP',
      server_description: 'Accede a incidencias de Linear a través de MCP.',
      server_url: 'https://mcp.linear.app/mcp',
      allowed_tools: ['issues.list'],
      headers: {
        Authorization: `Bearer ${process.env.LINEAR_API_KEY}`,
      },
      require_approval: 'never',
    },
  ],
});

// Las llamadas a herramientas MCP aparecen como elementos function_call en la salida
const functionCall = response.output.find((item) => item.type === 'function_call');
const message = response.output.find((item) => item.type === 'message');
console.log(response.output_text);

using MeetKai.MKA1;
using MeetKai.MKA1.Types.Components;

var sdk = new SDK(
    bearerAuth: "Bearer <mka1-api-key>",
    serverUrl: "https://apigw.mka1.com"
);

var response = await sdk.Llm.Responses.CreateAsync(
    new ResponsesCreateRequest()
    {
        Model = "meetkai:functionary-es-mini",
        Input = ResponsesCreateRequestInput.CreateStr(
            "Lista mi incidencia de Linear más reciente asignada a mí."
        ),
    }
);

// Las herramientas MCP requieren un endpoint de servidor MCP en funcionamiento.
// El SDK construye la misma forma de solicitud que los ejemplos de TypeScript y curl.
Console.WriteLine(response);

from mka1 import SDK
import os

sdk = SDK(bearer_auth="Bearer YOUR_API_KEY")

response = sdk.llm.responses.create(
    model="meetkai:functionary-es-mini",
    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",
            "server_label": "Linear MCP",
            "server_description": "Accede a incidencias de Linear a través de MCP.",
            "server_url": "https://mcp.linear.app/mcp",
            "allowed_tools": ["issues.list"],
            "headers": {
                "Authorization": f"Bearer {os.environ['LINEAR_API_KEY']}",
            },
            "require_approval": "never",
        },
    ],
)

print(response.output_text)

curl https://apigw.mka1.com/api/v1/llm/responses \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --header 'X-On-Behalf-Of: <end-user-id>' \
  --data '{
    "model": "meetkai:functionary-es-mini",
    "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",
        "server_label": "Linear MCP",
        "server_description": "Accede a incidencias de Linear a través de MCP.",
        "server_url": "https://mcp.linear.app/mcp",
        "allowed_tools": ["issues.list"],
        "headers": {
          "Authorization": "Bearer <linear-api-key>"
        },
        "require_approval": "never"
      }
    ]
  }'

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 de respuesta output contiene:

function_call — la llamada del modelo a la herramienta descubierta por MCP
function_call_output — los datos devueltos por el servidor MCP
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.

# Paso 1: Crear una respuesta en segundo plano con aprobación requerida
mka1 llm responses create --body '{
  "model": "meetkai:functionary-es-mini",
  "instructions": "Eres un asistente de gestión de proyectos con acceso a Linear vía MCP.",
  "input": "Lista mi incidencia de Linear más reciente asignada a mí.",
  "background": true,
  "store": true,
  "stream": false,
  "tools": [
    {
      "type": "mcp",
      "server_label": "Linear MCP",
      "server_url": "https://mcp.linear.app/mcp",
      "allowed_tools": ["issues.list"],
      "headers": { "Authorization": "Bearer <linear-api-key>" },
      "require_approval": "always"
    }
  ]
}'

# Paso 2: Haz polling de la respuesta por id hasta que aparezca un mcp_approval_request
mka1 llm responses get --response-id <response-id>

# Paso 3: Envía la aprobación para continuar
mka1 llm responses create --body '{
  "model": "meetkai:functionary-es-mini",
  "previous_response_id": "<response-id>",
  "input": [
    {
      "type": "mcp_approval_response",
      "approval_request_id": "<approval-request-id>",
      "approve": true
    }
  ],
  "store": true,
  "stream": false
}'

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: Crear una respuesta en segundo plano con aprobación requerida
let pendingResponse = await mka1.llm.responses.create(
  {
    model: 'meetkai:functionary-es-mini',
    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ó 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 denegación) para continuar
const approve = true; // Reemplaza con la decisión de tu UI

const continuedResponse = await mka1.llm.responses.create(
  {
    model: 'meetkai:functionary-es-mini',
    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);

import OpenAI from 'openai';

const openai = new OpenAI({
  apiKey: '<mka1-api-key>',
  baseURL: 'https://apigw.mka1.com/api/v1/llm/',
  defaultHeaders: { 'X-On-Behalf-Of': '<end-user-id>' },
});

// Paso 1: Crear una respuesta en segundo plano con aprobación requerida
let pendingResponse = await openai.responses.create({
  model: 'meetkai:functionary-es-mini',
  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',
      server_label: 'Linear MCP',
      server_description: 'Accede a incidencias de Linear a través de MCP.',
      server_url: 'https://mcp.linear.app/mcp',
      allowed_tools: ['issues.list'],
      headers: {
        Authorization: `Bearer ${process.env.LINEAR_API_KEY}`,
      },
      require_approval: 'always',
    },
  ],
});

// Paso 2: Haz polling hasta que aparezca una solicitud de aprobación
let approvalRequest;

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

  if (approvalRequest) break;

  await new Promise(resolve => setTimeout(resolve, 1000));
  pendingResponse = await openai.responses.retrieve(pendingResponse.id);
}

if (!approvalRequest) {
  throw new Error(`No se encontró 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.server_label);
console.log('Herramienta:', approvalRequest.name);
console.log('Argumentos:', approvalRequest.arguments);

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

const continuedResponse = await openai.responses.create({
  model: 'meetkai:functionary-es-mini',
  previous_response_id: pendingResponse.id,
  input: [
    {
      type: 'mcp_approval_response',
      approval_request_id: approvalRequest.id,
      approve,
    },
  ],
  store: true,
  stream: false,
});

console.log(continuedResponse.output_text);

using MeetKai.MKA1;
using MeetKai.MKA1.Types.Components;

var sdk = new SDK(
    bearerAuth: "Bearer <mka1-api-key>",
    serverUrl: "https://apigw.mka1.com"
);

// El flujo de aprobación MCP requiere un servidor MCP en funcionamiento.
// El SDK puede construir solicitudes en segundo plano con herramientas MCP.
var request = new ResponsesCreateRequest()
{
    Model = "meetkai:functionary-es-mini",
    Input = ResponsesCreateRequestInput.CreateStr("Ejecuta la herramienta aprobada."),
    Background = true,
};

Console.WriteLine(request);

import os
import time

# Paso 1: Crear una respuesta en segundo plano con aprobación requerida
pending = sdk.llm.responses.create(
    model="meetkai:functionary-es-mini",
    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",
            "server_label": "Linear MCP",
            "server_description": "Accede a incidencias de Linear a través de MCP.",
            "server_url": "https://mcp.linear.app/mcp",
            "allowed_tools": ["issues.list"],
            "headers": {
                "Authorization": f"Bearer {os.environ['LINEAR_API_KEY']}",
            },
            "require_approval": "always",
        },
    ],
)

# Paso 2: Haz polling hasta que aparezca una solicitud de aprobación
approval_request = None
while pending.status in ("queued", "in_progress"):
    for item in pending.output:
        if item.type == "mcp_approval_request":
            approval_request = item
            break
    if approval_request:
        break
    time.sleep(1)
    pending = sdk.llm.responses.get(response_id=pending.id)

# Paso 3: Muestra al usuario lo que el modelo quiere hacer
print("Servidor:", approval_request.server_label)
print("Herramienta:", approval_request.name)
print("Argumentos:", approval_request.arguments)

# Paso 4: Envía la aprobación (o denegación) para continuar
continued = sdk.llm.responses.create(
    model="meetkai:functionary-es-mini",
    previous_response_id=pending.id,
    input=[
        {
            "type": "mcp_approval_response",
            "approval_request_id": approval_request.id,
            "approve": True,
        },
    ],
    store=True,
    stream=False,
)

print(continued.output_text)

# Paso 1: Crear respuesta en segundo plano con aprobación requerida
RESPONSE=$(curl -s https://apigw.mka1.com/api/v1/llm/responses \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --header 'X-On-Behalf-Of: <end-user-id>' \
  --data '{
    "model": "meetkai:functionary-es-mini",
    "instructions": "Eres un asistente de gestión de proyectos con acceso a Linear vía MCP.",
    "input": "Lista mi incidencia de Linear más reciente asignada a mí.",
    "background": true,
    "store": true,
    "stream": false,
    "tools": [
      {
        "type": "mcp",
        "server_label": "Linear MCP",
        "server_url": "https://mcp.linear.app/mcp",
        "allowed_tools": ["issues.list"],
        "headers": { "Authorization": "Bearer <linear-api-key>" },
        "require_approval": "always"
      }
    ]
  }')

RESPONSE_ID=$(echo "$RESPONSE" | jq -r '.id')

# Paso 2: Haz polling hasta que aparezca la solicitud de aprobación
while true; do
  RESPONSE=$(curl -s "https://apigw.mka1.com/api/v1/llm/responses/$RESPONSE_ID" \
    --header 'Authorization: Bearer <mka1-api-key>' \
    --header 'X-On-Behalf-Of: <end-user-id>')

  APPROVAL_ID=$(echo "$RESPONSE" | jq -r '.output[] | select(.type == "mcp_approval_request") | .id')
  if [ -n "$APPROVAL_ID" ] && [ "$APPROVAL_ID" != "null" ]; then break; fi
  sleep 1
done

# Paso 3: Envía la aprobación para continuar
curl https://apigw.mka1.com/api/v1/llm/responses \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --header 'X-On-Behalf-Of: <end-user-id>' \
  --data "{
    \"model\": \"meetkai:functionary-es-mini\",
    \"previous_response_id\": \"$RESPONSE_ID\",
    \"input\": [
      {
        \"type\": \"mcp_approval_response\",
        \"approval_request_id\": \"$APPROVAL_ID\",
        \"approve\": true
      }
    ],
    \"store\": true,
    \"stream\": false
  }"

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á usando
name — qué herramienta quiere llamar el modelo
arguments — qué argumentos planea enviar

Referencia de definición de herramienta MCP

Parámetro	Tipo	Predeterminado	Descripción
`type`	`"mcp"`	—	Requerido. Identifica esto como una herramienta MCP.
`server_label`	string	—	Requerido. Nombre para mostrar del servidor MCP.
`server_url`	string	—	URL del endpoint del servidor MCP.
`server_description`	string	—	Descripción opcional del propósito del servidor.
`allowed_tools`	string[]	—	Limita qué herramientas puede llamar el modelo.
`headers`	object	—	Cabeceras a 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_id`	string	—	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

Consulta generar una respuesta para el flujo básico de Respuestas
Consulta respuestas en segundo plano para patrones de polling y streaming
Consulta conversaciones si quieres mantener el mismo usuario final en un hilo más largo
Revisa la referencia de la API para el esquema completo de Respuestas

​Llamar directamente a una herramienta MCP

​Requerir aprobación del usuario final

​Referencia de definición de herramienta MCP

​Próximos pasos

Llamar directamente a una herramienta MCP

Requerir aprobación del usuario final

Referencia de definición de herramienta MCP

Próximos pasos