Skip to content

AI Agent Access (MCP)

Don't use MCP as an API

The EngFlow MCP endpoint is designed exclusively for AI agent access. Do not build scripts, automations, or other integrations against it. The available tools and their interfaces may change without notice.

What is MCP?

The Model Context Protocol (MCP) is an open standard for connecting AI agents to external data sources and tools. It allows agents to query your EngFlow cluster directly as part of their workflow. For a full protocol specification, see the MCP documentation.

What can AI agents do with EngFlow?

When connected to your EngFlow cluster via MCP, AI agents can help you investigate and resolve development issues using the features enabled on your cluster:

Debug build and test failures: Agents can examine build results, read invocation logs, and inspect target details to help you understand why a build or test failed and then fix the code locally, all in one workflow.

Identify and debug flaky targets: Agents can look at historical test results across invocations to identify intermittently failing targets, surface failure patterns, and suggest next steps for investigation.

  • Example: "Which targets have been flaky this week? What's causing the failures?"
  • Example: "Is the //src/lib:parser_test flaky on my branch or has it always been flaky?"

Diagnose build speed bottlenecks: Agents can analyze build data to pinpoint where time is being spent and suggest optimizations.

  • Example: "Why is my build slow? What are the longest-running actions?"

How agents access data

The EngFlow MCP server provides programmatic access to the same data visible in the Build and Test UI. A useful rule of thumb: if you can see it in the UI, your agent can likely access it via MCP.

The specific tools available to your agent depend on the features enabled on your cluster. When in doubt, you may ask your agent to describe what tools are available to it.

To enable more tools, talk to your cluster administrator.

Security

The EngFlow MCP server operates with the same permissions as the authenticated user. This means any AI agent connected via MCP can access the same build results, logs, and test data that you can see in the Build and Test UI.

Warning: Access to sensitive data

Note that your AI agent may have access to sensitive information such as source files, environment variables, command-line arguments, and build and test output. Ensure that any AI agent you connect to your cluster is one you trust with access to this data.

Prerequisites

To use the EngFlow MCP server, your cluster must meet the following requirements:

  • Authentication: Your cluster must either have no HTTP authentication configured, or must have JWT token generation enabled.
  • Feature Enabled: MCP must be enabled on your cluster. Ask your cluster administrator or reach out to EngFlow support to enable it.

Setup

This quick MCP setup is per-user and cluster-specific. Your cluster's Getting Started page provides copy-paste configuration for supported AI clients including Claude Code, Cursor, and Windsurf.

To set up MCP access, visit your cluster's /getting-started#mcp page.

Repository-wide setup using dynamic header helpers

Claude Code only

Dynamic header helpers are currently a Claude Code feature. Other clients (Cursor, Windsurf, Codex) support only static or environment-variable headers, so they cannot fetch tokens this way. If you're using those clients, follow the per-user setup on your cluster's Getting Started page.

The per-user setup above configures each developer's machine individually with a personal token. If you administer a shared repository, you can instead check the MCP configuration into the repository once so that it works for everyone, with no per-developer copy-paste and no token stored in the configuration.

This approach uses engflow_auth — the same tool that authenticates Bazel builds — together with Claude Code's headersHelper, a command that Claude Code runs at connection time to supply request headers. The helper fetches a fresh token and re-runs the login flow on its own when needed.

This setup consists of two components:

  • Ensuring all developers have engflow_auth installed and can authenticate to the cluster. See Required one-time setup.
  • Checking in a helper script and an entry for the EngFlow MCP server to the shared repository. See Shared configuration files.

Required one-time setup for all developers

All developers must install engflow_auth and make sure it is on their PATH. Optionally, if you vendor the binary, developers can skip this install altogether.

There is no manual login step: the first time Claude Code connects, the helper opens a browser window to authenticate, and it does so again automatically whenever the stored credential expires.

Claude Code re-runs the helper on reconnect and when a request is rejected with 401/403, so authentication is re-established without leaving the editor.

Use Reconnect, not Authenticate

If authentication lapses, restore it from Claude Code's /mcp menu with Reconnect, which runs the helper. Avoid Authenticate: it triggers Claude Code's own OAuth flow, which bypasses the helper and does not work against EngFlow. If a stuck credential still won't clear, log in once from a terminal and reconnect:

Bash
engflow_auth login https://your-cluster.example.com

Shared configuration files

Commit the following files to your repository so that every developer gets MCP access without any per-user configuration:

  1. Add the following helper script at .claude/tools/engflow-mcp-auth.sh:

    engflow-mcp-auth.sh
     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
    #!/usr/bin/env bash
set -euo pipefail

# How engflow_auth is invoked. To vendor the binary instead of requiring it
# on each developer's PATH, change only this line — see "Vendor the
# engflow_auth binary" below.
run_auth() { engflow_auth "$@"; }

url="${CLAUDE_CODE_MCP_SERVER_URL:?}"
cluster=$(printf '%s' "$url" | sed -E 's#(https?://[^/]+).*#\1#')

# If there is no valid credential yet, log in — this opens a browser window.
if ! run_auth export "$cluster" >/dev/null 2>&1; then
    run_auth login "$cluster" >&2
fi

token=$(run_auth export "$cluster" | sed -E 's/.*"access_token":"([^"]+)".*/\1/')

printf '{"Authorization":"Bearer %s"}' "$token"

    Then, make the script executable by running chmod +x .claude/tools/engflow-mcp-auth.sh.

  2. Add an MCP server entry in .mcp.json that points at the helper. Replace https://your-cluster.example.com with your cluster's URL. The checked-in configuration contains no secrets.

    .mcp.json
    1
2
3
4
5
6
7
8
9
    {
  "mcpServers": {
    "engflow": {
      "type": "http",
      "url": "https://your-cluster.example.com/mcp",
      "headersHelper": ".claude/tools/engflow-mcp-auth.sh"
    }
  }
}

Optional: Vendor the engflow_auth binary

So that developers don't have to install engflow_auth themselves, you can commit the release binaries and let Bazel select the right one for each host. Download the binaries from the engflow_auth releases into, for example, tools/engflow_auth/, then add a BUILD file with a config_setting per platform and a native_binary that selects among them:

BUILD
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
load("@bazel_skylib//rules:native_binary.bzl", "native_binary")

[
    config_setting(
        name = name,
        constraint_values = cvs,
    )
    for name, cvs in {
        "macos_arm64": ["@platforms//os:macos", "@platforms//cpu:arm64"],
        "macos_x64": ["@platforms//os:macos", "@platforms//cpu:x86_64"],
        "linux_arm64": ["@platforms//os:linux", "@platforms//cpu:arm64"],
        "linux_x64": ["@platforms//os:linux", "@platforms//cpu:x86_64"],
    }.items()
]

native_binary(
    name = "engflow_auth",
    src = select({
        ":macos_arm64": "engflow_auth_macos_arm64",
        ":macos_x64": "engflow_auth_macos_x64",
        ":linux_arm64": "engflow_auth_linux_arm64",
        ":linux_x64": "engflow_auth_linux_x64",
    }),
    out = "engflow_auth",
    visibility = ["//visibility:public"],
)

Then change only the run_auth line in the helper script to invoke the binary through Bazel instead of relying on it being on the PATH. The rest of the script stays exactly as above:

engflow-mcp-auth.sh
run_auth() { bazel run --ui_event_filters=-info,-stdout //tools/engflow_auth -- "$@"; }

The --ui_event_filters flag keeps Bazel's build output off stdout so only the token reaches the helper. Teams on a single platform can skip the select and commit just the one binary they need.