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

# Crear un agente con herramientas MCP

> Crea un agente guardado que llama a un servidor MCP gestionado por el vault con credenciales cifradas por end user.

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:

* [Endpoints de agentes y ejecuciones](/es/api-reference/agents/create-an-agent)
* [Endpoints de servidores MCP Vault](/es/api-reference/mcp-vault/create-mcp-server)
* [Endpoints de credenciales MCP](/es/api-reference/mcp-vault/create-mcp-credential)

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.

<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": "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>'
  ```

  ```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>",
    createMcpServerRequest: {
      name: "Linear",
      serverLabel: "linear",
      serverUrl: "https://mcp.linear.app/mcp",
      serverDescription: "Access Linear issues, projects, and comments.",
      allowedTools: ["issues.list", "issues.create", "comments.create"],
      requireApproval: "always",
      metadata: {
        integration: "linear",
      },
    },
  });

  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": "Access Linear issues, projects, and comments.",
      "allowed_tools": ["issues.list", "issues.create", "comments.create"],
      "require_approval": "always",
      "metadata": {
        "integration": "linear"
      }
    }'
  ```
</CodeGroup>

La respuesta incluye un ID estable de servidor MCP, como `mcp_srv_...`.
Consulta la [referencia para crear un servidor MCP](/es/api-reference/mcp-vault/create-mcp-server).

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

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

  ```ts MKA1 SDK theme={null}
  const credential = await sdk.llm.mcpVault.createCredential({
    serverId: "mcp_srv_123",
    xOnBehalfOf: "<end-user-id>",
    createMcpCredentialRequest: {
      name: "Personal Linear token",
      authType: "bearer",
      bearerToken: "<linear-api-key>",
    },
  });

  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": "Personal Linear token",
      "auth_type": "bearer",
      "bearer_token": "<linear-api-key>"
    }'
  ```
</CodeGroup>

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.

<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);
  ```

  ```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>

Consulta la [referencia para probar un servidor MCP](/es/api-reference/mcp-vault/test-mcp-server).

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

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

  ```ts MKA1 SDK theme={null}
  const agent = await sdk.agents.createAgent({
    xOnBehalfOf: "<end-user-id>",
    createAgentRequest: {
      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",
          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);
  ```

  ```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": "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"
      }
    }'
  ```
</CodeGroup>

Consulta la [referencia para crear un agente](/es/api-reference/agents/create-an-agent).

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

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

  ```ts MKA1 SDK theme={null}
  const run = await sdk.agentRuns.createAgentRun({
    agentId: "agt_123",
    xOnBehalfOf: "<end-user-id>",
    createAgentRunRequest: {
      input: "Find my five newest bug issues and draft a short triage summary.",
      metadata: {
        source: "docs-recipe",
      },
    },
  });

  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": "Find my five newest bug issues and draft a short triage summary.",
      "metadata": {
        "source": "docs-recipe"
      }
    }'
  ```
</CodeGroup>

Usa [recuperar una ejecución de agente](/es/api-reference/agent-runs/retrieve-an-agent-run) para consultar el estado.
Usa [transmitir eventos de ejecución](/es/api-reference/agent-runs/stream-agent-run-events) 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.