AI Agents

This guide explains how to connect your AI agents to the MCP server provided by Develocity. To enable the MCP server on your Develocity installation, see the Installation Manual. For the credentials the server accepts and how an administrator configures them, see Authentication.

Permissions

All MCP tools provided by Develocity require a credential whose Develocity user has the Access build data via the API and MCP permission. This permission is included in the default Developer role.

The Develocity Analytics tools additionally require access to build data across all projects, because Develocity Analytics data isn’t subject to project-level access control. This cross-project access is granted by either the Read access to all build data with or without an associated project or the Access all data with or without an associated project permission.

The Develocity MCP Server validates the credential and its permissions at the start of every request, including when listing the available tools. A request made without a valid credential, or with one whose user lacks the Access build data via the API and MCP permission, is rejected before any tool runs.

You can check your permissions by visiting the /settings/access page when logged in to Develocity.

For detailed instructions on generating access keys, see the Develocity API user manual.

MCP Client Configuration

Configure your AI agent with a single MCP server pointed at your Develocity instance with the path /mcp, for example, https://develocity.example.com/mcp.

The Develocity Analytics tools are available from that same /mcp endpoint, subject to the user’s permissions, whether your analytics source is Develocity Reporting via Athena Data Export or a connected Develocity Reporting Kit. No additional client configuration is required.

In the snippets below, replace <develocity-url> with your Develocity instance URL (for example, https://develocity.example.com).

If you previously configured a separate Reporting Kit MCP server at <reporting-kit-url>/drv-mcp, that endpoint is deprecated in Develocity 2026.3 and will be removed in a future release. During 2026.3 it forwards requests to the consolidated Develocity MCP Server, so existing clients keep working. Migrate those clients to <develocity-url>/mcp — a single server entry now serves both the Develocity tools and the Reporting Kit’s Analytics tools.

  • Claude Code CLI

  • GitHub Copilot (IntelliJ IDEs)

  • GitHub Copilot (Visual Studio Code)

  • Gemini CLI

  • Gemini in Android Studio

  • Claude Desktop (via npx mcp-remote)

Use the Claude Code CLI to add the MCP server (guide).

With OAuth sign-in

Claude Code uses a client ID you give it. If you give it none, it registers itself: it uses its client ID metadata document when your authorization server supports one, and falls back to dynamic client registration.

To let it register itself, add the server and sign in:

claude mcp add --transport http develocity --scope user <develocity-url>/mcp

Claude Code’s client ID metadata document sits at the fixed address https://claude.ai/oauth/claude-code-client-metadata. The CLI chooses it only when your authorization server advertises both client_id_metadata_document_supported and none in token_endpoint_auth_methods_supported.

To use a client your administrator pre-registered, name it instead:

claude mcp add --transport http develocity --scope user <develocity-url>/mcp \
  --client-id CLIENT_ID \
  --callback-port 8765

Add --client-secret as well if your administrator registered a confidential client; the CLI prompts for the secret rather than taking it on the command line.

The redirect URIs Claude Code publishes carry no port, http://localhost/callback and http://127.0.0.1/callback, which is the loopback pattern for native applications described in RFC 8252. An authorization server that does not accept a port-less loopback URI needs a fixed port: --callback-port sets one, and the redirect URI to register is then http://localhost:8765/callback.

Sign in with the /mcp command from a Claude Code session, or with claude mcp login, which must run in an interactive terminal. Either opens a browser and captures the redirect for you, and claude mcp list then reports the server as connected.

With an access key

claude mcp add --transport http develocity --scope user <develocity-url>/mcp --header "Authorization: Bearer <Develocity Access Key>"

Use the GitHub Copilot plugin for IntelliJ IDEs to connect to the MCP server (guide).

With OAuth sign-in

Configure the server without an Authorization header:

mcp.json
{
  "servers": {
    "develocity": {
      "type": "http",
      "url": "<develocity-url>/mcp"
    }
  }
}

Start the server from the tools dialog in Copilot Chat.

The plugin attempts dynamic client registration. If your authorization server does not offer it, the plugin asks for the client ID your administrator registered and names the redirect URIs that client needs. Leave the client secret blank unless your administrator issued one. Copilot then opens a browser for you to sign in.

The plugin ignores an oauth block in the configuration file (copilot-intellij-feedback#2041), so a pre-registered client ID cannot be shipped in a project file. Each developer enters it once, in that dialog. Clear a saved registration under Tools  More…​  Clear OAuth Registration.

With an access key

mcp.json
{
  "servers": {
    "develocity": {
      "type": "http",
      "url": "<develocity-url>/mcp",
      "requestInit": {
        "headers": {
          "Authorization": "Bearer <Develocity Access Key>"
        }
      }
    }
  }
}

Use GitHub Copilot for Visual Studio Code to connect to the MCP server (guide).

With OAuth sign-in

Visual Studio Code registers itself when it can: it publishes a client ID metadata document at https://vscode.dev/oauth/client-metadata.json, and falls back to dynamic client registration. Leave the oauth block out to use either:

mcp.json
{
  "servers": {
    "develocity": {
      "type": "http",
      "url": "<develocity-url>/mcp"
    }
  }
}

To use a client your administrator pre-registered, name it instead:

mcp.json
{
  "servers": {
    "develocity": {
      "type": "http",
      "url": "<develocity-url>/mcp",
      "oauth": {
        "clientId": "CLIENT_ID"
      }
    }
  }
}

Visual Studio Code opens a browser the first time it connects to the server. It redirects to one of two fixed addresses, http://127.0.0.1:33418/ and https://vscode.dev/redirect, both of which your administrator registers for the client. See the Visual Studio Code MCP developer guide for the addresses it uses.

With an access key

Using inputs is recommended to avoid hardcoding the Develocity access key within the JSON configuration. You will be prompted for your access key the first time you start the server.

mcp.json
{
  "inputs": [
    {
      "type": "promptString",
      "id": "develocity-access-key",
      "description": "Develocity Access Key",
      "password": true
    }
  ],
  "servers": {
    "develocity": {
      "type": "http",
      "url": "<develocity-url>/mcp",
      "headers": {
        "Authorization": "Bearer ${input:develocity-access-key}"
      }
    }
  }
}

Add the following JSON configuration to your Gemini settings file, typically located at ~/.gemini/settings.json. More details can be found in the documentation.

With OAuth sign-in

Gemini CLI discovers the OAuth configuration from the server and registers itself dynamically when your authorization server supports it:

settings.json
{
  "mcpServers": {
    "develocity": {
      "httpUrl": "<develocity-url>/mcp",
      "oauth": {
        "enabled": true
      }
    }
  }
}

To use a client your administrator pre-registered, add its client ID and the redirect URI registered for it:

settings.json
{
  "mcpServers": {
    "develocity": {
      "httpUrl": "<develocity-url>/mcp",
      "oauth": {
        "enabled": true,
        "clientId": "CLIENT_ID",
        "redirectUri": "REDIRECT_URI"
      }
    }
  }
}

The oauth block also accepts clientSecret, authorizationUrl, tokenUrl, scopes and audiences. Gemini CLI stores the token it receives in ~/.gemini/mcp-oauth-tokens.json.

With an access key

settings.json
{
  "mcpServers": {
    "develocity": {
      "httpUrl": "<develocity-url>/mcp",
      "headers": {
        "Authorization": "Bearer <Develocity Access Key>"
      }
    }
  }
}

Use Gemini in Android Studio to connect to the MCP server (guide).

With OAuth sign-in

Android Studio’s MCP configuration carries no OAuth fields, so it can only sign in when your authorization server registers clients automatically, through a client ID metadata document or dynamic client registration. There is no way to give it a client ID your administrator pre-registered. If neither mechanism is available, connect with an access key instead.

mcp.json
{
  "mcpServers": {
    "develocity": {
      "httpUrl": "<develocity-url>/mcp",
      "timeout": -1,
      "enabled": true
    }
  }
}

The first connection reports an authorization error. Choose Start Login to open a browser and sign in.

With an access key

mcp.json
{
  "mcpServers": {
    "develocity": {
      "httpUrl": "<develocity-url>/mcp",
      "headers": {
        "Authorization": "Bearer <Develocity Access Key>"
      }
    }
  }
}

Claude Desktop reaches a remote MCP server in one of two ways, and which one applies depends on whether your Develocity instance is reachable from the public internet.

A custom connector connects from Claude’s own servers rather than from your machine, so it reaches only an instance that is available on the public internet. See Get started with custom connectors, which covers the OAuth client details you can supply for one.

For an instance on a private network, run a local proxy that presents the server over the STDIO protocol instead. A popular proxy server for this purpose is mcp-remote.

Gradle isn’t affiliated with or involved in the development of mcp-remote.

Please ensure that any third-party software you install complies with your organization’s security policies.

Modify the Claude Desktop configuration file (Developer  Edit Config in settings), replacing <develocity-url>.

With OAuth sign-in

The proxy performs dynamic client registration by default:

{
  "mcpServers": {
    "develocity": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "<develocity-url>/mcp",
        "9696"
      ]
    }
  }
}

The number after the URL fixes the port the proxy listens on for the redirect, so the redirect URI registered at your authorization server must be http://localhost:9696/oauth/callback. Leave the port out and the proxy derives a stable one from the server URL, then prints the callback address on its first run.

To use a client your administrator pre-registered, add --static-oauth-client-info, with a client_secret entry alongside client_id for a confidential client:

{
  "mcpServers": {
    "develocity": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "<develocity-url>/mcp",
        "9696",
        "--static-oauth-client-info",
        "{\"client_id\": \"CLIENT_ID\"}"
      ]
    }
  }
}

If your authorization server supports client ID metadata documents, point the proxy at a document you host with --client-metadata-url instead.

The proxy opens a browser the first time it runs, and stores the token under ~/.mcp-auth, so restarting Claude Desktop does not sign you in again.

With an access key

{
  "mcpServers": {
    "develocity": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "<develocity-url>/mcp",
        "--header",
        "Authorization: Bearer ${API_ACCESS_TOKEN}",
        "--transport",
        "http-only"
      ],
      "env": {
        "API_ACCESS_TOKEN": "<Develocity Access Key>"
      }
    }
  }
}

Other Clients

The MCP server provided by Develocity follows the standard MCP protocol and will work with any clients that support:

  • Remote MCP servers

  • Streamable HTTP transport

  • Bearer authentication, with either a Develocity access key or an OAuth access token obtained through the standard sign-in flow

Usage Tips

After testing the MCP server against a variety of models, use the latest or frontier version of your selected model where possible.

Testing has shown the "light" versions of these models are capable of basic analysis. However, they’re more prone to making mistakes and generally provide worse results than the frontier versions of the models.

Avoiding Common Issues With LLMs

When using the Develocity Analytics tools, briefly inspect the SQL queries submitted by the LLM to the MCP server to catch obvious errors.

Long conversations with many different lines of questioning or analysis may lead to the model’s responses becoming gradually worse. Consider starting a new session or clearing the model’s context to fix this when it happens.

Authentication Troubleshooting

Authentication or access key errors may be interpreted by client applications as a trigger to initiate the OAuth access flow. If you begin to see messages or errors related to authentication or OAuth, verify that your access key configuration is correct, the key is valid, and the associated Develocity user has the required permissions.

Some clients may need a restart for MCP configuration to be correctly updated.

Example Usage

Develocity Tools

Here are some example prompts you can use with the Develocity tools:

  • What are the most flaky tests from this week?

  • What different kinds of failures happened on CI on my branch?

  • What was the cause of the most recent failed build?

  • How can I make builds for this project faster?

Develocity Analytics Tools

Here are some example prompts you can use with the Develocity Analytics tools:

  • Are any projects using a version of log4j earlier than 2.17.1?

  • Which projects are using a non-LTS JDK version?

  • What tasks should I prioritize fixing to stabilize my CI builds?

  • Can you identify whether some users are impacted more by locally failing builds than others?

  • What’s the typical configuration time for local builds?

  • Which are the longest-running tasks in my CI builds?

  • What are the top 5 slowest builds in the last week?