Getting Started
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§
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:
claude mcp add --transport http synsema-docs https://synsema.dev/mcp # Claude Code
Cursor (.cursor/mcp.json) and most other clients:
{
"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:
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
.mdto 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), or syn deploy to the hosted platform (Synsema platform).