> ## Documentation Index
> Fetch the complete documentation index at: https://veryfront.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Coding agents

> Connect Claude Code, Cursor, Codex, and other MCP-aware coding agents to the Veryfront dev server.

Connect Claude Code, Cursor, Codex, or any MCP-aware coding agent to your Veryfront dev server. The agent gets a focused dev toolset: live errors and logs, route listing, route preview, scaffolding, test and lint runners.

This is the CLI's built-in MCP server. It is separate from the application-facing MCP server (see [MCP server](/code/guides/mcp-server)), which exposes *your* tools to MCP clients. The CLI MCP exposes *Veryfront dev tools* to your coding agent.

The CLI MCP server is development-only. `veryfront start` does not expose
`vf_*` tools in production.

## Prerequisites

* A Veryfront project (see [Create project](/code/getting-started/create-project)).
* An MCP-aware coding agent such as Claude Code, Cursor, or any client that
  speaks Model Context Protocol over HTTP or stdio.

## Project instructions

Starter templates include `AGENTS.md` at the project root. Coding agents should
read that file first. It explains Veryfront folders, the developer loop, the MCP
bootstrap step, inference setup, and when to use [https://veryfront.com/docs](https://veryfront.com/docs).

For older projects, add the same guide with:

```bash theme={null}
veryfront install agents
```

Tool-specific files are still available:

```bash theme={null}
veryfront install claude-code
veryfront install cursor
veryfront install copilot
veryfront install windsurf
```

Use `AGENTS.md` as the shared source of truth when multiple coding agents work
in the same project.

## Example: add an agent

Use the `ai-agent` template for the shortest runnable path. It creates a chat
page, an AG-UI route, an agent, a tool, and `AGENTS.md`.
The research-agent names below are examples. Use names that match your app
domain and workflow.

```bash theme={null}
veryfront init research-agent --template ai-agent --runtime deno
cd research-agent
veryfront login
```

If you do not have the CLI installed globally, use the package-manager entry:

```bash theme={null}
npm create veryfront -- research-agent --template ai-agent --runtime deno
cd research-agent
veryfront login
```

Add the project primitives for the research capability:

```bash theme={null}
veryfront generate agent research-agent
veryfront generate tool search-docs
veryfront generate skill research
```

Edit the generated agent, tool, and skill for your research workflow. To expose
the new agent through the starter chat route, update `app/api/ag-ui/route.ts` to
use `createAgUiHandler("research-agent")`.

With MCP connected, a coding agent can perform the same file generation with:

```text theme={null}
vf_bootstrap()
vf_get_conventions({ topic: "ai" })
vf_scaffold({ type: "agent", name: "research-agent" })
vf_scaffold({ type: "tool", name: "search-docs" })
vf_scaffold({ type: "skill", name: "research" })
vf_get_errors()
vf_run_lint()
```

Run `veryfront dev` after credentials are configured. The app needs model access
through `veryfront login`, `VERYFRONT_API_TOKEN`, or provider keys such as
`OPENAI_API_KEY` or `ANTHROPIC_API_KEY`.

## Choose a transport

The CLI MCP server supports two transports. Most agents work with HTTP.

| Transport | When to use it                                                    | How to start                        |
| --------- | ----------------------------------------------------------------- | ----------------------------------- |
| HTTP      | Your agent supports remote MCP URLs (Claude Code, Cursor, Codex). | Auto-starts with `veryfront dev`.   |
| stdio     | Your agent only supports stdio MCP servers.                       | Run `veryfront mcp` from the agent. |

When you run `veryfront dev`, the HTTP MCP server listens on `--port + 2`
(default `3002`). The endpoint is always `/mcp`.

```
http://localhost:3002/mcp        # dev
```

The dev server also accepts the `veryfront.me` hostname, which resolves to `127.0.0.1` and is what the CLI prints by default.

## Connect Claude Code

Add an `mcpServers` entry in `~/.claude.json`:

```json theme={null}
{
  "mcpServers": {
    "veryfront": {
      "url": "http://veryfront.me:3002/mcp"
    }
  }
}
```

Restart Claude Code, then run `veryfront dev` in your project. Claude Code discovers the Veryfront tools and prefixes them with `mcp__veryfront__` in its tool list.

## Connect Cursor

Open Cursor settings, find the **Model Context Protocol** section, and add a new server with:

* **Name:** `veryfront`
* **URL:** `http://localhost:3002/mcp`
* **Transport:** HTTP

Save and reload. Cursor's agent can now call Veryfront tools while you edit.

## Connect Codex (or any other MCP-aware client)

For any MCP-aware client that supports HTTP transport, point it at `http://localhost:3002/mcp` while `veryfront dev` is running. The CLI also exposes a stdio MCP server, so clients that require stdio can launch it as a subprocess:

```bash theme={null}
veryfront mcp
```

The stdio transport reads JSON-RPC requests on `stdin` and writes responses on `stdout`. Agents that only accept a command path can use the binary that `npm install -g veryfront` puts on `PATH`.

## What the agent can do

The CLI MCP exposes a focused toolset for the development loop. The names below are stable and prefix-namespaced with `vf_`:

| Tool                     | What it does                                                 |
| ------------------------ | ------------------------------------------------------------ |
| `vf_get_errors`          | Read live compile, runtime, bundle, HMR, and module errors.  |
| `vf_get_logs`            | Read dev-server logs with level, source, and pattern filter. |
| `vf_get_status`          | Inspect dev-server uptime, ports, and active features.       |
| `vf_list_routes`         | List every route the dev server has registered.              |
| `vf_preview_route`       | Render a route's HTTP response without opening a browser.    |
| `vf_scaffold`            | Generate routes, components, and AI primitives.              |
| `vf_run_tests`           | Run the project's test suite.                                |
| `vf_run_lint`            | Run the linter.                                              |
| `vf_trigger_hmr`         | Force a browser refresh after an external file change.       |
| `vf_list_templates`      | Browse the templates `veryfront init` supports.              |
| `vf_list_integrations`   | Browse the available integration connectors.                 |
| `vf_create_project`      | Bootstrap a new project from a template.                     |
| `vf_list_local_projects` | Find Veryfront projects on the filesystem.                   |

Use `tools/list` to inspect the tools exposed by the active MCP connection. Use
`vf_get_schema` from the agent, or `veryfront schema --json` from your shell,
when you need the CLI command schema.

At the start of a coding-agent session, ask the agent to call `vf_bootstrap`.
Then use `vf_get_conventions` before adding files, `vf_scaffold` for new files,
`vf_get_errors` after edits, and `vf_run_tests` or `vf_run_lint` for
verification. Use [https://veryfront.com/docs](https://veryfront.com/docs) when local files, MCP tools, and
CLI schema do not answer a Veryfront API or convention question.

## Verify it worked

Start the dev server:

```bash theme={null}
veryfront dev
```

Smoke-test the MCP endpoint with a `tools/list` request:

```bash theme={null}
curl -s -X POST http://localhost:3002/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | head -c 500
```

A working server returns a JSON-RPC response whose `result.tools` array lists `vf_get_errors`, `vf_scaffold`, and the other tools above. If you get a connection-refused error, the dev server is not running or is on a non-default port; check the dashboard for the printed MCP URL.

From inside a connected coding agent, ask it to "list routes" or "show recent dev errors". It calls the matching `vf_*` tool and streams the result back as text.

## Troubleshooting

### The agent does not see Veryfront tools

The dev server must be running. The HTTP MCP only listens while `veryfront dev`
is active.

### Port already in use

The dev MCP port follows the dev server port (`--port + 2`). If you start the dev server with `--port 4000`, the MCP server moves to `4002`. Update the URL in your agent config to match.

### CORS error from a browser-based agent

The HTTP MCP only accepts requests from `localhost`, `127.0.0.1`, and `veryfront.me`. Browser agents that run from any other origin are rejected by design.