Usage¶
1.x reference: This page documents earlier raw-output behavior. For the current 2.0 result contract, use the 2.0 quickstart and 2.0 design review.
Once the server is installed and configured in your MCP client, you interact with it the way you interact with any MCP server: the agent discovers the tools, then calls them on your behalf in response to your natural-language requests.
The connection lifecycle¶
- Initialize. Your MCP client launches the server (
java -jar …) and performs the MCPinitializehandshake over stdio. The server reports its name and version. - Discover. The client calls
tools/list. The server returns the 28 registered tools, each with a name, description, and JSON input schema generated from its@Tool/@ToolParamannotations. - Call. When you ask for something, the agent picks a tool and issues a
tools/callwith the required arguments. The server validates the request, runs it, and returns the result.
client ──initialize──▶ server (handshake; name + version)
client ──tools/list──▶ server (discover 28 tools + schemas)
client ──tools/call──▶ server (e.g. execute_build_command {...})
client ◀──result──── server (text or JSON payload)
Talking to your agent¶
You don't construct tool calls by hand — you describe what you want, and the agent maps it to a tool. Useful phrasings:
What build tools are available?
Detect the build tool for /path/to/my-project
Build and test /path/to/my-project
Run 'clean test' on /path/to/my-maven-app
What is the latest version of com.google.guava:guava?
Validate the build configuration in /path/to/my-project
Are there dependency version conflicts in /path/to/my-project?
Is /path/to/my-project compatible with Java 17?
Common starting points¶
| You want to… | The agent typically calls | Returns |
|---|---|---|
| See what's available | list_build_tools | Registered tools and their commands |
| Identify a project's build tool | detect_build_tool | JSON with detected tool(s) and markers |
| Run a build and read the log | execute_build_command | Raw build output (text) |
| Run a build and parse results | analyze_build_output | Structured JSON (tests, errors, warnings) |
| Check a build file without building | validate_build_configuration | JSON validation report |
| Find the latest dependency version | check_dependency_version | JSON with latest/stable versions |
The complete catalogue — every tool, its inputs, and outputs — is in the Tools / MCP API reference.
How a tool call is shaped¶
Under the hood, a tools/call carries the tool name and an arguments object. For example, running clean test on a Maven project looks like this on the wire:
{
"method": "tools/call",
"params": {
"name": "execute_build_command",
"arguments": {
"buildToolName": "maven",
"buildToolHome": "/opt/maven",
"projectDir": "/path/to/my-maven-app",
"command": "clean test"
}
}
}
Key points that apply to most tools:
projectDiris almost always required and must be an existing directory. The server canonicalises it withPath.toRealPath(), so it must resolve to a real path.buildToolNameis usually optional — omit it to let the server auto-detect from project markers (pom.xml→ Maven,build.gradle*→ Gradle,build.sbt→ SBT).buildToolHomeis required for Maven unlessMAVEN_HOMEis set; it is optional for Gradle and SBT.- Commands must be allowlisted. Only known phases/tasks run; unknown commands are rejected before any process starts.
Build vs. analyse: choosing the right tool¶
execute_build_command vs. analyze_build_output
Both run a real build. The difference is the return shape:
execute_build_command | analyze_build_output | |
|---|---|---|
| Returns | Raw stdout text | Structured JSON |
| Parsed output | No | Yes — test counts, errors with file:line, warnings |
| Best for | Quick builds, version checks | CI-style analysis, agents that parse results |
Use analyze_build_output when the agent needs to reason about failures programmatically; use execute_build_command when you just want the log.
Build-tool command syntax¶
The server preserves each tool's native command syntax:
Space-separated tasks. --no-daemon --console=plain are added automatically — don't include them. Multi-module tasks use colon syntax (:submodule:build):
Working with multiple projects¶
The server is stateless: each call is independent and carries its own projectDir. An agent can build a Maven project and then a Gradle project in succession with no state leakage. You can also run multiple server instances — each MCP client config entry spawns its own process.
Transport options: stdio and Streamable HTTP¶
Most users run the server over stdio (the default) — the MCP client launches java -jar … and talks to it over stdin/stdout, with no network surface. For remote or shared deployments the server also offers an opt-in Streamable HTTP transport.
Configured automatically by your MCP client (see Installation). No port, no HTTP, no tokens — ideal for a local desktop agent.
Activate the http Spring profile (or pass --http to the launcher) and choose a port:
The transport is stateless. The HTTP profile binds to loopback and requires a configured, scoped opaque API key by default. In this 1.x usage page, the examples above are historical; use the 2.0 HTTP authentication guide for current key setup and optional OAuth discovery. Without a configured issuer, the OAuth metadata endpoint returns 404 and a 401 response carries a plain Bearer challenge. Issuer configuration does not add JWT validation.
Verifying behaviour quickly¶
Ask the agent to call list_build_tools first. If it returns the Maven/Gradle/SBT commands, the MCP handshake and tool discovery are working. If the agent reports no tools, the handshake failed — check that the JAR path is absolute and that the client was fully restarted.
For concrete, end-to-end examples with sample responses, see Examples.