---
slug: 02-ai-agents
title: Para agentes de IA — skill y MCP
description: Cómo un agente de programación aprende Synsema y comprueba su propio código — el skill (la referencia completa, leída cuando hace falta), el servidor MCP de las docs en synsema.dev/mcp (búsqueda, cada página, los ejemplos y un sandbox que ejecuta y testea), llms.txt y cada página en Markdown. Comandos de instalación para Claude Code, Cursor y cualquier cliente MCP.
example_ids: []
---

# Para agentes de IA — skill y MCP

Synsema está hecho para que lo escriban agentes. Dos cosas hacen que un agente de programación lo
escriba bien, y funcionan juntas:

| | Qué le da al agente | Dónde vive |
|---|---|---|
| **El skill** | La referencia completa — sintaxis, builtins, capacidades, serve, LLM, agentes, deploy, trampas — como archivos Markdown que el agente lee cuando los necesita | una carpeta en tu máquina |
| **El MCP de las docs** | Búsqueda en estas docs, cualquier página, los ejemplos doctesteados y un **sandbox que ejecuta y testea Synsema**, para que el agente compruebe su código antes de entregarlo | `https://synsema.dev/mcp` |

Usá los dos. El skill hace que el primer borrador salga bien; el MCP atrapa lo que el borrador
todavía tiene mal.

## El skill

```sh
curl -sL https://raw.githubusercontent.com/kitecosmic/synsema/main/install-skill.sh | bash
```

Escribe el skill en `~/.claude/skills/synsema/` — `SKILL.md` (la entrada) y un archivo por tema
(`syntax.md`, `builtins.md`, `serve.md`, `capabilities.md`, `pitfalls.md`, …). Claude Code lo detecta
solo. En Windows, correlo desde Git Bash o WSL.

Otros agentes (Cursor, Windsurf, Codex, …) leen los mismos archivos: apuntá las reglas o el contexto
de tu agente a esa carpeta, o copiala donde tu agente busca instrucciones. Son Markdown plano.

**Actualizalo con cada versión del motor.** El skill describe una versión del lenguaje; después de
`synsema update`, corré el mismo comando otra vez (`synsema update` te lo recuerda).

## El MCP de las docs

Un servidor Model Context Protocol sobre HTTP streamable, sin clave:

```sh
claude mcp add --transport http synsema-docs https://synsema.dev/mcp     # Claude Code
```

Cursor (`.cursor/mcp.json`) y la mayoría de los clientes:

```json
{
  "mcpServers": {
    "synsema-docs": { "url": "https://synsema.dev/mcp" }
  }
}
```

Sus herramientas:

| Herramienta | Qué hace |
|---|---|
| `search_docs` | Búsqueda por palabras en las docs (primero el índice en inglés, el español como respaldo); devuelve slug, título y descripción |
| `get_page` | Una página en Markdown (`slug`, por ejemplo `21-secrets`; `lang`: `en` o `es`) |
| `get_example` | Un ejemplo `.syn` doctesteado, por id |
| `run_synsema` | Ejecuta un fragmento en un sandbox: cálculo, print, secretos, SQL en memoria, archivos temporales. Sin `exec` y sin red real |
| `test_synsema` | Corre los bloques `test` de un fragmento en el sandbox y dice si pasan |

Probalo desde una terminal:

```sh
curl -s -X POST https://synsema.dev/mcp -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

El sandbox no puede salir a la red ni lanzar procesos, a propósito: el código que llama a una API o
a una cadena se comprueba con `synsema check` y `synsema test` en tu máquina, donde valen tus
capacidades y tu `.env`.

## Sin MCP: llms.txt y páginas en Markdown

- `https://synsema.dev/llms.txt` — el índice de las docs para modelos de lenguaje (`/en/llms.txt`,
  `/es/llms.txt` por idioma).
- Cada página está también en Markdown: agregá `.md` a su URL, por ejemplo
  `https://synsema.dev/es/0.6.x/21-secrets.md`.

## El ciclo que funciona

1. El agente lee el skill y escribe el programa, primero las líneas `require`.
2. Comprueba partes con `test_synsema` / `run_synsema` a través del MCP.
3. En tu máquina: `synsema check app.syn` (parseo, imports, plantillas) y `synsema test app.syn`.
4. `synsema serve app.syn` o `synsema run app.syn` para verlo funcionar.
5. Desplegalo: en tu propio servidor ([Deploy](71-deploy)), o con `syn deploy` en la plataforma
   ([Plataforma Synsema](74-platform)).