> For the complete documentation index, see [llms.txt](https://doc.orbeon.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://doc.orbeon.com/form-builder/mcp.md). # Form Builder MCP ## Availability [\[SINCE Orbeon Forms 2025.1.2\]](/release-notes/orbeon-forms-2025.1.2.md) This is an early access feature. We're actively working to improve it by creating more tools that expose additional Form Builder functionality to AI agents and by improving the documentation and ergonomics. We believe it is already very useful, which is why we want to make it available to you early. Please let us know if you have any feedback. Watch the video which shows Form Builder MCP support in the browser: {% embed url="" %} ## What it does The Form Builder MCP server makes Form Builder's features available to AI agents through the MCP (Model Context Protocol), which is a standard protocol supported by most AI agents. This allows AI agents to interact with Form Builder to: * create forms based on user instructions * modify existing forms based on user instructions * retrieve information about forms, such as their structure and metadata. Orbeon Forms provides both: * A Form Builder MCP Server; this is covered in the first section below. * Support for WebMCP in Form Builder loaded in your browser; this is covered in the second section below. ## MCP Server Using any MCP server (not just Orbeon Forms'), involves 3 parts, illustrated in the diagram below: * On the right, the MCP server itself. In our case, the MCP server is part of Orbeon Forms, which you already have. * On the left, an AI agent. This is software that you install on your own laptop or workstation. It provides the chat interface. * At the bottom, an AI model. Typically, the AI model runs in the cloud. Local models can also be used, but this isn't something we cover on this page.

AI agent connected to Form Builder MCP

To use the MCP server: 1. Follow the first section below, *Orbeon Forms*. 2. Then jump to the section that corresponds to your agent of choice (*Claude Code*, *Codex CLI*, *GitHub Copilot CLI*, or *Antigravity*). If you have an OpenRouter key or account, instead jump to the relevant *OpenRouter* section. 3. Finally, optionally set up a skill as mentioned in the *Skill* section. ### Orbeon Forms Set the following three properties in your `properties-local.xml`: 1. The first enables the MCP server (it is disabled by default). 2. The second sets the password used to sign the token. You need to set the value of this property to a secure password. Should you, in the future, want to revoke all tokens issued, simply change this password. 3. The third sets the token validity to one year (the duration is in minutes). ```xml ``` Once you have those properties in place, you can generate a token. Open any form in Form Builder and click on the key icon that shows at the top right of the page to reveal the token dialog. If you'd like your agent to be able to create and edit forms, in the dropdown choose "Read/Write", then click on the button to the right of the token to copy its value.

Creating an MCP token in Form Builder

Then continue in the below section that corresponds to your configuration. In what follows: * Replace `YOUR_TOKEN` with the value of the token you just copied in Form Builder. * If needed, change the `http://localhost:8080/orbeon/fr/mcp/builder` URL: * Keep the `/fr/mcp/builder` part, which is the path to the MCP server in Form Builder. * The domain, port, and prefix (here `/orbeon`) should be those of your Orbeon Forms instance. ### Claude Code Add the MCP server with: ``` claude mcp add orbeon http://localhost:8080/orbeon/fr/mcp/builder \ --scope user \ --transport http \ --header "Authorization: Bearer YOUR_TOKEN" ``` You can then run `claude mcp list` to check it was correctly added and that Claude is able to connect. ### Codex CLI Declare an `ORBEON_MCP_TOKEN` environment variable with the value of your token value (`YOUR_TOKEN`), then run: ``` codex mcp add orbeon \ --url http://localhost:8080/orbeon/fr/mcp/builder \ --bearer-token-env-var ORBEON_MCP_TOKEN ``` You can then run `codex mcp list` to check it was correctly added. ### ChatGPT for desktop 1. Declare an `ORBEON_MCP_TOKEN` environment variable with the value of your token value (`YOUR_TOKEN`). 2. In ChatGPT, under Settings → Plugins → Add → Add MCP server: * In *Name*, enter `orbeon-form-builder` * In *URL*, enter `http://localhost:8080/orbeon/fr/mcp/builder` * In *Bearer token env var*, enter `ORBEON_MCP_TOKEN` * Save ### GitHub Copilot CLI Add the MCP server with: ``` copilot mcp add orbeon \ --url http://localhost:8080/orbeon/fr/mcp/builder \ --type http \ --header "Authorization=Bearer YOUR_TOKEN" ``` ### Antigravity Whether you're using Antigravity 2.0 or Antigravity CLI, edit your `~/.gemini/config/mcp_config.json` to add the `orbeon` MCP server, for example: ```json { "mcpServers": { "orbeon": { "serverUrl": "http://localhost:8080/orbeon/fr/mcp/builder", "headers": { "Authorization": "Bearer YOUR_TOKEN" } } } } ``` ### OpenRouter You can use your OpenRouter API key with numerous agents: * OpenRouter provides good documentation on how to set up your OpenRouter API key with a number of different agents. For a full list, open their [Cookbook](https://openrouter.ai/docs/cookbook), and check the links in the left navigation under the heading *Working with Coding Agents*. * We have tested OpenRouter with *ChatGPT for desktop* and *Claude Code*, but other agents should work as well. * Regarding the *ChatGPT* vs. *Codex* naming, note that on July 9, 2026, OpenAI renamed the desktop app that used to be called *Codex* into *ChatGPT for desktop*, so, occasionally, you'll still see this app called *Codex*. In general the procedure is as follows: 1. Follow the steps in the OpenRouter documentation, for instance [Use Codex Desktop App with OpenRouter](https://openrouter.ai/docs/cookbook/coding-agents/codex-desktop) or [Use Claude Code with OpenRouter](https://openrouter.ai/docs/cookbook/coding-agents/claude-code-integration). 2. Set up the MCP server for your agent as described in the corresponding section above. 3. Run your agent. 4. Pick a [model](https://openrouter.ai/models). This is often done through a selector or using a slash command like `/model z-ai/glm-5.3`. 5. Tell the agent what you'd like it to do, for instance `Using Orbeon, create a new demo form with just a First name field`. 6. In your browser, load the Form Builder summary page, and check the form got created. ### Skill Optionally, you can provide your AI agent with a skill file. The latest version of the skill file can be found [in the Orbeon Forms GitHub repository here](https://github.com/orbeon/orbeon-forms/blob/master/.agents/skills/orbeon/SKILL.md). You place such a file in the appropriate location for your AI agent, for example: ``` .agents/skills/orbeon/SKILL.md ``` ## WebMCP

AI agent connected to Form Builder through WebMCP

As of Summer 2026, WebMCP is a nascent, but very promising standard. The idea is that users will load a web page that supports WebMCP in their browser, open their agent, and the agent will be able to use tools provided by that page. Gemini in Chrome would be a prime candidate to support this, and other vendors like Anthropic or OpenAI could provide similar support through a browser extension. We expect that this will provide a very seamless experience for users: * It doesn't require users to generate a token in Form Builder and set up their agent with that token. * Users can see changes made to the form in real time in the browser. They can also make their own changes, and use both the agent and the Form Builder UI in the same session to update a form. * In the future, when agents built in the browser, such as Gemini in Chrome, support WebMCP, users will be able to do all of the above directly from their browser, without even having to install an external agent. As of September 2026, the only agent to natively support WebMCP is ChatGPT for desktop, which we cover in the first section below. If you're using another agent and prefer not to switch, you can get it to use WebMCP through Chrome DevTools for agents, which we cover in the second section below. ### ChatGPT for desktop 1. In the ChatGPT desktop app, open a browser tab with ⌘+T on macOS or Ctrl+T on other operating systems. 2. Use the URL bar to navigate to your instance of Orbeon Forms. Create a new form or open an existing form in Form Builder. 3. Use the chat to have your agent perform operations on the form. ### Any agent, through Chrome DevTools for agents 1. In Chrome, open `chrome://flags/`, search for "MCP", enable both "WebMCP support in DevTools" and "WebMCP for testing", then restart the browser. 2. Set up your agent to add [Chrome DevTools for agents](https://github.com/ChromeDevTools/chrome-devtools-mcp). Make sure to include `--autoConnect` to connect to your running browser (for instance, with Claude Code, use `claude mcp add chrome-devtools -s user -- npx chrome-devtools-mcp@latest --autoConnect`). 3. In Chrome, open a form in Form Builder, and ask your agent "with Chrome DevTools, through WebMCP, give me a list of the controls in the form I have open in Form Builder". ## Usage patterns With MCP support, you can use your AI agent to interact with Form Builder in various ways using prompts such as: * Using Orbeon, create a new demo form for a personal collection of widgets. Split the form into sections, and use appropriate form controls. Then save and close the form. * Using Orbeon, edit form 33e71949140e1282b9428770176994bdb24c702a and modify the size of control widget-quantity to half its current width. * Using Orbeon, update form 33e71949140e1282b9428770176994bdb24c702a to make the type of the widget-quantity field a non-negative integer. The result of the first prompt might look like this: ![Example of a form created by an AI agent](https://4129616727-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LEkBiSDvlXs3VWiO0Zu%2Fuploads%2Fgit-blob-e5cff4bca1bd7a74fe3e55f0e372b68f302fac88%2Fmcp-widgets-form.webp?alt=media)