AI Agent Integration (MCP)¶

Validibot supports the Model Context Protocol (MCP), an open protocol that lets compatible AI assistants use external tools. When an agent connects to your self-hosted Validibot MCP server, it can discover authorised workflows, validate files, and retrieve structured findings.

Your operator provides the URL¶

There is no shared public Validibot MCP endpoint. Your organisation runs its own endpoint, normally on a separate origin from the web application. This guide uses the following example:

https://mcp.validibot.example/mcp

Replace that host with the MCP URL supplied by your Validibot operator. Never send your API token or validation files to validibot.com; it is the product website, not a validation service.

Connect with OAuth 2.1¶

OAuth is the recommended path for interactive clients. The client opens your self-hosted Validibot sign-in page, you authenticate normally, and the client receives a token scoped to the MCP surface. You do not copy an API token into a configuration file.

The exact labels vary, but the setup is generally:

1. Open your client's MCP or connector settings.
2. Add a remote MCP server.
3. Enter https://mcp.validibot.example/mcp.
4. Choose OAuth if the client asks for an authentication method.
5. Complete sign-in in the browser window.

For example:

• Claude Desktop — Settings → Connectors → Add custom connector.
• Claude Code — use claude mcp add, enter the URL, then complete browser sign-in.
• Cursor — Settings → MCP → Add Server, enter the URL, and select OAuth.

MCP clients discover the authorization details from the server's protected resource metadata:

https://mcp.validibot.example/.well-known/oauth-protected-resource/mcp

Connect with a bearer token¶

For a client without OAuth support, the operator may allow a standard Validibot bearer API token.

Create a dedicated token by following the Authentication guide. Use a separate automation identity with only the permissions the agent needs, and store the token in a secrets manager or the client's protected credential store.

A typical remote-server configuration looks like this:

{
  "mcpServers": {
    "validibot": {
      "url": "https://mcp.validibot.example/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_TOKEN"
      }
    }
  }
}

Do not commit this configuration with a real token in it.

Available tools¶

The MCP server exposes five task-oriented tools:

A well-behaved agent normally:

1. calls list_workflows instead of guessing a workflow reference;
2. calls get_workflow_details and checks the accepted file types;
3. calls validate_file with the candidate artifact;
4. calls wait_for_run or get_run_status;
5. reports the result and uses individual findings to repair the candidate.

See Validate AI-generated data for a bounded validation-and-repair pattern.

Example prompts¶

Discovery

• "What validation workflows can I use?"
• "Show me the required file types and checks for the energy-model workflow."
• "Which workflow should validate this JSON configuration?"

Validation

• "Validate this file with the workflow named configuration-contract."
• "Check this generated RDF graph against our ASHRAE 223 workflow."
• "Run the building model and tell me whether every required assertion passed."

Repair

• "List each error with its data path, then propose the smallest correction."
• "Fix only the fields named by the validation findings and validate again."
• "Stop after two failed repair attempts and show me the unresolved findings."

Access controls¶

MCP does not make every workflow public. A workflow appears to the agent only when all of these are true:

• the authenticated user can access it;
• the organisation permits MCP access; and
• the workflow explicitly opts into MCP access.

An imported workflow starts with external access disabled. An administrator or authorised workflow owner must deliberately enable it. This prevents importing a workflow from silently exposing it to connected agents.

MCP tokens preserve the user's existing permissions. The MCP surface cannot grant itself a broader role, enable agent access on a workflow, or bypass the workflow's accepted file types and validation rules.

What happens to a run¶

A run launched through MCP uses the same workflow engine as a run launched in the web interface or REST API:

• it appears in the deployment's run history with an agent source;
• it uses the selected workflow version and validators;
• it produces the same findings, outputs, artifacts, and evidence;
• it remains subject to the deployment's concurrency and rate limits.

Capacity and retention are controlled by the operator's infrastructure and configuration; there is no per-run Validibot service quota.

How OAuth works¶

When OAuth is configured, the connection follows standard discovery and token flows:

1. The MCP client reads RFC 9728 protected-resource metadata from the MCP origin.
2. The client dynamically registers when it supports Dynamic Client Registration.
3. The MCP server proxies authorization to the self-hosted Validibot identity provider.
4. The user signs in and approves access.
5. The client receives a token scoped to validibot:mcp.
6. The client refreshes the token when needed.

The MCP service then calls the Validibot application through a private helper API while forwarding the authenticated user's identity. That helper API is not part of the user-facing REST schema and must not be called directly by agents.

Operator setup¶

Self-hosted operators enable the MCP service in the production build settings:

ENABLE_MCP_SERVER=true
VALIDIBOT_MCP_BASE_URL=https://mcp.validibot.example

The MCP origin must be routed to the MCP container, while the main Validibot origin continues to route to the web container. Run the normal self-hosted deployment and diagnostic commands after changing the configuration.

For the complete environment, reverse-proxy, OAuth-client, and verification steps, see the MCP developer/operator documentation and post-deployment verification.

Troubleshooting¶

The client cannot discover OAuth metadata

Open the protected-resource metadata URL in a browser or with curl. Confirm that the reverse proxy sends /.well-known/ requests to the MCP container and that VALIDIBOT_MCP_BASE_URL exactly matches the public origin.

Mismatching redirect URI

The OAuth client's registered callback does not match the MCP public URL. Confirm VALIDIBOT_MCP_BASE_URL, then re-run the deployment's OIDC client setup command.

Missing or invalid Authorization header

For bearer-token access, confirm the header starts with Bearer and that the token is active. For OAuth, remove and re-add the connector so the client starts a fresh authorization flow.

This workflow does not allow agent access

The user may be able to see the workflow in the web interface while MCP access remains disabled. Ask an organisation administrator to review the organisation and workflow MCP settings.

Workflow not found

Call list_workflows first. Do not guess an organisation slug, workflow slug, or internal database identifier.

Security guidance¶

• Use HTTPS for both the Validibot application and MCP origins.
• Prefer OAuth for interactive clients and dedicated bearer tokens for unattended automation.
• Give automation identities the minimum role they need.
• Enable MCP only for workflows intended for agent use.
• Keep submitted content and findings within approved model-provider and data-handling boundaries.
• Set a bounded repair-attempt count so an agent cannot create an unlimited validation loop.
• Report the workflow reference and run reference with every result.
• Treat a pass as evidence for the configured checks, not proof of untested claims.