Criar um agente com ferramentas MCP

Use a API de Agentes com o MCP Vault quando quiser agentes reutilizáveis que possam chamar ferramentas de um servidor MCP externo. O cofre mantém a configuração e as credenciais do servidor MCP fora da definição do agente, para que seu aplicativo possa alternar credenciais sem editar todos os agentes. Referência da API:

1. Registre o servidor MCP

Crie o servidor MCP uma vez para a integração que deseja que o agente use. Use allowed_tools para expor somente as ferramentas de que o agente precisa. Use require_approval quando seu produto precisar pedir autorização ao usuário final antes de executar a ferramenta MCP.

mka1 llm mcp-vault create-server --body '{
  "name": "Linear",
  "server_label": "linear",
  "server_url": "https://mcp.linear.app/mcp",
  "server_description": "Acesse issues, projetos e comentários do Linear.",
  "allowed_tools": ["issues.list", "issues.create", "comments.create"],
  "require_approval": "always",
  "metadata": {
    "integration": "linear"
  }
}' \
  -H 'X-On-Behalf-Of: <end-user-id>'

import { SDK } from "@meetkai/mka1";

const sdk = new SDK({
  bearerAuth: "Bearer <mka1-api-key>",
});

const server = await sdk.llm.mcpVault.createServer({
  xOnBehalfOf: "<end-user-id>", // opcional — atribua a solicitação a um de seus usuários finais
  createMcpServerRequest: {
    name: "Linear",
    serverLabel: "linear",
    serverUrl: "https://mcp.linear.app/mcp",
    serverDescription: "Acesse issues, projetos e comentários do Linear.",
    allowedTools: ["issues.list", "issues.create", "comments.create"],
    requireApproval: "always",
    metadata: {
      integration: "linear",
    },
  },
});

console.log(server.id);

const serverResponse = await fetch("https://apigw.mka1.com/api/v1/llm/mcp/servers", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer <mka1-api-key>",
    "X-On-Behalf-Of": "<end-user-id>",
  },
  body: JSON.stringify({
    name: "Linear",
    server_label: "linear",
    server_url: "https://mcp.linear.app/mcp",
    server_description: "Acesse issues, projetos e comentários do Linear.",
    allowed_tools: ["issues.list", "issues.create", "comments.create"],
    require_approval: "always",
    metadata: {
      integration: "linear",
    },
  }),
});

const server = await serverResponse.json();
console.log(server.id);

curl https://apigw.mka1.com/api/v1/llm/mcp/servers \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --header 'X-On-Behalf-Of: <end-user-id>' \
  --data '{
    "name": "Linear",
    "server_label": "linear",
    "server_url": "https://mcp.linear.app/mcp",
    "server_description": "Acesse issues, projetos e comentários do Linear.",
    "allowed_tools": ["issues.list", "issues.create", "comments.create"],
    "require_approval": "always",
    "metadata": {
      "integration": "linear"
    }
  }'

A resposta inclui um ID estável de servidor MCP, como mcp_srv_.... Use esse ID nas definições de ferramentas do agente. Consulte a referência da API Criar servidor MCP para ver o esquema completo.

2. Armazene a credencial MCP

Crie uma credencial no servidor MCP. A credencial pode usar um token bearer, um valor de cabeçalho de autorização, cabeçalhos personalizados ou nenhuma autenticação. Armazene credenciais de usuários finais com X-On-Behalf-Of para que cada usuário final tenha acesso isolado.

mka1 llm mcp-vault create-credential \
  --server-id mcp_srv_123 \
  --body '{
    "name": "Token pessoal do Linear",
    "auth_type": "bearer",
    "bearer_token": "<linear-api-key>"
  }' \
  -H 'X-On-Behalf-Of: <end-user-id>'

const credential = await sdk.llm.mcpVault.createCredential({
  serverId: "mcp_srv_123",
  xOnBehalfOf: "<end-user-id>",
  createMcpCredentialRequest: {
    name: "Token pessoal do Linear",
    authType: "bearer",
    bearerToken: "<linear-api-key>",
  },
});

console.log(credential.id);

const credentialResponse = await fetch(
  "https://apigw.mka1.com/api/v1/llm/mcp/servers/mcp_srv_123/credentials",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: "Bearer <mka1-api-key>",
      "X-On-Behalf-Of": "<end-user-id>",
    },
    body: JSON.stringify({
      name: "Token pessoal do Linear",
      auth_type: "bearer",
      bearer_token: "<linear-api-key>",
    }),
  },
);

const credential = await credentialResponse.json();
console.log(credential.id);

curl https://apigw.mka1.com/api/v1/llm/mcp/servers/mcp_srv_123/credentials \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --header 'X-On-Behalf-Of: <end-user-id>' \
  --data '{
    "name": "Token pessoal do Linear",
    "auth_type": "bearer",
    "bearer_token": "<linear-api-key>"
  }'

A resposta inclui um ID de credencial, como mcp_cred_.... Os valores secretos são armazenados pelo cofre e não são retornados em respostas de listagem posteriores. Use Listar credenciais MCP quando seu aplicativo precisar mostrar metadados de credenciais salvas.

3. Teste o servidor

Teste o servidor antes de vinculá-lo a um agente. Isso detecta URLs incorretas e problemas de descoberta de ferramentas antecipadamente. A resposta informa se o servidor foi conectado e quais ferramentas foram descobertas.

mka1 llm mcp-vault test-server \
  --server-id mcp_srv_123 \
  -H 'X-On-Behalf-Of: <end-user-id>'

const test = await sdk.llm.mcpVault.testServer({
  serverId: "mcp_srv_123",
  xOnBehalfOf: "<end-user-id>",
});

console.log(test);

const testResponse = await fetch(
  "https://apigw.mka1.com/api/v1/llm/mcp/servers/mcp_srv_123/test",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer <mka1-api-key>",
      "X-On-Behalf-Of": "<end-user-id>",
    },
  },
);

const test = await testResponse.json();
console.log(test);

curl https://apigw.mka1.com/api/v1/llm/mcp/servers/mcp_srv_123/test \
  --request POST \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --header 'X-On-Behalf-Of: <end-user-id>'

Consulte a referência da API Testar servidor MCP para detalhes sobre a solicitação e a resposta.

4. Crie o agente

Adicione uma ferramenta MCP ao agente com type: "mcp". Faça referência aos registros do cofre com mcp_server_id e mcp_credential_id. Você pode restringir ainda mais o acesso do agente com allowed_tools na definição da ferramenta.

mka1 agents create --body '{
  "name": "linear-triage-agent",
  "description": "Faz a triagem de issues do Linear e elabora atualizações.",
  "model": "meetkai:functionary-pt",
  "instructions": "Use o Linear por meio do MCP quando o usuário perguntar sobre triagem de issues. Confirme antes de criar ou editar registros externos.",
  "tools": [
    {
      "type": "mcp",
      "mcp_server_id": "mcp_srv_123",
      "mcp_credential_id": "mcp_cred_123",
      "allowed_tools": ["issues.list", "comments.create"],
      "require_approval": "always"
    }
  ],
  "tool_choice": "auto",
  "parallel_tool_calls": true,
  "metadata": {
    "team": "support"
  }
}' \
  -H 'X-On-Behalf-Of: <end-user-id>'

const agent = await sdk.agents.createAgent({
  xOnBehalfOf: "<end-user-id>",
  createAgentRequest: {
    name: "linear-triage-agent",
    description: "Faz a triagem de issues do Linear e elabora atualizações.",
    model: "meetkai:functionary-pt",
    instructions:
      "Use o Linear por meio do MCP quando o usuário perguntar sobre triagem de issues. Confirme antes de criar ou editar registros externos.",
    tools: [
      {
        type: "mcp",
        mcpServerId: "mcp_srv_123",
        mcpCredentialId: "mcp_cred_123",
        allowedTools: ["issues.list", "comments.create"],
        requireApproval: "always",
      },
    ],
    toolChoice: "auto",
    parallelToolCalls: true,
    metadata: {
      team: "support",
    },
  },
});

console.log(agent.id);

const agentResponse = await fetch("https://apigw.mka1.com/api/v1/agents", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer <mka1-api-key>",
    "X-On-Behalf-Of": "<end-user-id>",
  },
  body: JSON.stringify({
    name: "linear-triage-agent",
    description: "Faz a triagem de issues do Linear e elabora atualizações.",
    model: "meetkai:functionary-pt",
    instructions:
      "Use o Linear por meio do MCP quando o usuário perguntar sobre triagem de issues. Confirme antes de criar ou editar registros externos.",
    tools: [
      {
        type: "mcp",
        mcp_server_id: "mcp_srv_123",
        mcp_credential_id: "mcp_cred_123",
        allowed_tools: ["issues.list", "comments.create"],
        require_approval: "always",
      },
    ],
    tool_choice: "auto",
    parallel_tool_calls: true,
    metadata: {
      team: "support",
    },
  }),
});

const agent = await agentResponse.json();
console.log(agent.id);

curl https://apigw.mka1.com/api/v1/agents \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --header 'X-On-Behalf-Of: <end-user-id>' \
  --data '{
    "name": "linear-triage-agent",
    "description": "Faz a triagem de issues do Linear e elabora atualizações.",
    "model": "meetkai:functionary-pt",
    "instructions": "Use o Linear por meio do MCP quando o usuário perguntar sobre triagem de issues. Confirme antes de criar ou editar registros externos.",
    "tools": [
      {
        "type": "mcp",
        "mcp_server_id": "mcp_srv_123",
        "mcp_credential_id": "mcp_cred_123",
        "allowed_tools": ["issues.list", "comments.create"],
        "require_approval": "always"
      }
    ],
    "tool_choice": "auto",
    "parallel_tool_calls": true,
    "metadata": {
      "team": "support"
    }
  }'

Consulte a referência da API Criar um agente para todos os campos de agentes salvos.

5. Execute o agente

Execute o agente salvo com a entrada específica da tarefa. O agente reutiliza a configuração MCP salva e a referência de credencial.

mka1 agent-runs create \
  --agent-id agt_123 \
  --body '{
    "input": "Encontre minhas cinco issues de bugs mais recentes e elabore um breve resumo da triagem.",
    "metadata": {
      "source": "docs-recipe"
    }
  }' \
  -H 'X-On-Behalf-Of: <end-user-id>'

const run = await sdk.agentRuns.createAgentRun({
  agentId: "agt_123",
  xOnBehalfOf: "<end-user-id>",
  createAgentRunRequest: {
    input: "Encontre minhas cinco issues de bugs mais recentes e elabore um breve resumo da triagem.",
    metadata: {
      source: "docs-recipe",
    },
  },
});

console.log(run.id);

const runResponse = await fetch("https://apigw.mka1.com/api/v1/agents/agt_123/runs", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer <mka1-api-key>",
    "X-On-Behalf-Of": "<end-user-id>",
  },
  body: JSON.stringify({
    input: "Encontre minhas cinco issues de bugs mais recentes e elabore um breve resumo da triagem.",
    metadata: {
      source: "docs-recipe",
    },
  }),
});

const run = await runResponse.json();
console.log(run.id);

curl https://apigw.mka1.com/api/v1/agents/agt_123/runs \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --header 'X-On-Behalf-Of: <end-user-id>' \
  --data '{
    "input": "Encontre minhas cinco issues de bugs mais recentes e elabore um breve resumo da triagem.",
    "metadata": {
      "source": "docs-recipe"
    }
  }'

Use Recuperar uma execução de agente para consultar o status. Use Transmitir eventos de execução de agente quando sua interface precisar mostrar chamadas de ferramentas e progresso parcial.

Observações operacionais

Mantenha allowed_tools no nível do servidor amplo o suficiente para a integração e allowed_tools no nível da ferramenta tão restrito quanto o trabalho do agente permitir.
Prefira require_approval: "always" para ferramentas que alteram sistemas externos.
Alterne uma credencial criando uma nova credencial MCP e atualizando a ferramenta MCP do agente para fazer referência ao novo mcp_credential_id.
Exclua credenciais com o endpoint Excluir credencial MCP quando um usuário final desconectar uma integração.

Primeiros passos

Respostas

Recursos

Computação

CLI

Receitas

Benchmarks

Infraestrutura

Criar um agente com ferramentas MCP

1. Registre o servidor MCP

2. Armazene a credencial MCP

3. Teste o servidor

4. Crie o agente

5. Execute o agente

Observações operacionais

​1. Registre o servidor MCP

​2. Armazene a credencial MCP

​3. Teste o servidor

​4. Crie o agente

​5. Execute o agente

​Observações operacionais

1. Registre o servidor MCP

2. Armazene a credencial MCP

3. Teste o servidor

4. Crie o agente

5. Execute o agente

Observações operacionais