Set up the cloud MCP server – mabl help

With the mabl cloud MCP server, your AI client can author and execute tests, query results, analyze failures, and generate test-quality reports, all through conversational prompts.

Prerequisite

You need an AI client that supports MCP servers, such as Claude Code, Cursor, Windsurf, Gemini CLI, Claude Desktop, or Rovo.

Setup

The mabl cloud MCP server supports two authentication methods:

OAuth - connect the cloud MCP to your mabl user account, giving you access to any workspace your user belongs to. Uses your mabl login, so you'll occasionally need to re-authenticate, just like with the mabl app. If you're not sure which method to pick, start here.
API key - connect to the cloud MCP through a mabl API key. Access is scoped to the single workspace the key was generated in and persists until the key itself expires or is deleted. Best for agent-to-agent use cases.

The configurations in this article create an MCP server under the name "mabl". You can use a different name if needed. For example, if your organization uses strict security whitelists, corporate proxies, or internal IDE registries, you may need to update the name "mabl" to comply with your organization's whitelisting requirements. If in doubt, check with your internal IT or security team for specific MCP guidelines. Also note that not all clients use JSON configuration. Refer to your AI client’s documentation for specific instructions on adding remote MCP servers.

Config

Many AI clients use a JSON configuration file for MCP servers. Use the following config block:

{
  "mcpServers": {
    "mabl": {
      "url": "https://mcp.mabl.com/mcp",
      "type": "http"
    }
  }
}

Type string may vary

Some clients, such as Cursor and Windsurf, use "type": "streamable-http" instead of "type": "http". Check your client’s documentation for the expected type string.

For legacy MCP clients that require the dual-endpoint SSE pattern, use this configuration instead: "type": "sse" and "url": "https://mcp.mabl.com/sse".

In Claude Code, you can also run the following command in your terminal to set up the mabl MCP:

claude mcp add --transport http mabl https://mcp.mabl.com/mcp

This command registers the cloud MCP server for the current project only. To make mabl available across all your projects, add --scope user. To confirm the server is configured, run claude mcp list.

In Gemini CLI, the mabl MCP is available as an extension. Instead of editing a config file, you can install it with a single command:

gemini extensions install https://github.com/mablhq/mabl-mcp-server

The extension configures the cloud MCP server and adds a context file that gives your agent guidance on using the mabl tools. To confirm the extension is installed, run gemini extensions list.

After adding the server, complete authentication through a browser consent flow:

Client-initiated: Your client may recognize that you aren't logged in and provide a button or prompt to initiate the process.
User-initiated: If your agent doesn't automatically prompt you to authenticate, use a prompt like "Help me authenticate the mabl MCP" to initiate the process.

The cloud MCP will open a browser window to a consent page. Review the details and click Accept. At this point, if you aren't already logged into the mabl web app, you'll also need to sign in to mabl.

By default, the cloud MCP server connects to the primary workspace associated with your mabl user account. If you aren't sure what your default workspace is, ask your client:

“What is my default workspace?”

To list all available workspaces, ask:

“What workspaces do I have access to?”

To use the mabl cloud MCP tools in a non-primary workspace, provide the name of the workspace or workspace ID when you invoke tools. For example:

“Get my recently created tests from the mabl prod tests workspace.”

Config

API key setup authenticates your connection without a browser consent flow. Use the following config block, replacing YOUR_API_KEY_HERE with either an "Editor" or "Viewer" type mabl API key:

{
  "mcpServers": {
    "mabl": {
      "url": "https://mcp.mabl.com/mcp",
      "type": "http",
      "headers": {
        "x-api-key": "YOUR_API_KEY_HERE"
      }
    }
  }
}

Type string may vary

Some clients, such as Cursor and Windsurf, use "type": "streamable-http" instead of "type": "http". Check your client’s documentation for the expected type string.

For legacy MCP clients that require the dual-endpoint SSE pattern, use this configuration instead: "type": "sse" and "url": "https://mcp.mabl.com/sse".

In Claude Code, you can also run the following command in your terminal:

claude mcp add --transport http mabl https://mcp.mabl.com/mcp --header "x-api-key: YOUR_API_KEY_HERE"

In Gemini CLI, the mabl extension uses OAuth. To connect with an API key instead, add the server to your Gemini CLI settings manually, using httpUrl in place of url and a headers object for your key.

If your config file will be checked into version control or shared with others, reference the key from an environment variable instead of pasting it directly. For example, "x-api-key": "${MABL_API_KEY}".

An API key is scoped to the workspace it was generated in. Unlike OAuth, you can't switch workspaces when authenticated by API key. To work in a different workspace, generate a key there and update your config.

Config

Using the mabl MCP server in Claude Desktop requires an actively supported Node.js LTS version, currently version 22 or higher. To check if Node is installed and view the current version, open your terminal or command prompt and run node -v.

To add the mabl MCP server in Claude Desktop, open Claude Desktop Settings from your system’s menu bar: Claude > Settings…

Accessing settings in Claude

In the Settings window, click on the Developer tab. Click on Edit Config to open the configuration file for Claude Desktop. This action creates or opens the existing claude_desktop_config.json file. Depending on your OS, this file is located in one of the following locations:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Claude Desktop currently supports only stdio transport and does not natively connect to remote HTTP endpoints. To use the mabl cloud MCP on Claude Desktop, use a bridge like mcp-remote to translate between Claude's local stdio and our remote HTTP server. mcp-remote is a third-party open-source package that is not maintained by mabl.

For OAuth config, add the following to your Claude Desktop's MCP configuration:

"mcpServers": {
  "mabl": {
    "command": "npx",
    "args": [
      "-y",
      "mcp-remote",
      "https://mcp.mabl.com/mcp"
    ]
  }
}

For API key auth config, include your API key as a header. To use the following config block, replace YOUR_API_KEY_HERE with your editor or viewer mabl API key:

"mcpServers": {
  "mabl": {
    "command": "npx",
    "args": [
      "-y",
      "mcp-remote",
      "https://mcp.mabl.com/mcp",
      "--header",
      "x-api-key:YOUR_API_KEY_HERE"
    ]
  }
}

Start the server

To confirm the mabl cloud MCP is installed, quit and restart Claude Desktop. When you click on the settings icon at the bottom of the conversation input box, you should see available MCP tools.

Viewing mabl MCP tools in Claude Desktop

Next steps

mabl MCP overview - start here if you're new to MCPs.
mabl MCP tools and prompts - full reference of available tools and sample prompts.
How to interact with the mabl MCP - best practices for writing effective prompts.
Integrate the mabl MCP with Atlassian Rovo - create a custom Rovo Agent in Atlassian with access to mabl MCP tools.

Prerequisite

Setup

Config

Config

Config

Start the server

Next steps

Related articles