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 a Agents API com o MCP Vault quando precisar de agentes reutilizáveis que chamem ferramentas de um servidor MCP externo. O vault mantém a configuração do servidor e as credenciais fora da definição do agente. Assim, sua aplicação pode rotacionar credenciais sem editar cada agente. Referência da API: Use o mesmo X-On-Behalf-Of quando o servidor, a credencial, o agente e a execução pertencerem ao mesmo end user.

​
1. Registre o servidor MCP

Crie o servidor MCP uma vez para a integração que o agente vai usar. Use allowed_tools para expor apenas as ferramentas necessárias. Use require_approval quando seu produto deve pedir confirmação antes de executar uma ferramenta MCP. 
mka1 llm mcp-vault create-server --body '{
  "name": "Linear",
  "server_label": "linear",
  "server_url": "https://mcp.linear.app/mcp",
  "server_description": "Access Linear issues, projects, and comments.",
  "allowed_tools": ["issues.list", "issues.create", "comments.create"],
  "require_approval": "always",
  "metadata": {
    "integration": "linear"
  }
}' \
  -H 'X-On-Behalf-Of: <end-user-id>'
A resposta inclui um ID estável de servidor MCP, como mcp_srv_.... Veja a referência para criar servidor MCP.

​
2. Armazene a credencial MCP

Crie uma credencial para o servidor MCP. A credencial pode usar bearer token, valor Authorization, headers personalizados ou nenhuma autenticação. Armazene credenciais de end user com X-On-Behalf-Of para manter o acesso isolado. 
mka1 llm mcp-vault create-credential \
  --server-id mcp_srv_123 \
  --body '{
    "name": "Personal Linear token",
    "auth_type": "bearer",
    "bearer_token": "<linear-api-key>"
  }' \
  -H 'X-On-Behalf-Of: <end-user-id>'
A resposta inclui um ID de credencial, como mcp_cred_.... Os segredos ficam no vault e não aparecem nas respostas de listagem.

​
3. Teste o servidor

Teste o servidor antes de anexá-lo a um agente. A resposta informa se o servidor conectou e quais ferramentas foram descobertas. 
mka1 llm mcp-vault test-server \
  --server-id mcp_srv_123 \
  -H 'X-On-Behalf-Of: <end-user-id>'
Veja a referência para testar servidor MCP.

​
4. Crie o agente

Adicione uma ferramenta MCP ao agente com type: "mcp". Referencie os registros do vault com mcp_server_id e mcp_credential_id. 
mka1 agents create --body '{
  "name": "linear-triage-agent",
  "description": "Triages Linear issues and drafts updates.",
  "model": "auto",
  "instructions": "Use Linear through MCP when the user asks about issue triage. Confirm before creating or editing external records.",
  "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>'
Veja a referência para criar um agente.

​
5. Execute o agente

Execute o agente salvo com a entrada específica da tarefa. O agente reutiliza a configuração MCP e a referência de credencial salvas. 
mka1 agent-runs create \
  --agent-id agt_123 \
  --body '{
    "input": "Find my five newest bug issues and draft a short triage summary.",
    "metadata": {
      "source": "docs-recipe"
    }
  }' \
  -H 'X-On-Behalf-Of: <end-user-id>'
Use recuperar uma execução de agente para consultar o status. Use transmitir eventos de execução para mostrar progresso ao vivo.

​
Notas operacionais

  • Mantenha o allowed_tools do servidor amplo o suficiente para a integração.
  • Mantenha o allowed_tools da ferramenta tão restrito quanto o trabalho do agente permitir.
  • Prefira require_approval: "always" para ferramentas que modificam sistemas externos.
  • Rotacione uma credencial criando uma nova credencial MCP e atualizando o mcp_credential_id do agente.