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.

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

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.

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

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

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

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

Add to .bob/mcp.json:

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

Add to .cursor/mcp.json:

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

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

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

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"]
    }
  }
}

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

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

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.0.11-runner.jar

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.

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)

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

NEW PROJECT                           EXISTING PROJECT

1. quarkus_create                     1. quarkus_update
   → scaffolds + auto-starts             → checks version, suggests upgrades
   → generates CLAUDE.md + .mcp.json
                                      2. quarkus_start
2. quarkus_skills                        → starts dev mode
   → learn extension patterns
                                      3. quarkus_skills
3. quarkus_searchDocs                    → learn extension patterns
   → look up APIs, config
                                      4. quarkus_searchDocs
4. Write code + tests                    → look up APIs, config

5. Run tests                          5. Write code + tests
   → quarkus_callTool
   → devui-testing_runTests           6. Run tests
                                         → quarkus_callTool
6. Iterate                               → devui-testing_runTests

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).

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:

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 three-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. 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.
3. 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 and 2 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 3 (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.

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.

For existing projects, quarkus_update checks if the Quarkus version is current and provides a full upgrade report:

• Compares build files against reference projects
• Runs quarkus update --dry-run (if CLI available) to preview automated migrations
• Supports custom OpenRewrite recipes via additionalUpdateRecipes (e.g. org.acme:my-recipes:1.0.0), either per-call or configured globally with agent-mcp.update.additional-recipes
• Links to the structural diff between versions
• Recommends manual actions for changes that automated migration doesn't cover

In stdio mode, server logs are invisible because stdout/stderr are consumed by the MCP protocol.

File logging can be enabled permanently by setting agent-mcp.log.enabled=true. The easiest way is via an environment variable in your MCP server configuration:

Claude Code:

claude mcp add quarkus-agent -e AGENT_MCP_LOG_ENABLED=true -- jbang quarkus-agent-mcp@quarkusio

VS Code / GitHub Copilot:

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

Cursor / Windsurf / JetBrains (JSON config):

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

Logs are written to ~/.quarkus/agent-mcp/agent-mcp.log.

The agent can also toggle file logging on-the-fly using these tools:

The MCP server wraps quarkus dev as a child process, so it stays alive when the app crashes. This is the key differentiator from the built-in Dev MCP server.

Configuration via application.properties, system properties (-D), or environment variables:

For instant startup (no JVM warmup):

./mvnw package -Dnative -DskipTests -Dquarkus.package.jar.type=uber-jar

Then reference the native binary in your MCP config:

claude mcp add quarkus-agent -- ./target/quarkus-agent-mcp-*-runner

An HTML slide deck is available in the presentation/ directory for team demos and talks.

# Open directly in a browser
xdg-open presentation/index.html   # Linux
open presentation/index.html        # macOS

Press F for fullscreen, arrow keys or space to navigate slides.

Error: spawn jbang ENOENT

This happens when the MCP client (IDE, desktop app) cannot find jbang or java on its PATH. It affects JetBrains IDEs, Claude Desktop, and other desktop applications that don't inherit your shell environment.

Why it happens: Desktop applications launched from a graphical environment inherit the system PATH (from systemd on Linux, or system environment variables on Windows/macOS), not the shell PATH (from ~/.bashrc, ~/.zshrc, ~/.profile). Tools installed via user-local version managers — SDKMAN!, JBang's default installer, asdf, mise — are on the shell PATH but not the system PATH.

This is different from VS Code, which typically resolves the full shell environment, and from IDE built-in terminals, which start a proper login shell.

Solutions (pick one):

1. Use absolute paths in your MCP config (recommended):

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

   Find the path with which jbang or which java in a terminal.

2. Symlink into a system PATH directory:

   sudo ln -s ~/.jbang/bin/jbang /usr/local/bin/jbang

3. Add to the system PATH permanently:

   • Linux (systemd): Create /etc/profile.d/jbang.sh with export PATH="$HOME/.jbang/bin:$PATH", or add the path to ~/.config/environment.d/ for systemd user sessions.
   • macOS: Use launchctl setenv PATH ... or add to /etc/paths.d/.
   • Windows: Add %USERPROFILE%\.jbang\bin to the system environment variables (System → Advanced → Environment Variables → System variables → Path).

java.nio.file.AccessDeniedException: C:\WINDOWS\system32\config

This is a Quarkus core issue that occurs on Windows when the MCP server is launched by an IDE with the working directory set to system32. Quarkus scans {working-dir}/config for configuration files and hits the protected Windows registry hive directory.

Workaround: Set the working directory explicitly in your MCP config, or pass -Duser.dir to override it:

{
  "servers": {
    "quarkus-agent": {
      "type": "stdio",
      "command": "java",
      "args": ["-Duser.dir=C:\\Users\\you", "-jar", "C:\\path\\to\\quarkus-agent-mcp-runner.jar"]
    }
  }
}

• Creating Extension Skills - A practical guide for extension developers to discover, write, and test AI skills for their extensions

• Quarkus Dev MCP — Built-in MCP server inside running Quarkus apps
• quarkus-skills — Standalone skill files for Quarkus (Agent Skills specification)
• code-with-quarkus-compare — Reference projects for build file comparison
• chappie-docling-rag — Builds the pgvector Docker images with pre-indexed Quarkus docs
• quarkus-mcp-server — Quarkiverse MCP Server extension used by this project

Quarkus Agent MCP runs entirely on your local machine. It does not collect, transmit, or store any personal data, telemetry, or analytics.

The server makes the following outbound network requests, all in service of its documented features:

No data is sent to Quarkus, Red Hat, or any third party. All downloaded artifacts are cached locally in standard locations (~/.m2/repository, Docker image cache). Source code and project files never leave your machine.

Apache License 2.0