---
slug: 02-ai-agents
title: For AI agents — skill and MCP
description: How a coding agent learns Synsema and checks its own code — the skill (the whole reference, read on demand), the docs MCP server at synsema.dev/mcp (search, every page, the examples and a sandbox that runs and tests), llms.txt and every page as Markdown. Install commands for Claude Code, Cursor and any MCP client.
example_ids: []
---

# For AI agents — skill and MCP

Synsema is written to be written by agents. Two things make a coding agent good at it, and they
work together:

| | What it gives the agent | Where it lives |
|---|---|---|
| **The skill** | The whole reference — syntax, builtins, capabilities, serve, LLM, agents, deploy, pitfalls — as Markdown files the agent reads when it needs them | a folder on your machine |
| **The docs MCP** | Search over these docs, any page, the doctested examples, and a **sandbox that runs and tests Synsema** so the agent checks its code before handing it over | `https://synsema.dev/mcp` |

Use both. The skill makes the first draft right; the MCP catches what the draft still gets wrong.

## The skill

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

It writes the skill to `~/.claude/skills/synsema/` — `SKILL.md` (the entry point) and one file per
topic (`syntax.md`, `builtins.md`, `serve.md`, `capabilities.md`, `pitfalls.md`, …). Claude Code
detects it by itself. On Windows, run it from Git Bash or WSL.

Other agents (Cursor, Windsurf, Codex, …) read the same files: point your agent's rules or context
at that folder, or copy it where your agent looks for instructions. The files are plain Markdown.

**Refresh it on every engine release.** The skill describes one version of the language; after
`synsema update`, run the same command again (`synsema update` reminds you).

## The docs MCP

A Model Context Protocol server over streamable HTTP, no key needed:

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

Cursor (`.cursor/mcp.json`) and most other clients:

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

Its tools:

| Tool | What it does |
|---|---|
| `search_docs` | Keyword search over the docs (English index first, Spanish as fallback); returns slug, title and description |
| `get_page` | One page as Markdown (`slug`, e.g. `21-secrets`; `lang`: `en` or `es`) |
| `get_example` | A doctested `.syn` example by id |
| `run_synsema` | Runs a snippet in a sandbox: compute, print, secrets, in-memory SQL, scratch files. No `exec` and no real network |
| `test_synsema` | Runs a snippet's `test` blocks in the sandbox and reports pass/fail |

Check it from a terminal:

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

The sandbox cannot reach the network or run processes, on purpose: code that calls an API or a
chain is checked with `synsema check` and `synsema test` on your machine, where your capabilities
and your `.env` apply.

## Without MCP: llms.txt and Markdown pages

- `https://synsema.dev/llms.txt` — the index of the docs for language models (`/en/llms.txt`,
  `/es/llms.txt` per language).
- Every page is also Markdown: add `.md` to its URL, e.g.
  `https://synsema.dev/en/0.6.x/21-secrets.md`.

## The loop that works

1. The agent reads the skill and writes the program, `require` lines first.
2. It checks pieces with `test_synsema` / `run_synsema` through the MCP.
3. On your machine: `synsema check app.syn` (parse, imports, templates) and `synsema test app.syn`.
4. `synsema serve app.syn` or `synsema run app.syn` to see it work.
5. Deploy it: your own server ([Deploy](71-deploy)), or `syn deploy` to the hosted platform
   ([Synsema platform](74-platform)).