Configuration 2.0¶
This page describes the current 2.0 development line. Start with the quickstart for a local stdio server. The 1.x configuration reference is historical.
Project boundary¶
| Setting | Default | Meaning |
|---|---|---|
buildtools.projects.allowed-roots | empty | Comma-separated existing directories the server may access. With no roots, project access is denied. |
Tool argument projectDir | required by path-bearing tools | . selects the first allowed root; relative children resolve below it. Existing absolute paths are accepted only when they resolve inside an allowed root. |
Set roots in the server's local launch configuration, not in a prompt. For example, -Dbuildtools.projects.allowed-roots=/workspace/projects allows a client to pass {"projectDir":"service-a"} without showing an absolute host path to the model. Canonical path checks restrict the server's file access, but a build script still runs with the server process's operating system permissions. Isolate untrusted projects in a container.
Transports and access¶
| Setting | Default | Meaning |
|---|---|---|
spring.profiles.active | default/stdio | http enables stateless Streamable HTTP at /mcp and disables stdio. |
server.address | 127.0.0.1 in the HTTP profile | Listen address. A wider bind requires roots, configured credentials, enforced bearer authentication, and restricted CORS at startup. |
server.port | 8080 | HTTP listen port. |
BUILDTOOLS_API_KEY_<NAME> | absent | A bearer credential loaded from the server environment. Set it from a local secret manager; never copy its value into a prompt or repository. |
BUILDTOOLS_API_KEY_<NAME>_SCOPES | empty | Comma-separated scopes for that key. No scopes means no public tool call is authorized. Grant only the scopes needed; see the tool catalog. |
buildtools.oauth.resource-server.enabled | true in the HTTP profile | Require a configured bearer key for MCP requests. tools/call also checks the key's tool scope and returns 403 when it is absent. |
buildtools.oauth.authorization-servers | empty | Comma-separated issuer URLs. With bearer enforcement active, enables RFC 9728 metadata and a resource_metadata challenge; it does not enable JWT or remote-token validation. |
buildtools.oauth.resource | empty | External canonical MCP resource URL for proxy deployments. When configured, its origin supplies the public metadata link; route the root /.well-known/oauth-protected-resource path through the proxy. |
mcp.transport.cors.allowed-origins | local origins on port 8080 | Browser Origin allowlist for /mcp. Use explicit trusted origins; the server rejects an invalid Origin with 403. |
mcp.transport.allowed-hosts | empty | Additional Host names accepted by the loopback Host guard, useful with a trusted local reverse proxy. |
mcp.transport.max-validation-body-bytes | 1048576 | Maximum MCP POST body size accepted by header and auth inspection; oversized requests receive 413. |
The default HTTP mode uses local opaque keys. See HTTP authentication before configuring an issuer; discovery alone does not validate OAuth tokens.
The HTTP profile binds to loopback and enforces bearer authentication by default. Set a key and scopes before starting it. For example, a read-only client could have build:read,dependency:read; add build:execute only for build execution. This scope permits local Maven install, Gradle publishToMavenLocal, and sbt publishLocal, but rejects Maven deploy and sbt publish as direct command names. This is not a no-publish guarantee: an allowed phase can run POM-configured plugins or build scripts that publish using inherited environment variables or Maven settings. Run untrusted builds in an isolated, credential-free environment; disable its network if possible. Maven project, reactor, settings, and toolchains selectors (such as -f and --file) are rejected; select the project with the validated projectDir argument instead. Maven's direct path-override properties are also rejected.
The buildtools.auth.enabled and buildtools.auth.mode properties belong to the older in-process authorization service; HTTP tools/call scope checks happen in the bearer filter independently of those properties. Do not disable HTTP bearer enforcement for a shared server.
A CLI MCP client may omit Origin; a browser must send a trusted origin. The loopback server also rejects non-local Host values unless explicitly allowed. A TLS-terminating reverse proxy needs a matching CORS origin and, when its Host header reaches the loopback listener, an allowed Host.
Results and runtime limits¶
| Setting | Default | Meaning |
|---|---|---|
| Process capture | 32 KiB head + 96 KiB tail per stream | Maven, Gradle, and sbt output is bounded before privacy projection. |
| Model-visible diagnostics | at most 12 | Structured, normalized, redacted diagnostics; raw logs and commands stay local. |
The supported SDK protocol revision is MCP 2025-11-25. The architecture review explains the transport, privacy boundary, and container workflow in more detail.