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 browse your test catalog, start tests and batches, and report on what passed or failed. Recording new tests through the MCP server is not yet possible, but will be soon.

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, list_labels
Tests	list_tests, run_test
Test runs	list_test_runs, get_test_run, cancel_test_run
Batches	list_batches, get_batch, trigger_batch, run_batch
Batch executions	list_batch_executions, get_batch_execution, cancel_batch_execution

Runs are asynchronous. After starting a test or batch, the assistant polls the matching get_* tool until the run reaches a terminal status such as Passed, Failed, or Stopped.

Things to try

• "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.

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.