AI Agents (MCP)

Agora includes a built-in Model Context Protocol (MCP) server. It lets AI coding assistants such as Claude Code, Cursor, GitHub Copilot, Windsurf, Codex and Gemini CLI run Agora accessibility checks while they build and fix your UI.

A typical conversation with your assistant looks like this:

Scan localhost:3000/checkout with Agora and fix the accessibility issues it finds.

The assistant calls Agora, gets back a detailed report and edits your code. It can then run the scan again to confirm the fixes.

Agora MCP or QualiBooth MCP?

This page covers the local MCP server built into the Agora desktop app. It scans pages in Agora's own browser, including local development servers. To manage portal organizations, projects and scheduled scans from an AI assistant, use the QualiBooth MCP server instead.

How It Works

• The server starts automatically with Agora and listens on http://127.0.0.1:24672/mcp.
• It only accepts connections from your own computer. Requests addressed to other hosts, or sent by web pages from other origins, are rejected.
• No API key or token is needed. Your assistant uses the account you are signed in with in Agora.
• Scans run in Agora's own headless Chrome, using the same axe-core engine and rules as the rest of the app.
• Up to two scans run at the same time. Further requests wait for a free slot.

Requirements

• Agora must be running.
• You must be signed in to Agora with an account that has an Agora desktop license.
• Agora must have finished downloading its scanning browser (this happens on first launch).
• validate_attributes and simulate_screen_reader use QualiBooth's AI, like the Screen Reader Simulation and Accessibility Attributes features in the app.

Setting Up Your Assistant

Click the AI Agents icon (the robot) in the top bar of Agora. The page shows the server status and step-by-step setup instructions for each supported assistant, with commands and configuration you can copy. Cursor and VS Code also offer one-click install buttons.

The configurations below use the default port. If you change the port, update the URL to match.

Claude Code

# Add Agora for all your projects
claude mcp add --transport http --scope user agora http://127.0.0.1:24672/mcp

Claude Code (.mcp.json)

{
  "mcpServers": {
    "agora": {
      "type": "http",
      "url": "http://127.0.0.1:24672/mcp"
    }
  }
}

Cursor (mcp.json)

{
  "mcpServers": {
    "agora": {
      "url": "http://127.0.0.1:24672/mcp"
    }
  }
}

VS Code (.vscode/mcp.json)

{
  "servers": {
    "agora": {
      "type": "http",
      "url": "http://127.0.0.1:24672/mcp"
    }
  }
}

Windsurf (mcp_config.json)

{
  "mcpServers": {
    "agora": {
      "serverUrl": "http://127.0.0.1:24672/mcp"
    }
  }
}

Claude Desktop

{
  "mcpServers": {
    "agora": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://127.0.0.1:24672/mcp"]
    }
  }
}

Codex CLI (config.toml)

[mcp_servers.agora]
url = "http://127.0.0.1:24672/mcp"

Gemini CLI

gemini mcp add --transport http --scope user agora http://127.0.0.1:24672/mcp

Client Notes

Client	Where the configuration goes
Claude Code	Run the command once in any terminal, or commit .mcp.json to the root of your repository to share Agora with your team. Run /mcp inside Claude Code to check the connection.
Cursor	~/.cursor/mcp.json for all projects, or .cursor/mcp.json in a project. Then make sure Agora is switched on under Cursor Settings → MCP & Integrations.
VS Code	Run code --add-mcp '{"name":"agora","type":"http","url":"http://127.0.0.1:24672/mcp"}', or create .vscode/mcp.json in your project. Switch Copilot Chat to Agent mode; Agora's tools appear in the tools picker.
Windsurf	Windsurf Settings → Cascade → MCP Servers → View raw config, or edit ~/.codeium/windsurf/mcp_config.json. Press refresh in the MCP Servers panel afterwards.
Claude Desktop	Settings → Developer → Edit Config. Claude Desktop connects to local servers through the mcp-remote bridge, so Node.js must be installed. Quit and reopen Claude after saving.
Codex CLI	Append to ~/.codex/config.toml. Run /mcp inside Codex to see Agora and its tools.
Gemini CLI	Run the command, or add {"mcpServers": {"agora": {"httpUrl": "http://127.0.0.1:24672/mcp"}}} to ~/.gemini/settings.json.

On Windows, ~ stands for %USERPROFILE%.

Other Clients

Any client that supports the Streamable HTTP transport can connect to http://127.0.0.1:24672/mcp directly. Clients that only support stdio servers can connect through mcp-remote (requires Node.js):

npx -y mcp-remote http://127.0.0.1:24672/mcp

Example Prompts

• Scan localhost:3000/checkout with Agora and fix the accessibility issues it finds.
• Use Agora to check the signup form (#signup-form) on localhost:3000 on desktop and mobile.
• Render the Button component's HTML and audit it with Agora's scan_html tool.
• Ask Agora to validate the alt texts and ARIA labels on localhost:3000 and improve the flagged ones.
• Use Agora's screen reader simulation on the navbar component and fix anything that sounds confusing.
• Re-run the Agora scan to verify the fixes.

Available Tools

Tool	What it does
scan_url	Runs an axe-core audit on a served page.
scan_html	Runs an axe-core audit on raw HTML, without a server.
validate_attributes	Uses AI to check whether accessible names, labels and descriptions make sense.
simulate_screen_reader	Lists what a screen reader announces, with an AI review.

scan_url

Audits any page Agora's browser can reach: local development servers (localhost:3000/page), staging and production sites, or file:// paths. If you leave out the scheme, local and private-network addresses use http:// and everything else uses https://.

Option	Description
url	The page to scan (required).
selector	CSS selector that limits the audit to one component, e.g. #signup-form.
waitForSelector	Wait up to 15 seconds for an element to appear before scanning (client-rendered pages).
scrollPage	Scroll through the page first to load lazy content. Slower; off by default.
viewports	desktop (default) and/or mobile. Add mobile to catch responsive issues.
standard	wcag21aa, wcag22aa or wcag22aaa. Defaults to your scanning settings.
includeScreenshot	Also return a screenshot of the scanned area for each viewport.
maxElementsPerIssue	How many affected elements to list per issue, from 1 to 200 (default 25).
format	markdown (default) or json.

Basic auth credentials saved in Agora are used automatically for matching hosts.

scan_html

Audits raw HTML without running a server. Agora renders the markup in memory and scans it the same way as a URL.

• Components: snippets without <html> or <body> are wrapped in a minimal document, and page-level rules (document title, language, landmarks, page heading, skip links) are skipped.
• Full documents: HTML that contains <!doctype>, <html> or <body> is scanned with every rule.
• Styles and assets: pass baseUrl (e.g. http://localhost:3000/) so relative stylesheets, scripts and images load from your dev server. Without styles, color contrast can't be evaluated accurately.

Option	Description
html	The markup to scan (required).
baseUrl	Where the HTML is treated as being served from.
mode	auto (default), component or page. auto picks page when the HTML contains <!doctype>, <html> or <body>.

scan_html also accepts the selector, waitForSelector, viewports, standard, includeScreenshot, maxElementsPerIssue and format options of scan_url.

validate_attributes

The MCP version of attribute validation. Agora collects the text that assistive technology uses for each element (aria-label, aria-labelledby, aria-describedby, alt, title, form labels, link and button text, SVG titles and table headers). QualiBooth's AI then flags values that don't meaningfully describe their element, such as "image", "click here", file names or labels in the wrong language.

scan_url and scan_html find missing names. This tool checks whether the names that are there make sense.

For each flagged value the report lists the attribute, the element's CSS selector and HTML, the current value and why it was flagged.

simulate_screen_reader

The MCP version of the screen reader simulation. Agora reads the content through Chrome's accessibility tree and returns the announcements a screen reader makes, in order: headings, landmarks, links, buttons, form fields, images and tables, with what is spoken and the element's selector. By default QualiBooth's AI also reviews the reading order, the heading structure and any unclear or missing announcements.

Option	Description
analyze	Include the AI review (default true). Set to false to get only the announcements, which is faster.
maxAnnouncements	How many announcements to list in the report, from 1 to 2000 (default 300). The AI review always considers all of them.

Options for validate_attributes and simulate_screen_reader

Both tools check either a served page or raw HTML. Pass exactly one of url and html.

Option	Description
url	The page to check, like in scan_url.
html	Markup to check instead of a URL, like in scan_html. Snippets are wrapped in a minimal document.
baseUrl	Only with html: where the HTML is served from, so relative CSS, scripts and images load.
mode	Only with html: auto (default), component or page.
selector	CSS selector that limits the check to one component, e.g. #signup-form.
waitForSelector	Wait for an element to appear before checking (client-rendered pages).
scrollPage	Scroll through the page first to load lazy content.
viewport	desktop (default) or mobile.
format	markdown (default) or json.

Privacy

The AI analysis sends the collected names, labels and announcements (not the full page) to the QualiBooth API, the same as in the app. scan_url and scan_html run entirely on your computer.

What the Scan Report Contains

Every scan_url and scan_html scan returns:

• An accessibility score from 0 to 100 and a count of issues by impact.
• Each violated rule with its impact, the WCAG success criteria it relates to and a link to detailed guidance.
• For each failing element: its CSS selector, an HTML snippet and a concrete "How to fix" hint, such as the measured and required contrast ratio.
• The viewports where each issue appears, when you scan more than one.

Automated checks cover only part of WCAG. Use validate_attributes and simulate_screen_reader to review wording and reading order, and still test keyboard navigation and focus management manually.

Managing the Server

On the AI Agents page you can:

• Turn the server on or off. When it's off it stays off, including after restarting Agora, until you turn it back on.
• Restart the server.
• Change the port if 24672 is already used by another application. Remember to update the URL in your assistant's configuration afterwards.
• See connected assistants and the tools Agora offers them.
• See recent activity: scans and checks requested by assistants during the current session, with their duration, score and result.

The robot icon in the top bar shows a colored dot with the server state: green when running, orange while starting and red when there is an error.

Troubleshooting

The assistant says it can't connect. Make sure Agora is running and the server status shows Running. Open http://127.0.0.1:24672/ in a browser; it should answer with "status": "ok".

The status shows "Port … is already in use". Another application is using the port. Choose a different port on the AI Agents page and update your assistant's configuration.

"Agora is not signed in". Open Agora and sign in. Scans require an account with an Agora desktop license.

"The signed-in QualiBooth account does not have an Agora desktop license". Ask your organization administrator to assign you an Agora license in the QualiBooth Portal. See License Issues.

"Agora is still downloading its scanning browser". Open Agora and wait for the first-launch setup to finish, then try again.

"Could not connect to http://localhost:3000". Your development server isn't running, or it's listening on a different port.

"No element matches the selector …" or "Timed out … waiting for …". Check the selector against the rendered page. For client-rendered content, combine selector with waitForSelector.

Color contrast results look wrong for scan_html. The markup was scanned without its stylesheets. Pass baseUrl pointing to your dev server, or scan the served page with scan_url.