Formio MCP

Formio MCP server

The MCP server (@formio/mcp) is independently usable from any MCP-aware client. It speaks stdio: the client spawns it and owns stdin/stdout. There is no port to open and nothing to start by hand.

From a clone of this repo, the entry point is src/stdio.ts:

pnpm install

pnpm --filter @formio/mcp exec tsx src/stdio.ts

Run that way it waits for MCP traffic on stdin, which only tells you it starts cleanly — point a client at the command instead. A built package exposes the same entry point as the formio-mcp bin and as dist/stdio.js.

Transport

There is no HTTP or SSE transport. The server's only HTTP listener is the temporary browser-login page described under Authentication, which carries no MCP traffic.

Connect a client

The same stdio entry works everywhere, but the file it goes in and the key it goes under both vary by client — .mcp.json under mcpServers for Claude Code, .cursor/mcp.json under mcpServers for Cursor, .vscode/mcp.json under `servers` for VS Code, and .codex/config.toml as TOML for Codex. There is no universal .mcp.json. The root README carries the full per-client table; the JSON mcpServers shape is:

{

"mcpServers": { "formio-mcp": { "command": "npx", "args": ["-y", "@formio/mcp@1.0.1"], "env": { "FORMIO_PROJECT_URL": "https://your-project.form.io" } } } }

Every tool that reaches Form.io needs a project. It can come from a committed formio.json, from a per-directory mapping written by the project_set tool, or from FORMIO_PROJECT_URL in the environment — in that order, narrowest scope first, so a mapping overrides the environment and a committed file overrides both. FORMIO_BASE_URL is optional and usually unnecessary: the base URL is derived from the project URL's shape — https://api.form.io for a project on a form.io host, the parent path for a sub-directory-routed one — and is asked for only when it cannot be derived. No plugin manifest prompts for either value; every client records them per directory with project_set or a committed formio.json, and the .mcpb desktop bundle is the one exception because a desktop host has no working directory to interview in.

The server starts without either one, so a client can connect and list the tools before anything is configured — the project URL is only demanded at the point a tool needs it, and server_status works regardless.

Run in Docker

The server ships a Dockerfile and is published to Docker Hub as formio/mcp for linux/amd64 and linux/arm64. The image speaks stdio, so the MCP client owns stdin/stdout and the container must be run with -i:

docker run -i --rm \

-e FORMIO_PROJECT_URL=https://your-project.form.io \ -e FORMIO_API_KEY=your-api-key \ formio/mcp

Wired into a client — the same entry as Connect a client, with command and args pointed at Docker — that becomes (shown in the JSON mcpServers shape; VS Code uses servers and Codex uses TOML, as noted there):

{

"mcpServers": { "formio-mcp": { "command": "docker", "args": [ "run", "-i", "--rm", "-e", "FORMIO_PROJECT_URL", "-e", "FORMIO_API_KEY", "formio/mcp" ], "env": { "FORMIO_PROJECT_URL": "https://your-project.form.io", "FORMIO_API_KEY": "your-api-key" } } } }

Authentication in a container

FORMIO_API_KEY is the recommended path — no browser, nothing interactive. Browser login also works if you publish the auth port; see Headless environments for both.

Two container-specific notes regardless of auth mode. Prefer the FORMIO_PROJECT_URL environment variable over the project_set tool: project_set persists its per-directory mapping to ~/.formio/projects.json, which lives inside the container and is discarded when it exits. And the cwd argument every tool takes refers to a path *inside* the container, not on your host — while a workspace root the client reports is a host path, so pass cwd explicitly.

To reuse a token across container runs, mount the cache directory — it must be writable, since the server rewrites the file when a token is refreshed or cleared:

-v "$HOME/.formio:/root/.formio"

Self-hosted deployments

Two things commonly bite when the deployment is not public:

Hostname resolution. A private hostname won't resolve inside the container. Map it explicitly:

docker run -i --rm --add-host forms.internal:10.0.0.5 \

-e FORMIO_BASE_URL=https://forms.internal \ -e FORMIO_PROJECT_URL=https://forms.internal/my-project \ -e FORMIO_API_KEY=your-api-key \ formio/mcp

Private or self-signed certificates. The image trusts only the standard CA bundle. A certificate your host trusts — via the macOS keychain, say — will still fail inside the container, surfacing as a bare fetch failed from the tool. There are two cases, and they behave differently:

*Issued by a private CA.* Mount the CA certificate and point Node at it:

-v /path/to/rootCA.pem:/certs/rootCA.pem:ro -e NODE_EXTRA_CA_CERTS=/certs/rootCA.pem

*A fully self-signed server certificate* — one where subject and issuer are identical and there is no CA:TRUE basic constraint. NODE_EXTRA_CA_CERTS cannot fix this, even if you mount the server's own certificate: Node requires a trust anchor to be a CA, and rejects the chain with DEPTH_ZERO_SELF_SIGNED_CERT. Confirm which case you have with:

echo | openssl s_client -connect your-host:443 -servername your-host 2>/dev/null \

| openssl x509 -noout -subject -issuer

If subject and issuer match, your only option is FORMIO_INSECURE_TLS=1, which skips certificate verification only for requests to the configured deployment; every other host the server reaches is still verified. Use it for local development only — never against a production deployment.

Building the image locally

The build context is the repository root, not this directory: the image installs its dependencies from the repository's pnpm-lock.yaml with a frozen lockfile, so it carries exactly the versions the repository tested. Run this from the repository root:

docker build -f packages/mcp-server/Dockerfile -t formio-mcp .

Inspect it with MCP Inspector

The MCP Inspector connects to the server and lets you browse and call its tools by hand — useful for confirming a config works before wiring it into an agent. Start the web portal:

npx @modelcontextprotocol/inspector

It prints a URL carrying an auth token and opens a browser. The default port is 6274; if something already holds it, move both with CLIENT_PORT=6284 SERVER_PORT=6285.

Copy inspector-config.example.json to inspector-config.json, fill in your project URL and API key, and you have the file the next step asks for. That name is gitignored, so a filled-in copy cannot be committed by accident.

The same run, step by step:

1. Choose Add Servers → Import from client config.

2. Click "From file…". The dialog takes a client config file or a client installed on this machine — there is nowhere to paste JSON.

3. Select your `inspector-config.json`, and the server it defines is listed as new. Confirm with "Import 1 server".

4. Enable the server with the toggle on its card. It turns green and reports the negotiated protocol version once the container is up; the first connection is slower because Docker has to start it.

5. Open the Tools tab for the tools this server exposes. Every server lists all 25 — including project_set and project_get, which are registered for every client.

6. Pick a tool, fill in its arguments, and press "Execute Tool". The result appears in the middle pane and the JSON-RPC exchange in the right-hand Protocol panel. server_status touches no credentials and makes no Form.io request, so it isolates transport problems from auth problems; form_list below is a real call against a project.

Importing writes the server into the inspector's own catalog at ~/.mcp-inspector/mcp.json, so it is still there next time — remove it from the card when you are done. A tool that fails with a bare fetch failed is usually the deployment, not the server: see Self-hosted deployments for hostname resolution and certificate trust inside a container.

MCP server tools

The bundled @formio/mcp server exposes these 25 tools. Skills prefer these over raw HTTP whenever an operation is covered.

Forms

| form_revision_list | List a form's revision summaries (_id, _vid, _vnote, _vuser, created, `