Saltar para o conteúdo principal
Use ferramentas MCP quando quiser que a MKA1 API chame ferramentas de um servidor MCP externo durante uma resposta. Defina o servidor MCP em tools. Limite quais ferramentas o modelo pode chamar com allowed_tools. Use require_approval quando quiser que sua aplicação pause e peça aprovação ao end user antes de executar a ferramenta. Use X-On-Behalf-Of para o end user da MKA1 API. Passe as credenciais do servidor MCP upstream na definição da ferramenta MCP.

​
Chame uma ferramenta MCP diretamente

Defina require_approval como 'never' quando a ferramenta puder ser executada imediatamente. 
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: 'auto',
    instructions:
      'You are a project management assistant with access to Linear via MCP. Use Linear tools when the user asks about tasks, bugs, or projects. Keep the final answer terse.',
    input: 'List my most recent Linear issue assigned to me.',
    store: true,
    stream: false,
    tools: [
      {
        type: 'mcp',
        serverLabel: 'Linear MCP',
        serverDescription: 'Access Linear issues through 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>' } },
);

// Chamadas de ferramenta MCP aparecem como itens function_call na saída
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 é o fluxo mais simples. O modelo chama a ferramenta MCP permitida e retorna a mensagem final do assistente em uma única requisição. O array output da resposta contém:
  1. function_call — a chamada do modelo para a ferramenta descoberta via MCP
  2. function_call_output — os dados retornados pelo servidor MCP
  3. message — a resposta em texto do modelo resumindo os resultados

​
Exija aprovação do end user

Defina require_approval como 'always' quando sua aplicação precisar parar e aguardar uma decisão de aprovação. Nesse fluxo, crie a resposta em modo background, faça polling e procure um item mcp_approval_request em output. 
import { SDK } from '@meetkai/mka1';
import type * as components from '@meetkai/mka1/models/components';

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

// Passo 1: Crie uma resposta em background com aprovação obrigatória
let pendingResponse = await mka1.llm.responses.create(
  {
    model: 'auto',
    instructions:
      'You are a project management assistant with access to Linear via MCP. Use Linear tools when the user asks about tasks, bugs, or projects. Keep the final answer terse.',
    input: 'List my most recent Linear issue assigned to me.',
    background: true,
    store: true,
    stream: false,
    tools: [
      {
        type: 'mcp',
        serverLabel: 'Linear MCP',
        serverDescription: 'Access Linear issues through 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>' } },
);

// Passo 2: Faça polling até que uma solicitação de aprovação apareça
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 approval request found. Response ended with ${pendingResponse.status}.`);
}

// Passo 3: Mostre ao usuário o que o modelo quer fazer
console.log('Server:', approvalRequest.serverLabel);
console.log('Tool:', approvalRequest.name);
console.log('Arguments:', approvalRequest.arguments);

// Passo 4: Envie a aprovação, ou a recusa, para continuar
const approve = true; // Substitua pela decisão da sua UI

const continuedResponse = await mka1.llm.responses.create(
  {
    model: 'auto',
    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);
Se o end user negar a chamada da ferramenta, envie approve: false. Você também pode incluir um campo reason no item mcp_approval_response. Em interfaces de aprovação, mostre:
  • server_label — qual servidor MCP está sendo usado
  • name — qual ferramenta o modelo quer chamar
  • arguments — quais argumentos ele pretende enviar

​
Referência da definição de ferramenta MCP

ParâmetroTipoPadrãoDescrição
type"mcp"—Obrigatório. Identifica isto como uma ferramenta MCP.
server_labelstring—Obrigatório. Nome de exibição do servidor MCP.
server_urlstring—URL do endpoint do servidor MCP.
server_descriptionstring—Descrição opcional da finalidade do servidor.
allowed_toolsstring[]—Limita quais ferramentas o modelo pode chamar.
headersobject—Cabeçalhos enviados ao servidor MCP, como tokens de autenticação.
require_approval"always" | "never""always"Define se a execução deve pausar para aprovação do end user antes da chamada.
connector_idstring—Usa um connector pré-configurado em vez de uma URL de servidor personalizada.
As credenciais passadas em headers são mascaradas automaticamente em respostas armazenadas e eventos de streaming.

​
Próximos passos