Pular para o conteúdo principal

Documentation Index

Fetch the complete documentation index at: https://docs.mka1.com/llms.txt

Use this file to discover all available pages before exploring further.

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 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 através 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>'
Esse é 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 pelo MCP
  2. function_call_output — os dados retornados pelo servidor MCP
  3. message — a resposta em texto do modelo resumindo os resultados

​
Exigir aprovação do usuário final

Defina require_approval como 'always' quando seu aplicativo deve parar e aguardar uma decisão de aprovação. Neste fluxo, crie a resposta em modo background, faça polling e procure um item mcp_approval_request em output. 
# Passo 1: Crie uma resposta em background exigindo aprovação
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"
    }
  ]
}'

# Passo 2: Faça polling da resposta pelo id até aparecer um mcp_approval_request
mka1 llm responses get --response-id <response-id>

# Passo 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
}'
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 pretende enviar

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

ParâmetroTipoPadrãoDescrição
type"mcp"—Obrigatório. Identifica como uma ferramenta MCP.
server_labelstring—Obrigatório. Nome de exibição para o servidor MCP.
server_urlstring—URL do endpoint do servidor MCP.
server_descriptionstring—Descrição opcional do propósito do servidor.
allowed_toolsstring[]—Limita quais ferramentas o modelo pode chamar.
headersobject—Headers a serem enviados ao servidor MCP (ex: tokens de autenticação).
require_approval"always" | "never""always"Se deve pausar para aprovação do usuário final antes de chamar.
connector_idstring—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óximos passos