Usar ferramentas MCP

Use ferramentas MCP quando quiser que a API MKA1 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 seu aplicativo pause e peça ao usuário final antes de executar a ferramenta. Use X-On-Behalf-Of para o usuário final da API MKA1. Passe as credenciais do servidor MCP upstream na definição da ferramenta MCP.

Chamar uma ferramenta MCP diretamente

Defina require_approval como 'never' quando a ferramenta puder ser executada imediatamente.

mka1 llm responses create --body '{
  "model": "meetkai:functionary-pt",
  "instructions": "Você é um assistente de gerenciamento de projetos com acesso ao Linear via MCP. Use as ferramentas do Linear quando o usuário perguntar sobre tarefas, bugs ou projetos. Mantenha a resposta final concisa.",
  "input": "Liste meu problema mais recente do Linear atribuído a mim.",
  "store": true,
  "stream": false,
  "tools": [
    {
      "type": "mcp",
      "server_label": "Linear MCP",
      "server_description": "Acesse problemas do Linear por meio do 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({
  xOnBehalfOf: '<end-user-id>', // optional — atribua a solicitação a um de seus usuários finais
  responsesCreateRequest: {
    model: 'meetkai:functionary-pt',
    instructions:
      'Você é um assistente de gerenciamento de projetos com acesso ao Linear via MCP. Use as ferramentas do Linear quando o usuário perguntar sobre tarefas, bugs ou projetos. Mantenha a resposta final concisa.',
    input: 'Liste meu problema mais recente do Linear atribuído a mim.',
    store: true,
    stream: false,
    tools: [
      {
        type: 'mcp',
        serverLabel: 'Linear MCP',
        serverDescription: 'Acesse problemas do Linear por meio do MCP.',
        serverUrl: 'https://mcp.linear.app/mcp',
        allowedTools: ['issues.list'],
        headers: {
          Authorization: `Bearer ${process.env.LINEAR_API_KEY}`,
        },
        requireApproval: 'never',
      },
    ],
  },
}) as components.ResponseObject;

// MCP tool calls appear as mcp_call items in the output
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-pt',
  instructions:
    'Você é um assistente de gerenciamento de projetos com acesso ao Linear via MCP. Use as ferramentas do Linear quando o usuário perguntar sobre tarefas, bugs ou projetos. Mantenha a resposta final concisa.',
  input: 'Liste meu problema mais recente do Linear atribuído a mim.',
  store: true,
  stream: false,
  tools: [
    {
      type: 'mcp',
      server_label: 'Linear MCP',
      server_description: 'Acesse problemas do Linear por meio do MCP.',
      server_url: 'https://mcp.linear.app/mcp',
      allowed_tools: ['issues.list'],
      headers: {
        Authorization: `Bearer ${process.env.LINEAR_API_KEY}`,
      },
      require_approval: 'never',
    },
  ],
});

// MCP tool calls appear as mcp_call items in the output
const mcpCall = response.output.find((item) => item.type === 'mcp_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-pt",
        Input = ResponsesCreateRequestInput.CreateStr(
            "Liste meu problema mais recente do Linear atribuído a mim."
        ),
    }
);

// MCP tools require a running MCP server endpoint.
// The SDK constructs the same request shape as the TypeScript and curl examples.
Console.WriteLine(response);

from meetkai_mka1 import SDK
import os

sdk = SDK(bearer_auth="Bearer YOUR_API_KEY")

response = sdk.llm.responses.create(
    model="meetkai:functionary-pt",
    instructions="Você é um assistente de gerenciamento de projetos com acesso ao Linear via MCP. Use as ferramentas do Linear quando o usuário perguntar sobre tarefas, bugs ou projetos. Mantenha a resposta final concisa.",
    input="Liste meu problema mais recente do Linear atribuído a mim.",
    store=True,
    stream=False,
    tools=[
        {
            "type": "mcp",
            "server_label": "Linear MCP",
            "server_description": "Acesse problemas do Linear por meio do 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-pt",
    "instructions": "Você é um assistente de gerenciamento de projetos com acesso ao Linear via MCP. Use as ferramentas do Linear quando o usuário perguntar sobre tarefas, bugs ou projetos. Mantenha a resposta final concisa.",
    "input": "Liste meu problema mais recente do Linear atribuído a mim.",
    "store": true,
    "stream": false,
    "tools": [
      {
        "type": "mcp",
        "server_label": "Linear MCP",
        "server_description": "Acesse problemas do Linear por meio do MCP.",
        "server_url": "https://mcp.linear.app/mcp",
        "allowed_tools": ["issues.list"],
        "headers": {
          "Authorization": "Bearer <linear-api-key>"
        },
        "require_approval": "never"
      }
    ]
  }'

Este é o fluxo mais simples. O modelo chama a ferramenta MCP permitida e retorna a mensagem final do assistente em uma solicitação. A matriz output da resposta contém:

mcp_call — a chamada do modelo para a ferramenta descoberta pelo MCP
mcp_call_output — os dados retornados pelo servidor MCP
message — a resposta de texto do modelo que resume os resultados

Exigir aprovação do usuário final

Defina require_approval como 'always' quando seu aplicativo precisar parar e aguardar uma decisão de aprovação. Nesse fluxo, crie a resposta no modo em segundo plano, consulte-a e procure um item mcp_approval_request em output.

# Etapa 1: Crie uma resposta em segundo plano com aprovação obrigatória
mka1 llm responses create --body '{
  "model": "meetkai:functionary-pt",
  "instructions": "Você é um assistente de gerenciamento de projetos com acesso ao Linear via MCP.",
  "input": "Liste meu problema mais recente do Linear atribuído a mim.",
  "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"
    }
  ]
}'

# Etapa 2: Consulte a resposta por ID até que um mcp_approval_request apareça
mka1 llm responses get --response-id <response-id>

# Etapa 3: Envie a aprovação para continuar
mka1 llm responses create --body '{
  "model": "meetkai:functionary-pt",
  "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}`,
});

// Step 1: Create a background response with approval required
let pendingResponse = await mka1.llm.responses.create({
  xOnBehalfOf: '<end-user-id>',
  responsesCreateRequest: {
    model: 'meetkai:functionary-pt',
    instructions:
      'Você é um assistente de gerenciamento de projetos com acesso ao Linear via MCP. Use as ferramentas do Linear quando o usuário perguntar sobre tarefas, bugs ou projetos. Mantenha a resposta final concisa.',
    input: 'Liste meu problema mais recente do Linear atribuído a mim.',
    background: true,
    store: true,
    stream: false,
    tools: [
      {
        type: 'mcp',
        serverLabel: 'Linear MCP',
        serverDescription: 'Acesse problemas do Linear por meio do MCP.',
        serverUrl: 'https://mcp.linear.app/mcp',
        allowedTools: ['issues.list'],
        headers: {
          Authorization: `Bearer ${process.env.LINEAR_API_KEY}`,
        },
        requireApproval: 'always',
      },
    ],
  },
}) as components.ResponseObject;

// Step 2: Poll until an approval request appears
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,
    xOnBehalfOf: '<end-user-id>',
  }) as components.ResponseObject;
}

if (!approvalRequest) {
  throw new Error(`No approval request found. Response ended with ${pendingResponse.status}.`);
}

// Step 3: Show the user what the model wants to do
console.log('Server:', approvalRequest.serverLabel);
console.log('Tool:', approvalRequest.name);
console.log('Arguments:', approvalRequest.arguments);

// Step 4: Send the approval (or denial) to continue
const approve = true; // Replace with your UI decision

const continuedResponse = await mka1.llm.responses.create({
  xOnBehalfOf: '<end-user-id>',
  responsesCreateRequest: {
    model: 'meetkai:functionary-pt',
    previousResponseId: pendingResponse.id,
    input: [
      {
        type: 'mcp_approval_response',
        approvalRequestId: approvalRequest.id,
        approve,
      },
    ],
    store: true,
    stream: false,
  },
}) as components.ResponseObject;

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>' },
});

// Step 1: Create a background response with approval required
let pendingResponse = await openai.responses.create({
  model: 'meetkai:functionary-pt',
  instructions:
    'Você é um assistente de gerenciamento de projetos com acesso ao Linear via MCP. Use as ferramentas do Linear quando o usuário perguntar sobre tarefas, bugs ou projetos. Mantenha a resposta final concisa.',
  input: 'Liste meu problema mais recente do Linear atribuído a mim.',
  background: true,
  store: true,
  stream: false,
  tools: [
    {
      type: 'mcp',
      server_label: 'Linear MCP',
      server_description: 'Acesse problemas do Linear por meio do MCP.',
      server_url: 'https://mcp.linear.app/mcp',
      allowed_tools: ['issues.list'],
      headers: {
        Authorization: `Bearer ${process.env.LINEAR_API_KEY}`,
      },
      require_approval: 'always',
    },
  ],
});

// Step 2: Poll until an approval request appears
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 approval request found. Response ended with ${pendingResponse.status}.`);
}

// Step 3: Show the user what the model wants to do
console.log('Server:', approvalRequest.server_label);
console.log('Tool:', approvalRequest.name);
console.log('Arguments:', approvalRequest.arguments);

// Step 4: Send the approval (or denial) to continue
const approve = true; // Replace with your UI decision

const continuedResponse = await openai.responses.create({
  model: 'meetkai:functionary-pt',
  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"
);

// MCP approval workflow requires a running MCP server.
// The SDK can construct background requests with MCP tools.
var request = new ResponsesCreateRequest()
{
    Model = "meetkai:functionary-pt",
    Input = ResponsesCreateRequestInput.CreateStr("Execute a ferramenta aprovada."),
    Background = true,
};

Console.WriteLine(request);

import os
import time

# Step 1: Create a background response with approval required
pending = sdk.llm.responses.create(
    model="meetkai:functionary-pt",
    instructions="Você é um assistente de gerenciamento de projetos com acesso ao Linear via MCP. Use as ferramentas do Linear quando o usuário perguntar sobre tarefas, bugs ou projetos. Mantenha a resposta final concisa.",
    input="Liste meu problema mais recente do Linear atribuído a mim.",
    background=True,
    store=True,
    stream=False,
    tools=[
        {
            "type": "mcp",
            "server_label": "Linear MCP",
            "server_description": "Acesse problemas do Linear por meio do MCP.",
            "server_url": "https://mcp.linear.app/mcp",
            "allowed_tools": ["issues.list"],
            "headers": {
                "Authorization": f"Bearer {os.environ['LINEAR_API_KEY']}",
            },
            "require_approval": "always",
        },
    ],
)

# Step 2: Poll until an approval request appears
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)

# Step 3: Show the user what the model wants to do
print("Servidor:", approval_request.server_label)
print("Ferramenta:", approval_request.name)
print("Argumentos:", approval_request.arguments)

# Step 4: Send the approval (or denial) to continue
continued = sdk.llm.responses.create(
    model="meetkai:functionary-pt",
    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)

# Etapa 1: Crie uma resposta em segundo plano com aprovação obrigatória
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-pt",
    "instructions": "Você é um assistente de gerenciamento de projetos com acesso ao Linear via MCP.",
    "input": "Liste meu problema mais recente do Linear atribuído a mim.",
    "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')

# Etapa 2: Consulte até que a solicitação de aprovação apareça
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

# Etapa 3: Envie a aprovação 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-pt\",
    \"previous_response_id\": \"$RESPONSE_ID\",
    \"input\": [
      {
        \"type\": \"mcp_approval_response\",
        \"approval_request_id\": \"$APPROVAL_ID\",
        \"approve\": true
      }
    ],
    \"store\": true,
    \"stream\": false
  }"

Se o usuário final negar a chamada da ferramenta, envie approve: false. Você também pode incluir um campo reason no item mcp_approval_response. Para interfaces de aprovação, mostre:

server_label — qual servidor MCP está sendo usado
name — qual ferramenta o modelo deseja chamar
arguments — quais argumentos ele planeja enviar

Referência da definição da ferramenta MCP

Parâmetro	Tipo	Padrão	Descrição
`type`	`"mcp"`	—	Obrigatório. Identifica isto como uma ferramenta MCP.
`server_label`	string	—	Obrigatório. Nome de exibição do servidor MCP.
`server_url`	string	—	URL do endpoint do servidor MCP.
`server_description`	string	—	Descrição opcional da finalidade do servidor.
`allowed_tools`	string[]	—	Limite quais ferramentas o modelo pode chamar.
`headers`	object	—	Cabeçalhos a serem passados ao servidor MCP (por exemplo, tokens de autenticação).
`require_approval`	`"always"` \| `"never"`	`"always"`	Se deve pausar para aprovação do usuário final antes de chamar.
`connector_id`	string	—	Use um conector pré-configurado em vez de uma URL de servidor personalizada.

As credenciais passadas em headers são automaticamente mascaradas em respostas armazenadas e eventos de streaming.

Próximas etapas

Consulte gerar uma resposta para o fluxo básico de Responses
Consulte respostas em segundo plano para padrões de consulta e streaming
Consulte conversas se quiser manter o mesmo usuário final em uma conversa mais longa
Revise a referência da API para o esquema completo de Responses

Primeiros passos

Respostas

Recursos

Computação

CLI

Receitas

Benchmarks

Infraestrutura

Usar ferramentas MCP

Chamar uma ferramenta MCP diretamente

Exigir aprovação do usuário final

Referência da definição da ferramenta MCP

Próximas etapas

​Chamar uma ferramenta MCP diretamente

​Exigir aprovação do usuário final

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

​Próximas etapas

Chamar uma ferramenta MCP diretamente

Exigir aprovação do usuário final

Referência da definição da ferramenta MCP

Próximas etapas