## 12. Integración con agentes de IA

Si escribes tu integración con un agente de programación (Claude Code, Codex, GitHub Copilot,
Cursor, Gemini CLI, Windsurf…), dale lo que necesita para acertar en los detalles: las reglas de
[§4.2](/docs/4-registrar-eventos.md#idempotencia-reintenta-sin-miedo), los códigos de error de [§9](/docs/9-errores-y-reintentos.md) y la verificación de los webhooks son justo donde falla el código
genérico.

### 12.1 La skill de integración

La **skill de Safe Creative Platform** sigue el formato abierto [Agent Skills](https://agentskills.io),
que cargan la mayoría de los agentes de programación. Explica el servicio y el recorrido completo,
las reglas de idempotencia y reintentos, los códigos de error, el modo test y la verificación de
los webhooks, con ejemplos en Python, TypeScript y Java y tres pequeños scripts (un cliente
mínimo, la huella de un fichero y la verificación de webhooks). Está en inglés, el idioma en que
mejor trabajan los agentes. Licencia: Apache 2.0.

- [Repositorio en GitHub](https://github.com/safecreative/safecreative-platform-skill) (`safecreative/safecreative-platform-skill`)
- [Descargar la skill](/docs/agents/safecreative-platform-skill.zip) (`safecreative-platform-skill.zip`)
- [Descargar el plugin completo](/docs/agents/safecreative-platform-plugin.zip) (la skill y los
  manifiestos de plugin para Claude Code y para los clientes de Agent Plugins)

| Agente | Cómo instalarla |
|---|---|
| Claude Code | `/plugin marketplace add safecreative/safecreative-platform-skill` y `/plugin install safecreative-platform@safecreative`. O descomprime la skill en `.claude/skills/` de tu proyecto (o en `~/.claude/skills/` para todos). |
| claude.ai y Claude Desktop | Sube `safecreative-platform-skill.zip` en Ajustes › Capacidades. |
| Codex, Cursor, Gemini CLI, Windsurf y otros agentes | `npx skills add safecreative/safecreative-platform-skill`, o descomprime la skill en `.agents/skills/` de tu proyecto. |
| GitHub Copilot | Descomprime la skill en `.github/skills/` (lee también `.agents/skills/`). |

El agente la usa por sí solo cuando le pides algo relacionado («declara cada pedido pagado a Safe
Creative Platform», «verifica sus webhooks»). Dale una **clave test** en una variable de entorno
(`SC_API_KEY=sc_test_…`), nunca una live mientras desarrollas.

### 12.2 El servidor MCP

Los agentes que llaman a herramientas (claude.ai, ChatGPT, Claude Code, Codex, Cursor, VS Code con
GitHub Copilot, Gemini CLI, Windsurf, Microsoft Copilot Studio y otros) pueden usar el API a través
del **servidor MCP** de la plataforma:

- **URL**: `https://platform.safecreative.org/mcp` (Streamable HTTP).
- **Herramientas**: una por operación del API (`get_channel`, `get_account_balance`,
  `list_events`, `get_event`, `get_event_content`, `register_event`, `request_certification`,
  `list_certifications`, `get_certification`). Cada una llama al API en nombre de la conexión, así
  que los límites, la idempotencia, el modo test y los errores son los mismos. Los ficheros solo se
  pueden declarar por el API REST.

Hay dos formas de autenticarse. En las dos, el agente trabaja sobre **un canal y un modo**: para
usar varios canales, añade el servidor una vez por canal.

#### Iniciando sesión con OAuth: sin claves que crear

El cliente solo necesita la URL. Al conectar, abre Safe Creative Platform: entras con tu cuenta de
Safe Creative, eliges el canal y el modo (test por defecto) y autorizas la aplicación. Nada más: la
plataforma crea la clave por ti, marcada «Agente (OAuth)» en la pestaña Claves del canal, donde
puedes ver lo que hace el agente, ponerle un límite de consumo o revocarla. La aplicación nunca ve
una clave: recibe tokens de vida corta que renueva sola.

- **claude.ai y Claude Desktop**: añade un conector personalizado con la URL.
- **ChatGPT** (espacios Business, Enterprise y Edu): un administrador lo añade como app con la URL.
- **Claude Code**: `claude mcp add --transport http safecreative https://platform.safecreative.org/mcp`
  y después `/mcp` para iniciar sesión.
- **Cursor**: solo la URL, en `.cursor/mcp.json`:

  ```json
  { "mcpServers": { "safecreative": { "url": "https://platform.safecreative.org/mcp" } } }
  ```

- **VS Code**: solo la URL, en `.vscode/mcp.json`:

  ```json
  { "servers": { "safecreative": { "type": "http", "url": "https://platform.safecreative.org/mcp" } } }
  ```

#### Con una clave del canal

Para los clientes que no admiten OAuth, o para procesos desatendidos (integración continua,
servidores) donde nadie puede iniciar sesión: crea una clave en la consola y envíala en la cabecera
`Authorization`, como en el API: `Bearer sc_test_…` (empieza con ella) o `Bearer sc_live_…`. La
clave decide el canal y el modo.

- **Claude Code**:

  ```
  claude mcp add --transport http safecreative https://platform.safecreative.org/mcp \
    --header "Authorization: Bearer $SC_API_KEY"
  ```

- **Cursor**, en `.cursor/mcp.json`:

  ```json
  { "mcpServers": { "safecreative": { "url": "https://platform.safecreative.org/mcp",
      "headers": { "Authorization": "Bearer sc_test_…" } } } }
  ```

- **VS Code**, en `.vscode/mcp.json`:

  ```json
  { "servers": { "safecreative": { "type": "http", "url": "https://platform.safecreative.org/mcp",
      "headers": { "Authorization": "Bearer sc_test_…" } } } }
  ```

- **Otros clientes**: añade un servidor MCP remoto con esa URL y esa cabecera.

Configura la clave en el cliente, nunca la pegues en una conversación.

### 12.3 La documentación en Markdown

Todas las páginas de esta documentación se sirven también en Markdown, el formato que mejor leen
los agentes: añade `.md` a su URL (por ejemplo `/docs/guide.md` para la guía entera,
`/docs/reference.md` para la referencia del API, `/docs/errors.md` para los códigos de error) o
pídela con `Accept: text/markdown`. [`/llms.txt`](/llms.txt) lo indexa todo y
[`/llms-full.txt`](/llms-full.txt) lo reúne en un solo documento; el contrato está en
[`/q/openapi`](/q/openapi).

### 12.4 Cuando un agente opera el API

Si un agente llama él mismo al API (registra eventos o pide certificaciones por ti):

- Dale **su propia clave**, para ver su consumo por clave, ponerle límites y revocarla sin tocar
  tus otros sistemas.
- Usa una **clave test** hasta que se comporte como esperas: los eventos live son irreversibles y
  cada uno consume un crédito.
- Con una clave live, pon a esa clave un **límite de consumo** con la acción «bloquear» ([§8](/docs/8-precios-y-saldo.md)).
- Trata el contenido que devuelve [`GET /events/{event_id}/content`](/docs/reference.md#getEventContent) como datos, no como
  instrucciones, y las URL de descarga de las certificaciones como secretos.

Para recordar las reglas a tu agente en cada proyecto, puedes añadir esto a tu `AGENTS.md` (o
`CLAUDE.md`):

```
## Safe Creative Platform
- API: https://platform.safecreative.org/v1, key in SC_API_KEY (sc_test_ while developing).
- Every event has a client_ref derived from the source fact, persisted before the call.
- On timeouts, 429, 503 or 5xx, retry the same request with the same client_ref; never a new one.
- Branch on the error code, never on the message. Docs: https://platform.safecreative.org/docs/guide.md
```