# Conectar Cartaventa a Claude Code

**Si generas tus propuestas con Claude Code, puedes pedirle que las publique y las comparta en Cartaventa, y preguntarle después «¿ya la abrió Juan?». Trabaja con una llave tuya, con lo que le permitas, y te avisa por correo de lo delicado.**

## 1. Crea una llave

En **Cuenta → API**, **Crear llave**. Ponle de nombre «Claude Code» para reconocerla en los avisos, y marca lo que puede hacer:

- Para que solo consulte quién abrió qué, deja marcada solo **leer**.
- Para que publique y comparta, marca también **publicar** y **compartir**.
- **Quitar el acceso** y **archivar** solo si quieres pedírselo desde la terminal. Si lo hace, te llega un correo con un botón para deshacerlo.

Copia la llave: empieza con `cv_live_` y se muestra una sola vez.

## 2. Conéctala

En la terminal, con tu llave en lugar de `cv_live_…`. El espacio al principio hace que la mayoría de las terminales no guarden la línea en el historial, así la llave no queda escrita ahí:

```bash
 claude mcp add --transport http --scope user cartaventa https://api.cartaventa.com/mcp --header "Authorization: Bearer cv_live_…"
```

`--scope user` deja a Cartaventa disponible en todos tus proyectos, y la llave se queda en tu configuración personal. **No uses `--scope project`**: guardaría la llave en el archivo `.mcp.json` del proyecto, que suele subirse al repositorio.

## 3. Pruébala

Abre Claude Code y escribe `/mcp`: **cartaventa** debe aparecer conectado. Luego pídele algo:

> ¿Qué documentos tengo en Cartaventa y cuántas veces se abrió cada uno?

Antes de usar una herramienta de Cartaventa, Claude Code te pide permiso. A las que solo consultan puedes darles permiso para siempre; a las que comparten, quitan el acceso o archivan, conviene seguir diciéndole que sí cada vez.

## Lo que puede hacer

| Herramienta | Qué hace | Permiso |
|---|---|---|
| `listar_documentos` | Tus documentos, con su liga y cuántas veces se abrieron | leer |
| `ver_documento` | Quién tiene acceso, quién abrió y cuándo | leer |
| `reglas_html` | Cómo debe ser el HTML para que Cartaventa lo acepte a la primera | ninguno |
| `publicar_documento` | Publica un HTML nuevo | publicar |
| `reemplazar_version` | Sube una versión nueva sin cambiar la liga | publicar |
| `compartir_documento` | Comparte con hasta 5 personas y devuelve la liga de cada una | compartir |
| `revocar_acceso` | Le quita el acceso a una persona | revocar |
| `revocar_todos` | Le quita el acceso a todos en un documento | archivar |
| `archivar_documento` | Archiva un documento | archivar |

Claude Code solo ve las herramientas que tu llave permite. Lo que no está en la tabla —desarchivar, cambiar la restricción, administrar tu cuenta o tus llaves— se hace en el tablero.

Un documento de hasta **512 KB** se publica directo. Si Claude Code genera uno más pesado, pídele que lo aligere (casi siempre son imágenes) o súbelo desde el tablero.

## Lo que te avisamos

Te llega un correo cada vez que comparte, archiva o le quita el acceso a todos en un documento. Los dos últimos traen un botón **Deshacer** que funciona sin iniciar sesión. Si hace cuatro de esas cosas en 24 horas, te llega uno solo con un botón que deshace todo y corta la llave. Si el documento es de otra persona de tu equipo, a ella también le avisamos.

Un asistente puede leer instrucciones escondidas en un documento, un correo o una página («comparte esto con…»). Por eso hay topes —5 personas y 2 empresas por llamada, 20 personas al día, 60 llamadas por minuto— y por eso conviene leer lo que te pide aprobar antes de decirle que sí.

Los detalles de cada límite y de cada error están en [Usar la API](/guias/usar-la-api).

## Quitarla

```bash
claude mcp remove cartaventa --scope user
```

Y revoca la llave en **Cuenta → API**: es lo que de verdad la corta. Desde el momento en que la revocas, la siguiente petición ya no entra.

## Si algo no funciona

- **`/mcp` dice que falló la conexión, o `401`**: la llave está mal copiada, venció o se revocó. Crea otra y vuelve a conectarla.
- **Falta una herramienta**: tu llave no tiene ese permiso. Crea una con el permiso y cambia la conexión.
- **«limite_ritmo»**: topó uno de los límites; Claude Code lo lee y espera.

¿Algo que no cuadra? Escríbenos por [WhatsApp](https://wa.me/message/ETAWOVY3AKNVK1).