> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vertz.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Dev Server Tools for AI Agents
> Use the built-in MCP server and HTTP bridge to give AI agents full observability into your running Vertz app
The Vertz dev server exposes a built-in [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server and an HTTP bridge that give AI coding agents real-time access to errors, rendered pages, API specs, audit logs, and more. Instead of guessing whether code works, agents can **verify** by inspecting the running app.
## Quick setup
The MCP server is always available when the dev server is running — no extra flags needed:
```bash theme={null}
vtz dev
```
### Connect your AI tool
Add to your project's `.mcp.json`:
```json theme={null}
{
"mcpServers": {
"vertz-dev": {
"url": "http://localhost:3000/__vertz_mcp"
}
}
}
```
Claude Code auto-discovers the tools on connection.
For AI tools that don't support MCP natively, start the HTTP bridge on a separate port:
```bash theme={null}
vtz dev --bridge-port 3001
```
The bridge exposes the same tools as plain HTTP endpoints — no WebSocket required.
## Available tools
The dev server provides **21 MCP tools** that agents can call — 9 observability tools and 12 browser interaction tools (11 connected-tab + 1 headless screenshot):
### `vertz_get_errors`
Returns current compilation and runtime errors with file paths, line numbers, code snippets, and fix suggestions.
```json theme={null}
// No parameters needed
// Returns: { errors: [...], count: 2, category: "build" }
```
**When to use:** After every code change to verify nothing is broken. This is the single most important tool for agent workflows.
### `vertz_render_page`
Server-side renders a URL and returns an HTML "text screenshot" with render timing and metadata.
```json theme={null}
{ "url": "/tasks" }
// Returns: rendered HTML + timing + SSR status
```
**When to use:** To verify what a page looks like after making UI changes, without needing a browser.
### `vertz_get_audit_log`
Returns a unified timeline of all server events — API requests, SSR renders, compilations, file changes, and errors — with nanosecond-precision timestamps.
```json theme={null}
{ "last": 50, "type": "error,api_request", "since": "2026-04-05T14:30:00Z" }
```
All parameters are optional. `type` filters by event kind (comma-separated): `api_request`, `ssr_render`, `compilation`, `file_change`, `error`. `since` filters events after an ISO 8601 timestamp.
**When to use:** To understand what happened in the server after a change — did the API return errors? Did SSR fail? Were there compilation issues?
### `vertz_get_diagnostics`
Returns a health snapshot: uptime, compilation cache stats, module graph size, connected HMR clients, SSR pool metrics, and current errors.
```json theme={null}
// No parameters needed
```
**When to use:** To diagnose server health issues or understand the current state of the dev environment.
### `vertz_get_api_spec`
Returns an OpenAPI 3.1 specification with all entity CRUD routes, service endpoints, request/response schemas, and access rules.
```json theme={null}
{ "filter": "tasks,users" }
```
`filter` is optional — comma-separated entity/service names to include. Without it, returns the full spec.
**When to use:** To understand the API surface when writing frontend code or integration tests.
### `vertz_render_component`
Renders a single component in isolation with optional props.
```json theme={null}
{ "file": "src/components/TaskCard.tsx", "props": { "title": "Buy milk" } }
```
**When to use:** To quickly check a component's rendered output during iterative editing, without navigating to a page.
### `vertz_navigate`
Triggers client-side navigation in the browser via the HMR WebSocket — no full page reload.
```json theme={null}
{ "to": "/tasks/123" }
```
**When to use:** To navigate the user's browser to a specific page for visual verification.
### `vertz_get_events_url`
Returns the WebSocket URL for real-time event push, so agents can subscribe to live updates instead of polling.
```json theme={null}
// No parameters needed
// Returns: { url: "ws://localhost:3000/__vertz_mcp/events" }
```
### `vertz_get_console` (deprecated)
Use `vertz_get_audit_log` instead — it provides the same information in a more structured, filterable format.
## Browser interaction tools
These tools let agents interact with the live browser page — clicking buttons, filling forms, reading page state — without needing a separate browser automation tool like Playwright.
### `vertz_browser_list_tabs`
Lists all connected browser tabs with their current URL, title, and control status.
```json theme={null}
// No parameters needed
// Returns: { tabs: [{ id, url, title, controlled }] }
```
### `vertz_browser_connect`
Connects to a browser tab for interactive control. Returns a session ID and an initial page snapshot showing all interactive elements.
```json theme={null}
{ "tabId": "tab-abc123" }
// tabId is optional — auto-connects if only one tab is open
// Returns: { sessionId, tab: { id, url, title }, snapshot: { ... } }
```
### `vertz_browser_disconnect`
Releases a browser control session.
```json theme={null}
{ "sessionId": "sess-abc123" }
```
### `vertz_browser_snapshot`
Returns a structured snapshot of the page: interactive elements with refs, form structure, focused element, and current values.
```json theme={null}
{ "sessionId": "sess-abc123", "maxElements": 50 }
// sessionId is optional if only one session is active
```
The snapshot includes:
* **Elements**: inputs, buttons, selects, links, checkboxes — each with a stable `ref` for targeting
* **Forms**: form elements with their field refs, action, and method
* **Focused element**: which element currently has focus
* **URL and title**: current page state
### `vertz_browser_click`
Clicks an element. Target can be an element ref from a snapshot, a CSS selector, or a text/name/label matcher.
```json theme={null}
{ "target": "submit-btn" }
{ "target": "#my-button" }
{ "target": { "text": "Save" } }
// Returns updated snapshot after the page settles
```
### `vertz_browser_type`
Types text into an input or textarea.
```json theme={null}
{ "target": "email", "text": "user@example.com" }
```
### `vertz_browser_select`
Selects an option in a `