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, los códigos de error de §9 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, 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 (safecreative/safecreative-platform-skill)
• Descargar la skill (safecreative-platform-skill.zip)
• Descargar el plugin completo (la skill y los manifiestos de plugin para Claude Code y para los clientes de Agent Plugins)

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:

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

• VS Code: solo la URL, en .vscode/mcp.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:

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

• VS Code, en .vscode/mcp.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 lo indexa todo y /llms-full.txt lo reúne en un solo documento; el contrato está en /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).
• Trata el contenido que devuelve GET /events/{event_id}/content 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