Coding agents

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), 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).
  • 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.

For older projects, add the same guide with:

bash
veryfront install --target agents

Tool-specific files are still available:

bash
veryfront install --target claude-code
veryfront install --target cursor
veryfront install --target copilot
veryfront install --target windsurf

Running veryfront install without --target opens an interactive picker instead, preselecting the tools it detects in the project. Without a TTY (in CI, behind a pipe, or from a coding agent) there is no prompt: the detected tools are installed immediately, and a project with nothing to detect gets SKILL.md. Always pass --target in non-interactive environments.

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
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
npm create veryfront -- research-agent --template ai-agent --runtime deno
cd research-agent
veryfront login

Add the project primitives for the research capability:

bash
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
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.

TransportWhen to use itHow to start
HTTPYour agent supports remote MCP URLs (Claude Code, Cursor, Codex).Auto-starts with veryfront dev.
stdioYour agent only supports stdio MCP servers.Run veryfront mcp from the agent.

When you run veryfront dev, the HTTP MCP server listens two ports above the port the dev server bound (default 3002). The endpoint is always /mcp.

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

localhost is what the CLI prints by default; 127.0.0.1 reaches the same server.

Connect Claude Code

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

json
{
  "mcpServers": {
    "veryfront": {
      "url": "http://localhost: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
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_:

ToolWhat it does
vf_get_errorsRead live compile, runtime, bundle, HMR, and module errors.
vf_get_logsRead dev-server logs with level, source, and pattern filter.
vf_get_statusInspect dev-server uptime, ports, and active features.
vf_list_routesList every route the dev server has registered.
vf_preview_routeRender a route's HTTP response without opening a browser.
vf_scaffoldGenerate routes, components, and AI primitives.
vf_run_testsRun the project's test suite.
vf_run_lintRun the linter.
vf_trigger_hmrForce a browser refresh after an external file change.
vf_list_templatesBrowse the templates veryfront init supports.
vf_list_integrationsBrowse the available integration connectors.
vf_create_projectBootstrap a new project from a template.
vf_list_local_projectsFind 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 when local files, MCP tools, and CLI schema do not answer a Veryfront API or convention question.

For existing apps that need login, ask the agent to scaffold type: "auth" and name the provider, for example Authelia or generic OIDC. The auth scaffold writes config and environment placeholders only; it does not rewrite application routes. Review the diff against Application authentication.

Verify it worked

Start the dev server:

bash
veryfront dev

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

bash
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

The JSON-RPC response's result.tools array includes vf_get_errors and vf_scaffold. If the connection is refused, ensure the dev server is running and use its actual port plus two for MCP.

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 is always two above the port the dev server bound, so a dev server that bound 4000 serves MCP at http://localhost:4002/mcp. When the port you requested is already in use, the dev server falls forward to the next free one and MCP moves with it. Take the port from the URL the dev server printed rather than the --port you passed, then 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 [::1]. Browser agents that run from any other origin are rejected by design.