Saltar al contenido 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.

Usa la Agents API con MCP Vault cuando necesites agentes reutilizables que llamen herramientas de un servidor MCP externo. El vault mantiene la configuración del servidor y las credenciales fuera de la definición del agente. Así puedes rotar credenciales sin editar cada agente. Referencia de API: Usa el mismo X-On-Behalf-Of cuando el servidor, la credencial, el agente y la ejecución pertenezcan al mismo end user.

​
1. Registra el servidor MCP

Crea el servidor MCP una vez para la integración que usará el agente. Usa allowed_tools para exponer solo las herramientas necesarias. Usa require_approval cuando tu producto deba pedir confirmación antes de ejecutar una herramienta 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>'
La respuesta incluye un ID estable de servidor MCP, como mcp_srv_.... Consulta la referencia para crear un servidor MCP.

​
2. Guarda la credencial MCP

Crea una credencial para el servidor MCP. La credencial puede usar un bearer token, un valor Authorization, headers personalizados o ninguna autenticación. Guarda credenciales de end user con X-On-Behalf-Of para mantener el acceso aislado. 
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>'
La respuesta incluye un ID de credencial, como mcp_cred_.... Los secretos se guardan en el vault y no vuelven en las respuestas de listado.

​
3. Prueba el servidor

Prueba el servidor antes de conectarlo a un agente. La respuesta indica si el servidor conectó y qué herramientas se descubrieron. 
mka1 llm mcp-vault test-server \
  --server-id mcp_srv_123 \
  -H 'X-On-Behalf-Of: <end-user-id>'
Consulta la referencia para probar un servidor MCP.

​
4. Crea el agente

Agrega una herramienta MCP al agente con type: "mcp". Referencia los registros del vault con mcp_server_id y 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>'
Consulta la referencia para crear un agente.

​
5. Ejecuta el agente

Ejecuta el agente guardado con la entrada específica de la tarea. El agente reutiliza la configuración MCP y la referencia de credencial guardadas. 
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>'
Usa recuperar una ejecución de agente para consultar el estado. Usa transmitir eventos de ejecución para mostrar progreso en vivo.

​
Notas operativas

  • Mantén allowed_tools del servidor lo bastante amplio para la integración.
  • Mantén allowed_tools de la herramienta tan estrecho como permita el trabajo del agente.
  • Prefiere require_approval: "always" para herramientas que modifican sistemas externos.
  • Rota credenciales creando una nueva credencial MCP y actualizando el mcp_credential_id del agente.