> ## 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.

# Criar um agente com ferramentas MCP

> Crie um agente salvo que chama um servidor MCP gerenciado pelo cofre com credenciais criptografadas por usuário final.

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:

* [Endpoints de coleção e execução de agentes](/pt/api-reference/agents/create-an-agent)
* [Endpoints de servidor do MCP Vault](/pt/api-reference/mcp-vault/create-mcp-server)
* [Endpoints de credenciais MCP](/pt/api-reference/mcp-vault/create-mcp-credential)

## 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.

<CodeGroup>
  ```bash CLI theme={null}
  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>'
  ```

  ```ts MKA1 SDK theme={null}
  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);
  ```

  ```ts fetch theme={null}
  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);
  ```

  ```bash bash theme={null}
  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"
      }
    }'
  ```
</CodeGroup>

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](/pt/api-reference/mcp-vault/create-mcp-server) 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.

<CodeGroup>
  ```bash CLI theme={null}
  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>'
  ```

  ```ts MKA1 SDK theme={null}
  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);
  ```

  ```ts fetch theme={null}
  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);
  ```

  ```bash bash theme={null}
  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>"
    }'
  ```
</CodeGroup>

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](/pt/api-reference/mcp-vault/list-mcp-credentials) 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.

<CodeGroup>
  ```bash CLI theme={null}
  mka1 llm mcp-vault test-server \
    --server-id mcp_srv_123 \
    -H 'X-On-Behalf-Of: <end-user-id>'
  ```

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

  console.log(test);
  ```

  ```ts fetch theme={null}
  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);
  ```

  ```bash bash theme={null}
  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>'
  ```
</CodeGroup>

Consulte a [referência da API Testar servidor MCP](/pt/api-reference/mcp-vault/test-mcp-server) 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.

<CodeGroup>
  ```bash CLI theme={null}
  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>'
  ```

  ```ts MKA1 SDK theme={null}
  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);
  ```

  ```ts fetch theme={null}
  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);
  ```

  ```bash bash theme={null}
  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"
      }
    }'
  ```
</CodeGroup>

Consulte a [referência da API Criar um agente](/pt/api-reference/agents/create-an-agent) 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.

<CodeGroup>
  ```bash CLI theme={null}
  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>'
  ```

  ```ts MKA1 SDK theme={null}
  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);
  ```

  ```ts fetch theme={null}
  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);
  ```

  ```bash bash theme={null}
  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"
      }
    }'
  ```
</CodeGroup>

Use [Recuperar uma execução de agente](/pt/api-reference/agent-runs/retrieve-an-agent-run) para consultar o status.
Use [Transmitir eventos de execução de agente](/pt/api-reference/agent-runs/stream-agent-run-events) 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](/pt/api-reference/mcp-vault/delete-mcp-credential) quando um usuário final desconectar uma integração.