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:
veryfront install --target agentsTool-specific files are still available:
veryfront install --target claude-code
veryfront install --target cursor
veryfront install --target copilot
veryfront install --target windsurfRunning 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.
veryfront init research-agent --template ai-agent --runtime deno
cd research-agent
veryfront loginIf you do not have the CLI installed globally, use the package-manager entry:
npm create veryfront -- research-agent --template ai-agent --runtime deno
cd research-agent
veryfront loginAdd the project primitives for the research capability:
veryfront generate agent research-agent
veryfront generate tool search-docs
veryfront generate skill researchEdit 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:
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.
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.
http://localhost:3002/mcp # devlocalhost 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:
{
"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:
veryfront mcpThe 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_:
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:
veryfront devSmoke-test the MCP endpoint with a tools/list request:
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 500The 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.