Quarkus Agent

Quarkus Agent MCP

A standalone MCP server that enables AI coding agents to create, manage, and interact with Quarkus applications. It runs as a separate process that survives app crashes, giving agents the ability to create projects, check for updates, read extension skills, control application lifecycle, proxy Dev MCP tools, and search Quarkus documentation.

Part of the DevStar working group.

Prerequisites

• Java 21+
• Docker or Podman (for documentation search)
• One of: Quarkus CLI, Maven, or JBang (for creating new projects)

Installation

Claude Code plugin

Add the marketplace and install the plugin:

claude plugin marketplace add quarkusio/quarkus-agent-mcp
claude plugin install quarkus-agent@quarkus-tools

This installs the plugin and configures the MCP server automatically. Requires JBang.

Via JBang (recommended)

JBang resolves the uber-jar from Maven Central automatically — no build step needed.

Claude Code

claude mcp add quarkus-agent -- jbang quarkus-agent-mcp@quarkusio

VS Code / GitHub Copilot

Add to .vscode/mcp.json in your workspace:

{
  "servers": {
    "quarkus-agent": {
      "type": "stdio",
      "command": "jbang",
      "args": ["quarkus-agent-mcp@quarkusio"]
    }
  }
}

IBM Bob

Add to .bob/mcp.json:

{
  "mcpServers": {
    "quarkus-agent": {
      "command": "jbang",
      "args": ["quarkus-agent-mcp@quarkusio"]
    }
  }
}

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "quarkus-agent": {
      "command": "jbang",
      "args": ["quarkus-agent-mcp@quarkusio"]
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "quarkus-agent": {
      "command": "jbang",
      "args": ["quarkus-agent-mcp@quarkusio"]
    }
  }
}

JetBrains IDEs (IntelliJ IDEA, WebStorm, etc.)

In Settings → Tools → AI Assistant → MCP Servers (or the GitHub Copilot MCP settings), add a server with an absolute path to jbang:

{
  "mcpServers": {
    "quarkus-agent": {
      "type": "stdio",
      "command": "/home/you/.jbang/bin/jbang",
      "args": ["quarkus-agent-mcp@quarkusio"]
    }
  }
}

Why absolute paths? JetBrains IDEs launched from the desktop inherit the system PATH, not your shell PATH (~/.bashrc / ~/.zshrc). Tools installed via SDKMAN!, JBang's default installer, asdf, or mise are typically on the shell PATH only — so the IDE can't find them. See Troubleshooting below.

Alternatively, use the direct download method with an absolute path to java:

{
  "mcpServers": {
    "quarkus-agent": {
      "type": "stdio",
      "command": "/path/to/java",
      "args": ["-jar", "/path/to/quarkus-agent-mcp-runner.jar"]
    }
  }
}

Via direct download

Download the uber-jar from the latest GitHub Release, then:

claude mcp add quarkus-agent -- java -jar /path/to/quarkus-agent-mcp-runner.jar

Build from source

git clone https://github.com/quarkusio/quarkus-agent-mcp.git
cd quarkus-agent-mcp
./mvnw package -DskipTests -Dquarkus.package.jar.type=uber-jar

This produces the uber-jar at target/quarkus-agent-mcp-1.0.0-SNAPSHOT-runner.jar (version may vary).

claude mcp add quarkus-agent -- java -jar /path/to/quarkus-agent-mcp/target/quarkus-agent-mcp-1.1.7-runner.jar

Verify

After registering, ask your agent something like:

"Search the Quarkus docs for how to create a REST endpoint"

If the MCP server is working, the agent will use quarkus_searchDocs and return documentation results.

Usage

Creating a new Quarkus app

Ask your agent to build a Quarkus application using natural language. The agent uses the MCP tools automatically.

Example conversation:

You: Create a Quarkus REST API with a greeting endpoint and a PostgreSQL database

Agent: (uses quarkus_create to scaffold the project with rest-jackson,jdbc-postgresql,hibernate-orm-panache extensions — the app starts automatically in dev mode, a CLAUDE.md is generated with project-specific workflow instructions, and a .mcp.json is created for automatic MCP server discovery)

Agent: (calls quarkus_skills to learn the correct patterns for Panache, REST, and other extensions before writing any code)

You: Add a Greeting entity and a REST endpoint that stores and retrieves greetings

Agent: (writes the code following patterns from skills, then runs tests using quarkus_callTool — via a subagent if supported)

Development workflow

The MCP server guides the agent through the optimal Quarkus development workflow:

NEW PROJECT                           EXISTING PROJECT

1. quarkus_create                     1. quarkus_start
   → scaffolds + auto-starts             → starts dev mode
   → generates CLAUDE.md + .mcp.json
                                      2. quarkus_skills
2. quarkus_skills                        → learn extension patterns
   → learn extension patterns            → query 'quarkus-update' to check version
                                      3. quarkus_searchDocs
3. quarkus_searchDocs                    → look up APIs, config
   → look up APIs, config
                                      4. Write code + tests
4. Write code + tests
                                      5. Run tests
5. Run tests                             → quarkus_callTool
   → quarkus_callTool                    → devui-testing_runTests
   → devui-testing_runTests

6. Iterate

Key points:

• Hot reload is automatic in Quarkus dev mode — triggered on the next access (HTTP request or test run), not on file save.
• Skills before code — the agent reads extension-specific skills to learn correct patterns, testing approaches, and common pitfalls before writing any code.
• Tests via subagents — if your agent supports subagents, test execution can be dispatched to one so the main conversation stays responsive.
• The MCP server survives crashes — if the app crashes due to a code error, the agent can use devui-exceptions_getLastException to get structured exception details (class, message, stack trace, user code location) and fix it. Use quarkus_logs for broader context.
• CLAUDE.md — every new project gets a CLAUDE.md with Quarkus-specific workflow instructions that guide the agent.
• .mcp.json — every new project gets a .mcp.json for automatic MCP server discovery by agents that support the convention (Claude Code, Pi/pi.dev).

What the agent can do with a running app

Once a Quarkus app is running in dev mode, the agent can discover and use all Dev MCP tools via quarkus_searchTools and quarkus_callTool. The tool list is dynamic — it changes when extensions are added or removed, so the agent should re-discover tools after any extension change. Typical tools include:

Extension skills

The agent can read extension-specific coding skills using quarkus_skills. Skills contain patterns, testing guidelines, and common pitfalls for each extension — things like "always use @Transactional for write operations with Panache" or "don't create REST clients manually, let CDI inject them."

When called without a query, skills are organized by category (Web, Data, Security, Core, etc.) for easier discovery.

Skills are loaded using a four-layer chain (most specific wins):

1. Extension skills — discovered from individual extension deployment JARs (META-INF/quarkus-skill.md) in the local Maven repository, composed with extension metadata and available Dev MCP tools. This supports skills from Quarkus core, Quarkiverse, and custom extensions. For older Quarkus versions that don't ship skill files in deployment JARs, the aggregated quarkus-extension-skills JAR is used as a fallback.
2. Bundled community skills — shipped in the io.quarkus:quarkus-skills JAR on the classpath (META-INF/skills/<name>/SKILL.md). These include standalone workflow skills like Spring-to-Quarkus migration and project update checking, and are available immediately without any installation step.
3. User-level skills — from ~/.quarkus/skills/<extension-name>/SKILL.md (or a directory configured via agent-mcp.local-skills-dir). Useful for extension developers testing new or modified skills without rebuilding the aggregated JAR.
4. Project-level skills — from .agent/skills/<extension-name>/SKILL.md in the project directory. These are standalone files read as-is (no composition with base layers), so any agent can read them directly from the filesystem. Use quarkus_saveSkill to materialize a fully composed skill into this directory, then edit the file directly.

Layers 1–3 support enhance and override composition, controlled by the mode field in the SKILL.md frontmatter:

• mode: enhance (default) — appends content to the base skill. The base content is preserved and the customization is added after a separator. This is ideal for adding personal conventions or standards without losing the built-in guidance.
• mode: override — fully replaces the base skill. Use this when you need complete control over a skill's content.

Layer 4 (project) always replaces — the file content is used directly with no composition.

The agent can create or update global skill customizations using quarkus_updateSkill (writes to ~/.quarkus/skills/). For project-level customization, use quarkus_saveSkill to materialize the full composed skill into .agent/skills/, then edit the file directly.

Documentation search

The agent can search Quarkus documentation at any time using quarkus_searchDocs. This uses semantic search (BGE embeddings + pgvector) over the full Quarkus documentation.

On first use, a Docker/Podman container with the pre-indexed documentation is started automatically. If a project directory is provided, the documentation version matches the project's Quarkus version.

Documentation from Quarkiverse and third-party extensions is also indexed automatically when those extensions are project dependencies. Extensions can ship their documentation embeddings either bundled in the deployment JAR or as a separate artifact (recommended for extensions with multiple doc pages — see the Contributing Extension Documentation guide).

To narrow results to a specific extension, use the extension parameter:

quarkus_searchDocs query="broadcasting messages" extension="quarkus-json-rpc"

MCP Tools Reference

App Creation

…