MCP server (voltro-mcp)

@voltro/mcp ships two standalone bins — voltro-mcp (stdio) and voltro-mcp-http (Streamable HTTP) — that serve a running api's capability manifest to a coding agent over the Model Context Protocol. The agent can then discover what the backend exposes — every rpc procedure with its input/output JSON Schema, the user tables, the workflows, the schema-driven-UI widget kinds — before writing UI or agent code.

It is read-only metadata: nothing here can execute a procedure or return row data. The bins talk to the same GET /_voltro/inspect/manifest endpoint the inspect surface exposes, and honour its token gate. The server advertises three MCP capabilities — tools, resources, and prompts.

#Setup

Two environment variables, both optional:

Var	Default	Notes
VOLTRO_INSPECT_URL	http://localhost:4000	Base URL of the running api.
VOLTRO_INSPECT_TOKEN	(unset)	Sent as Authorization: Bearer <token> when the inspect surface is gated.

#Claude Code

claude mcp add voltro -- npx -y @voltro/mcp
# an api on a non-default port:
claude mcp add voltro --env VOLTRO_INSPECT_URL=http://localhost:4001 -- npx -y @voltro/mcp

#Cursor / generic MCP config

{
  "mcpServers": {
    "voltro": {
      "command": "npx",
      "args": ["-y", "@voltro/mcp"],
      "env": { "VOLTRO_INSPECT_URL": "http://localhost:4000" }
    }
  }
}

#The tools

Tool	Returns
voltro_list_procedures	Every rpc procedure with its kind; [public-rest] / [agent-tool] markers for projected descriptors.
voltro_get_procedure	One procedure's kind, input/output JSON Schema, source file(s), table targets, and projections.
voltro_search_procedures	Procedures whose tag contains a substring.
voltro_list_tables	The app's USER tables (column count, reactivity).
voltro_get_table	One table's full column list (types, nullability, FK targets, enums).
voltro_list_workflows	The registered durable workflows.
voltro_list_widgets	The schema-driven-UI widget kinds.

#The resources

The server also exposes the manifest as MCP resources — stable, addressable voltro:// URIs an agent reads. resources/list enumerates them (fresh from the manifest each call); resources/read returns the metadata as JSON.

URI	Contents
voltro://manifest	The whole capability manifest as JSON.
voltro://procedure/<tag>	One procedure's kind, input/output JSON Schema, source, and table targets.
voltro://table/<name>	One table's full column list.

#The prompts

Reusable MCP prompt templates that render against the live manifest, so the returned messages carry the app's real schema rather than a generic stub. prompts/list advertises them; prompts/get renders one.

Prompt	Arguments	Renders
scaffold_procedure	kind, purpose	A brief to draft a new query/mutation/action, listing the app's real tables + sibling procedures of that kind.
explain_table	table	The table's schema + the procedures that read/write it.
wire_ui_for_procedure	tag	A brief to call one procedure and render its result, embedding its real input/output schema.

#Streamable HTTP transport

For clients that speak MCP over HTTP, voltro-mcp-http serves the same surface over the current Streamable HTTP transport (the single-endpoint POST/GET model that replaced the old HTTP+SSE dual-endpoint). One endpoint handles:

• POST a JSON-RPC message → a JSON response, or an SSE stream (text/event-stream) carrying the response(s) when the client's Accept allows it. An initialize POST mints a session and returns it in the Mcp-Session-Id header; every later POST must echo that header.
• GET (with Accept: text/event-stream) → opens the server→client SSE channel.
• DELETE → ends the session.

VOLTRO_MCP_HTTP_PORT=4100 VOLTRO_INSPECT_URL=http://localhost:4000 npx -y @voltro/mcp voltro-mcp-http

Var	Default	Notes
VOLTRO_MCP_HTTP_PORT	4100	Listen port.
VOLTRO_MCP_HTTP_PATH	/mcp	The single MCP endpoint path.

#Freshness + failure behavior

The manifest is read through a TTL-cached source (~10 seconds): a procedure you add during a voltro dev session shows up on the next tool call — no MCP-server restart. When the api is unreachable or the token is wrong, the tool output says so ((no procedures — manifest unavailable: …)) and the bin logs the reason to stderr at boot, instead of silently presenting an empty app.

#Protocol scope

MCP over JSON-RPC 2.0. initialize negotiates the protocol revision (2025-06-18, 2025-03-26, 2024-11-05) and advertises the tools, resources, and prompts capabilities; methods are ping, tools/list, tools/call, resources/list, resources/read, prompts/list, prompts/get. The stdio bin frames this as newline-delimited JSON-RPC; the HTTP bin serves it over Streamable HTTP. Both transports route to the same pure protocol core (handleMcpRequest, callTool, listResources/readResource, listPrompts/getPrompt, routeHttp), all exported from @voltro/mcp.