Formbox Docs

Connect AI Agents to Formbox Builder

Formbox exposes an MCP endpoint so external agents can work with Formbox Builder directly. To connect an agent, use the /sdc/mcp endpoint and send a bearer token in the Authorization header.

Endpoint

Formbox exposes one MCP endpoint:

<formbox-base-url>/sdc/mcp

Authentication

The authentication prerequisites are the same as for other Formbox MCP integrations: create a client, allow the required operations with an AccessPolicy, then request a bearer token.

1. Create a client

POST /Client
content-type: application/json

{
  "resourceType": "Client",
  "id": "formbox-mcp-client",
  "secret": "verysecret",
  "grant_types": ["client_credentials"]
}

2. Create an AccessPolicy

This policy allows only the Formbox MCP operations used by this endpoint.

POST /AccessPolicy
content-type: application/json

{
  "resourceType": "AccessPolicy",
  "id": "formbox-mcp-access",
  "engine": "matcho",
  "matcho": {
    "client": {
      "id": "formbox-mcp-client"
    },
    "operation": {
      "$one-of": [
        { "resourceType": "Operation", "id": "sdc-mcp" },
        { "resourceType": "Operation", "id": "sdc-mcp-stream" },
        { "resourceType": "Operation", "id": "sdc-mcp-delete" }
      ]
    }
  }
}

3. Get a token

POST /auth/token
content-type: application/json
accept: application/json

{
  "client_id": "formbox-mcp-client",
  "client_secret": "verysecret",
  "grant_type": "client_credentials"
}

Save the access_token from the response. You will use it as a bearer token when connecting your agent.

Connect an agent

Add the Formbox MCP server to your agent configuration and send the bearer token in the Authorization header.

Add this to ~/.codex/config.toml:

[mcp_servers.formbox]
url = "<formbox-base-url>/sdc/mcp"
http_headers = { Authorization = "Bearer <your-access-token>" }

Run:

claude mcp add --transport http --scope user \
  --header "Authorization: Bearer <your-access-token>" \
  formbox <formbox-base-url>/sdc/mcp

Add this to .cursor/mcp.json in your project root, or ~/.cursor/mcp.json for a global configuration:

{
  "mcpServers": {
    "formbox": {
      "url": "<formbox-base-url>/sdc/mcp",
      "headers": {
        "Authorization": "Bearer <your-access-token>"
      }
    }
  }
}

Replace <formbox-base-url> with your Formbox base URL and <your-access-token> with the token returned by /auth/token.

Typical conversation

Once the MCP server is configured, the interaction usually looks like this:

1

User: "Connect to Formbox and show me opened questionnaires."
Agent: Lists the Builder tabs currently available for selection.

2

User: "Use PHQ-9 draft."
Agent: Requests access to that Builder tab and asks for approval in the browser.

3

User approves the consent prompt in the browser.
Agent receives the approval result, binds to the selected Builder tab, and is ready to work with that questionnaire.

4

User: "Add the remaining PHQ-9 questions, reuse the same answer options, and add a calculated total score at the end."
Agent: Updates the questionnaire structure in the selected Builder tab.

5

User: "Make all PHQ-9 questions required and verify the calculation."
Agent: Applies the validation changes and checks that the calculation works.

After the session is selected, the agent works with the same live Builder tab you see in the browser, so you can watch the changes in real time and continue refining the questionnaire through the conversation.

Last updated: