AI Agent Integration (MCP)¶

Validibot supports the Model Context Protocol (MCP), an open standard that lets AI assistants like Claude, Cursor, Windsurf, Continue, Zed, and other LLM-powered tools interact with external services. When connected via MCP, your AI assistant can discover your workflows, validate files, and report results conversationally.

Two ways to authenticate¶

Validibot's MCP server supports two authentication paths. Pick the one your client supports best:

OAuth 2.1 (recommended)¶

Most modern MCP clients — Claude Desktop, Claude Code, Cursor, Windsurf, Continue, Zed — support OAuth 2.1 with Dynamic Client Registration. When you add Validibot as a connector, the client opens your browser, you sign in to Validibot normally, and the client stores the resulting access token. No API token to create, no config file to edit, and revoking access is a single click in your Validibot profile.

How to connect:

The exact UI varies by client, but the shape is always the same — add an MCP connector and point it at:

https://mcp.validibot.com/mcp/

Examples:

• Claude Desktop — Settings → Connectors → Add custom connector → paste the URL → click Connect → sign in to Validibot in the browser window that opens
• Claude Code — claude mcp add in the terminal, URL https://mcp.validibot.com/mcp/, then complete the browser sign-in
• Cursor — Settings → MCP → Add Server → URL https://mcp.validibot.com/mcp/ → select "OAuth" authentication

Once connected, your AI assistant can use any of the tools listed below.

Legacy API token (fallback)¶

For clients that don't yet support OAuth Dynamic Client Registration, or for scripting scenarios where you want a long-lived token, Validibot still accepts a standard bearer token in the Authorization header.

1. Create an API token. Follow the Authentication guide to create an API token from your profile settings. We recommend creating a dedicated token for MCP use so you can revoke it independently.

2. Configure your MCP client with the token. Most clients have a "headers" or "custom auth" field.

Claude Desktop — edit claude_desktop_config.json:

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

On macOS, this file is at ~/Library/Application Support/Claude/claude_desktop_config.json.

Cursor (legacy) — add an MCP server in Settings → MCP:

• Name: Validibot
• URL: https://mcp.validibot.com/mcp/
• Headers: Authorization: Bearer YOUR_API_TOKEN

Start validating¶

Ask your AI assistant to validate a file:

"Validate this IDF file against my ASHRAE 90.1 workflow"

"List my available validation workflows"

"Check if this JSON file passes the energy model schema"

The assistant will use Validibot's MCP tools to find the right workflow, submit the file, and report the results.

Available Tools¶

Your AI assistant has access to five tools:

A typical conversation flow:

1. The assistant calls list_workflows to see what's available
2. It calls get_workflow_details on the relevant workflow to check file type requirements
3. It calls validate_file with your file content
4. It calls wait_for_run to get the results
5. It summarises the findings for you

How it works¶

The OAuth 2.1 flow¶

When you add Validibot as an OAuth connector, here's what happens under the hood:

1. Discovery. Your MCP client asks https://mcp.validibot.com/.well-known/oauth-protected-resource/mcp for the authorization server details. Validibot's MCP server responds with a standards-compliant RFC 9728 metadata document pointing at its OAuth endpoints.
2. Dynamic Client Registration. The client POSTs to /register to get a fresh OAuth client ID and secret — unique to this client install. You never copy a client secret yourself.
3. Authorize. The client opens your browser to /authorize, which proxies to Validibot's OIDC provider at app.validibot.com/identity/o/authorize. You see Validibot's normal sign-in (and MFA, if enabled).
4. Token exchange. After you sign in, the authorization code is exchanged for an access token. The token is scoped to validibot:mcp — it can do everything you can do via the MCP tools, nothing else.
5. Request. Every subsequent tool call includes the access token. When it expires, your client automatically refreshes it.

You can revoke access at any time from your Validibot profile settings under "Connected applications." Revocation invalidates the access token immediately; the client will show a re-authenticate prompt the next time you use it.

Data path¶

Regardless of which auth path you use, every validation run created through MCP is identical to a run you'd create through the web interface or CLI:

• Runs appear in your dashboard with source "AI Agent"
• Runs consume your plan quota (same as web or CLI runs)
• Findings, results, and artifacts are all accessible normally
• Your existing workflows work without any changes

Example Prompts¶

Discovery:

• "What validation workflows do I have in my organisation?"
• "Show me the details of the energy-model-check workflow"
• "What file types does the ASHRAE 90.1 workflow accept?"

Validation:

• "Validate this IDF file against ASHRAE 90.1"
• "Check if my building model passes the energy code requirements"
• "Run the JSON schema validation on this configuration file"

Results:

• "What were the findings from my last validation?"
• "Did the validation pass or fail?"
• "Explain the error about missing heating setpoint"

Remediation:

• "Fix the issues found in the validation and show me the corrected file"
• "What changes would make this model pass the ASHRAE 90.1 check?"

Billing¶

MCP runs are billed exactly like web or CLI runs. Each validate_file call consumes one basic launch from your plan quota. There are no additional charges for using MCP.

You can see a breakdown of runs by source (Web, API, CLI, AI Agent) on your Billing & Usage dashboard.

Troubleshooting¶

"Connection issue — server configuration issue" (OAuth path)

If the connector page in Claude Desktop or Claude Code shows this error, the client has cached a previous failed state. Remove the connector entirely (not just disconnect), wait a minute or two, then add it again. A fresh add forces a new OAuth dance with clean state.

"Mismatching redirect URI" (OAuth path)

The MCP server's registered callback URL doesn't match what the OAuth authorization server expects. For cloud customers this should never happen — contact support with your reference ID. For self-hosted Pro operators, re-run ensure_oidc_clients after setting VALIDIBOT_MCP_BASE_URL in your Django settings.

"Missing or invalid Authorization header" (API token path)

Your API token is not configured correctly. Check that the Authorization header in your MCP client config includes the Bearer prefix and that the token is valid.

"This workflow does not allow agent access"

The workflow has agent access disabled. This is the default for all workflows. The workflow author can enable agent access from the workflow settings page.

"Workflow not found"

Check that you're using the correct organisation slug and workflow slug. Ask your assistant to call list_workflows first to see what's available to your account.

Validation runs not appearing in dashboard

MCP runs may take a few seconds to appear. Refresh the page. If they still don't appear, check that your session (OAuth) or API token belongs to the correct organisation.

Security¶

• OAuth tokens never leave Validibot. They're stored in your MCP client locally; Anthropic / the client vendor never see them.
• API tokens are the same. Sent only to mcp.validibot.com — never shared with the AI assistant's provider.
• MCP sessions have the same permissions as your user account. MCP cannot do anything you can't do through the web interface.
• Revocation is one click. OAuth tokens are revoked from your profile's "Connected applications" page; API tokens are deleted from the same page.
• Scoped to validibot:mcp. OAuth tokens can call the MCP tool surface and nothing else — no access to billing endpoints, admin, or non-MCP APIs.