formio/ai / plugin/skills/formio-mcp-setup
formio-mcp-setup
VerifiedConnects the Form.io MCP server (`@formio/mcp`) to the running coding agent — Claude Code, Cursor, VS Code, or Codex — so the Form.io skills have tools to call, then records which Form.io project this directory uses. Use when a Form.io skill finds the MCP tools missing, when no Form.io tools are available, or when the user asks to install, connect, configure, or fix the Form.io MCP server. Not for: logging in to Form.io — the server opens that in the browser on the first tool call; an application's end-user auth (see `formio-auth`); building anything with Form.io — return to the skill that sent you here.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 23.8 KB |
| references/project-urls.md | markdown | 8.4 KB |
references/project-urls.md
View on GitHub# Obtaining the Project URL and the Base URL
The two values every Form.io application is configured with. This document is how you get them — with the MCP server, or without it.
## The two values, and the names they travel under
| Value | What it is | Called this in `FormioAppConfig` | Called this in the SDK |
| --- | --- | --- | --- |
| **Project URL** | The full URL of the one Form.io project this application reads and writes. The single value a user supplies. | `appUrl` | `Formio.setProjectUrl(...)` |
| **Base URL** | The deployment hosting that project. Normally derived from the Project URL rather than supplied. | `apiUrl` | `Formio.setBaseUrl(...)` |
`appUrl` is an alias for `projectUrl` and `apiUrl` is an alias for `baseUrl` — the same two values under different names, never a third and fourth value. Getting that pairing backwards points the application at its deployment for project reads and at its project for platform reads, and both fail in ways that look like permission errors.
## Which path you are on
**If the Form.io MCP tools are callable by you — Path A.** The server already knows what this working directory resolves to, and its answer is what every tool call will target, so asking it keeps the generated application and the tooling on the same project.
**If they are not — Path B.** Ask the user. **Do not install the MCP server to learn these two values**, and do not hand off to `formio-mcp-setup` for them: nothing on this page reads from or writes to a deployment, so a server would be installed to answer two questions the user can answer directly. Install it when something actually needs a tool call — an import, a form write, a role change.
Both paths apply the same rules, which are below and are the same rules the server itself applies.
## Path A — ask the server
Call `project_get` without `cwd` — the server takes the directory from the client's workspace root — and read `cwdSource` before `status`. When `cwdSource` is `server` or `claude-project-dir`, the answer is about a guessed directory — the MCP server's own, fixed at spawn, or a launch default — that may be mapped to a different project, so call `project_get` again with `cwd` set to the user's current working directory and keep passing that `cwd` on the calls after it. Otherwise pass `cwd` only to target another directory; a refusal listing several workspace roots is answered the same way, with `cwd` set to the one the user is working in. Then branch on `status`:
- **`ok`** — both values are in the report. Use them exactly as reported. Do not ask the user to confirm them.
- **`not-configured`** — nothing is recorded for this directory. Ask the user for the Project URL (one question — see the rules below), record it by calling `project_set` with that `projectUrl` and the same `cwd`, if the `project_get` call passed one, then call `project_get` again. If that Project URL carries no path on the user's own domain it names no deployment, so the call is refused and names the Base URL it still needs: ask for that one value and repeat the call with both.
- **`base-url-unresolved`** — the project is recorded and its deployment could not be derived. Ask the user for the Base URL alone, then make the `project_set` call the report names, and call `project_get` again. Do not re-ask the user for the Project URL: the report named it, and the call it prints carries it for you.
If the call fails outright instead of returning a status, relay the error and stop; do not fall through to Path B. A recorded configuration that cannot be read is not an absent one, and interviewing around it writes a second answer that the broken record still shadows.
**A project and its deployment are recorded together, in one record.** That is why the report names the remedy rather than leaving you to compose one: a deployment goes beside the project it serves, so what records it depends on which record holds that project — a `project_set` update for this directory's own mapping, an edit adding `"baseUrl"` to a committed `formio.json` (hand-authored and versioned with the code; the server reads that file and never writes it), or, for a project that comes only from the environment, a new pair in the mapping, which then governs. Never record a deployment in one record while its project sits in another; nothing in such a record says which project the deployment serves.
## Path B — ask the user
Ask for the **Project URL** first, and alone. Then derive the Base URL from it, and ask for that only in the one shape where it cannot be derived. Two questions is the worst case; one is the common one.
Nothing is recorded on this path — there is no server to record it in — so the values live only in what you write into the application. If the user later installs the MCP server, offer once to record the same Project URL with `project_set` so the tooling resolves what the application already ships with.
## What a Project URL is
The full URL of one Form.io project. It has three shapes, and which one applies depends on the deployment:
- **Form.io hosted cloud** — the project's name as a sub-domain of `form.io`. A project named `examples` is `https://examples.form.io`.
- **Customer-hosted, sub-directory routing** — a path under the deployment: `https://forms.mysite.com/myproject`.
- **Customer-hosted, sub-domain routing** — a sibling sub-domain of the customer's own domain: `https://myproject.mysite.com`.
Rules that hold on both paths:
- **Never build a Project URL by appending a project name to a deployment URL.** In the sub-domain shape the two hosts differ by design, so neither can be built from the other.
- A `*.form.io` host is never a Base URL, and `https://api.form.io/<project>` is not a hosted Project URL.
- Strip a trailing slash before using or recording the value.
## Deriving the Base URL
| Project URL shape | Base URL |
| --- | --- |
| `https://examples.form.io` (any `form.io` host) | `https://api.form.io` |
| `https://forms.mysite.com/myproject` (sub-directory) | the project URL minus its final path segment — `https://forms.mysite.com` |
| `https://forms.mysite.com/one/two` (sub-directory, deployment mounted at a sub-path) | the same rule, one segment up — `https://forms.mysite.com/one` |
| `https://myproject.mysite.com` (path-less, customer domain) | **cannot be derived** — ask for it |
The rule for a project URL with a path is always its **parent path**, never its origin — the third row is what makes the difference visible, and a deployment mounted at a sub-path is where taking the origin instead points the portal login at a host root that serves nothing.
The last row is the only case that needs a second question. That shape names no deployment anywhere in it: the deployment is a sibling sub-domain, and nothing in the project URL says which. Do not answer it with `https://api.form.io` — that value is certainly wrong for a project that is not on a `form.io` host, and it is the guess this table exists to prevent.
The first row is enforced, not merely derived: a `*.form.io` project recorded against any other deployment is refused. One deployment is indistinguishable from that mistake — an internal, non-SaaS deployment served from a `*.form.io` domain — and its escape hatch is a flag on the shell command, not on any tool you hold: the USER runs `npx -y @formio/mcp@1.0.1 project set --force --project-url "<project url>" --base-url "<base url>" --cwd "$(pwd)"` themselves, and every later call then resolves that pair. Relay it only when the user says their `*.form.io` project is served by their own deployment; never offer it to make a refusal go away, and never pass a value the user has not stated. A pair recorded that way survives an ordinary `project_set` call that re-states it, and the user clears it with `npx -y @formio/mcp@1.0.1 project set --reset --cwd "$(pwd)"` — the report says so wherever it reports a forced pair.
Never invent a Base URL, never reuse one from another project or an earlier session, and **never edit `~/.formio/projects.json`** by any means — its shape, its `0600` mode, and its merge rules belong to the server, and `project_set` is how you reach them.
## Before you write either value into a file
State both values in one line and what you are about to write them into, so a wrong target is caught before it ships in the application's own source. A hardcoded example host — `https://examples.form.io` from this page included — points the built application at a deployment nobody manages.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |