Connect an AI assistant (MCP)

AIVA exposes an MCP server, so an AI assistant can work with your AIVA workspace directly — no scripting and no API glue. Any MCP-compatible client works; the ecosystem is large and growing, and AIVA implements the standard rather than integrating with particular products.

Once connected, your assistant can record new tests in a real browser, browse your test catalog, start tests and batches, and report on what passed or failed. Describe the user flow you want covered and the assistant records it step by step while you watch. The result is an ordinary AIVA test that you can review, run, and heal in AIVA like any other.

Server URL

https://api.aiva.works/mcp

The transport is Streamable HTTP, and the server authenticates with OAuth 2.1 — your client opens a browser window and you sign in with your normal AIVA account. There is no API key to create or paste, and the assistant only ever sees what your AIVA account can already reach.

Set it up

Point your client at the server URL above as a remote (Streamable HTTP) server. That is the whole configuration — clients supporting OAuth 2.1 with dynamic client registration handle sign-in themselves, and nothing else needs setting.

Where you paste it differs by client. These are a starting point, not the full list of what works — menus move, so follow your client's own documentation if a path below no longer matches.

Chat assistants

Nothing to install or run — each of these keeps a list of connectors you paste the server URL into.

Claude — Settings → Connectors → Add custom connector, then paste the URL. Available on every plan.

ChatGPT — custom MCP connectors sit behind Developer mode, on the paid plans (Plus, Pro, Business, Enterprise, Edu). Turn it on in Settings → Apps → Advanced settings, then add the connector. OpenAI documents the switch in Developer mode and MCP apps in ChatGPT. Do not be put off by the name — it is a settings toggle, not a coding step. Do read OpenAI's warning there about connecting servers you do not trust; it applies to any MCP server, not just this one.

Grok — grok.com/connectors → New Connector → Custom, then paste the URL. On Business and Enterprise a team admin provisions connectors first.

Perplexity and Mistral Le Chat also connect to remote MCP servers. The consumer Google Gemini and Microsoft Copilot apps do not offer custom MCP connectors yet.

Developer tools

Claude Code

claude mcp add --transport http aiva https://api.aiva.works/mcp

Cursor — Settings → MCP → Add new global MCP server:

{
  "mcpServers": {
    "aiva": {
      "url": "https://api.aiva.works/mcp"
    }
  }
}

VS Code

code --add-mcp '{"name":"aiva","type":"http","url":"https://api.aiva.works/mcp"}'

What your assistant can do

Ask in plain language — the assistant picks the tool.

Area	Tools
Workspace	list_tenants, list_gateways, setup_gateway, list_labels
Tests	list_tests, run_test, delete_test
Test runs	list_test_runs, get_test_run, cancel_test_run
Batches	list_batches, get_batch, trigger_batch, run_batch, delete_batch
Batch executions	list_batch_executions, get_batch_execution, cancel_batch_execution
Recording	get_recording_guidelines, start_recording, get_recording, finish_recording, get_recording_status, cancel_recording
Recording — the page	get_hierarchy, get_image, click, type_text, press_keys, scroll, move_mouse, clear_text, navigate, browser_navigate, delay
Recording — checks	verify_text, assert_image
Recording — steps	edit_step, delete_step
Recording — modules and files	list_modules, add_module_step, reserve_upload, confirm_upload

Runs are asynchronous. After starting a test or batch, the assistant checks its status until the run reaches a terminal status such as Passed, Failed, or Stopped.

Things to try

• "Record a test: open the shop, search for a laptop, and check the results mention it."
• "Record a checkout test starting from the Staging Login module."
• "Show me the steps you have recorded so far, and drop the last one."
• "Run the Basic test and tell me when it finishes."
• "List the tests I can run."
• "Which tests failed in the last batch execution, and on which step?"
• "Start the smoke-test batch and summarise the results."

Troubleshooting

The client never finishes signing in. Check that your browser completed the AIVA sign-in and returned to the client. Some clients need the callback port left free on first connect.

Tools return nothing. The assistant only sees what your AIVA account can reach. If you have more than one workspace, check it picked the one you expected.

A recording seems to have stalled. Open the recording link and look at the browser. A page waiting for a file, or a module that failed to replay, stops the recording until it is dealt with — the assistant will say which it is and ask how to continue.

The client cannot reach the server. The endpoint is plain HTTPS on port 443. If you are behind a corporate proxy that inspects traffic, allow https://api.aiva.works.

note

Tests that run against apps on localhost or a private network still need a gateway. Ask your assistant to list_gateways to see which ones are available, and tell it which to use before it starts recording.