# Surface for agents

- **Status:** current on 2026-11-06, for version 0.
- **Related documents:** [MCP server](https://surface.solenovis.com/docs/mcp-server.md), [skills](https://surface.solenovis.com/docs/skills.md), [plugins](https://surface.solenovis.com/docs/plugins.md), [llms.txt](https://surface.solenovis.com/docs/llms-txt.md), [ADR-0107](https://git.solenovis.com/henning.liemant/surface/src/branch/main/docs/adr/0107-an-mcp-server-for-agents.md)

A coding agent knows little about Surf. Surf looks like Svelte, so an agent often writes syntax that does not exist in Surf. Surface gives agents four tools. Each tool works alone, and they work best together.

| Tool | What it gives | Where it runs |
|---|---|---|
| [MCP server](https://surface.solenovis.com/docs/mcp-server.md) | The documents of this version, and the checks of the compiler | `surf mcp` on your computer, or the hosted server |
| [Skills](https://surface.solenovis.com/docs/skills.md) | Short rules that an agent reads when it writes Surf code | The folder of skills of your agent |
| [Plugins](https://surface.solenovis.com/docs/plugins.md) | The MCP server, the skills, a subagent and a rule, in one install | Claude Code, Codex CLI and Cursor |
| [llms.txt](https://surface.solenovis.com/docs/llms-txt.md) | The documents as plain text files | This website |

---

## 1. Choose a tool

- **Your agent has plugins.** Install the [plugin](https://surface.solenovis.com/docs/plugins.md). It adds the other tools.
- **Your agent has MCP.** Add the [MCP server](https://surface.solenovis.com/docs/mcp-server.md). Use the local server when `surf` is on your computer. Use the hosted server when it is not.
- **Your agent reads files or web pages only.** Give it [llms.txt](https://surface.solenovis.com/docs/llms-txt.md), or one document as Markdown.

---

## 2. How the tools help

The compiler knows each name of the language. A wrong utility, a wrong method or a wrong attribute is a compile error. So the best tool is the compiler itself:

1. The agent reads the document of the feature.
2. The agent writes the code.
3. The agent sends the code to `check_code`.
4. The agent fixes each error, and sends the code again.
5. The agent stops when `check_code` reports no error.

`check_code` runs `surf check` and `surf lint`. It does not run the code, and it writes no file.

---

## 3. Instructions for your project

Put this text into the instructions file of your project, for example `AGENTS.md` or `CLAUDE.md`:

```text
This project uses Surface. Its language is Surf. Surf is not Svelte, React or Flutter.
Before you write Surf code, call `list_sections` and `get_documentation` of the `surface` MCP server.
Call `check_code` on each new text until it reports no error. Then call `format_code`.
```

The text is short, so it costs little context. The skills and the documents give the details when the agent needs them.