---
type: how-to
title: Usa el servidor MCP
summary: Conecta un agente de IA a Caputchin a través del servidor MCP, autentícalo con un access token, y conduce la API de gestión en lenguaje natural, con un ejemplo trabajado.
---

El servidor MCP de Caputchin deja que un agente de IA (Claude, Cursor, o cualquier cliente de [Model Context Protocol](https://modelcontextprotocol.io)) gestione tu cuenta llamando a la misma [API de gestión](/docs/automation/management-api) que usa el dashboard. El servidor es un shell fino de transporte y auth: expone una herramienta MCP por operación de gestión y hace de proxy de cada llamada a la API. Así que el agente puede hacer cualquier cosa que tú puedas, salvo la facturación, en lenguaje natural.

## Acuña un access token [#mint-an-access-token]

El servidor se autentica con un access token de la variable de entorno `CAPUTCHIN_TOKEN`. Cualquier tipo funciona (ver [autenticación de la API](/docs/automation/management-api#mint-an-access-token)):

- un [personal access token](/docs/account-management/personal-access-token) para control de toda la cuenta, o
- un [troop access token](/docs/troops/tokens) para acotar el agente a ciertos equipos con mínimo privilegio, que es el valor por defecto más seguro al entregar acceso a un agente autónomo.

Copia el token al crearlo; se muestra una vez.

## Dos formas de conectar

Hay dos transportes, y exponen las **mismas herramientas** respaldadas por la misma API de gestión. Elige según cómo conecta tu cliente:

| | Local (stdio) | Alojado (HTTP) |
|---|---|---|
| Qué es | El paquete `@caputchin/mcp`, corriendo en tu máquina | Un endpoint remoto en `api.caputchin.com/mcp` |
| El cliente necesita | Lanzar un proceso local (stdio) | Conectar a un servidor MCP remoto (HTTP) |
| Auth | `CAPUTCHIN_TOKEN` en el entorno del proceso | Header `Authorization: Bearer` en la conexión |
| Mejor cuando | Dev local, un cliente de escritorio, sin red entrante | Un agente alojado, sin proceso local que lanzar |

### Local: el servidor npx (stdio)

El servidor se publica como `@caputchin/mcp` en npm. Normalmente no lo corres a mano; lo cableas en la config de tu cliente MCP y se lanza por stdio, con el token en su entorno:

```json
{
  "mcpServers": {
    "caputchin": {
      "command": "npx",
      "args": ["-y", "@caputchin/mcp"],
      "env": { "CAPUTCHIN_TOKEN": "cpt_pat_..." }
    }
  }
}
```

Para comprobar que corre, lánzalo directamente; habla MCP por stdio y sale con un error si falta el token:

```bash
CAPUTCHIN_TOKEN=cpt_pat_... npx -y @caputchin/mcp
```

### Alojado: el endpoint HTTP

Para clientes que conectan a un servidor MCP remoto en vez de lanzar uno local, Caputchin aloja el mismo servidor en:

```
https://api.caputchin.com/mcp
```

Se autentica con tu token como un header `Bearer` en la conexión (la misma credencial, solo pasada por HTTP en vez del entorno):

```json
{
  "mcpServers": {
    "caputchin": {
      "url": "https://api.caputchin.com/mcp",
      "headers": { "Authorization": "Bearer cpt_pat_..." }
    }
  }
}
```

La forma exacta de la config depende de tu cliente MCP; lo que importa es la URL y el header `Authorization: Bearer`. Nada que instalar, y ningún proceso local; la contrapartida es que el token viaja al endpoint alojado por petición en vez de quedarse en el entorno de un proceso local.

## Las herramientas

Cada herramienta se llama `caputchin_<verb>_<noun>` y mapea a una operación de gestión, por ejemplo `caputchin_list_troops`, `caputchin_create_site`, `caputchin_rotate_site_secret`, `caputchin_add_troop_member`, `caputchin_site_stats`. El agente descubre el conjunto completo y los parámetros de cada herramienta automáticamente por MCP, así que describes el objetivo y el agente elige las herramientas.

## Un ejemplo trabajado

Con el servidor cableado en tu cliente, puedes pedirle al agente en lenguaje llano:

> "Crea una clave de sitio llamada shop-frontend en mi equipo shop-team, luego activa el gate de juego para ella."

El agente lo resuelve en una secuencia de llamadas a herramientas: `caputchin_list_troops` para encontrar el id del equipo, `caputchin_create_site` con ese `troop_id`, luego `caputchin_update_site_security` para exigir un juego. Cada llamada golpea la API de gestión bajo tu token, y en Apex cada una aterriza en tu [audit log](/docs/audit-logs/overview) atribuida al token, así que las acciones de un agente son tan rastreables como las de una persona.

Como el agente actúa con el alcance completo de tu token, prefiere un token de equipo acotado cuando puedas, y revócalo en cuanto la tarea termine.

## La referencia completa

Para la lista completa de herramientas, cada una con una descripción de una línea y el permiso que su token debe tener, mira la [referencia de herramientas MCP](/docs/automation/mcp-tools). Las herramientas reflejan la API de gestión una a una, así que la [referencia interactiva de la API](/docs/api-reference) es la descripción autoritativa de los parámetros y la respuesta de cada operación: lee la descripción MCP de una herramienta para el resumen de cara al agente, y la referencia de la API para el esquema exacto.

## Véase también

- [Referencia de herramientas MCP](/docs/automation/mcp-tools): cada herramienta, su descripción, y el permiso que necesita.
- [Gestiona Caputchin desde la API](/docs/automation/management-api): la API HTTP que cada herramienta llama.
- [Usa Terraform o OpenTofu](/docs/automation/terraform): la superficie de infraestructura como código.
- [Personal access token](/docs/account-management/personal-access-token) y [tokens de equipo](/docs/troops/tokens): las credenciales que el servidor usa.