How to Build Living AI Coding Assistants With Quarkus Agent MCP

AI code generation tools are fantastic at writing isolated snippets of code, but they quickly fall short when they need to understand a running application's state. When a compiled class fails, or a local database container drops, standard AI coding assistants are left guessing. They lack runtime context, environment visibility, and any real-time connection to your active local development workspace.

The Model Context Protocol (MCP) bridges this gap by standardizing how AI applications interact with local tools. By leveraging the standalone quarkus-agent-mcp server, you can turn your local AI coding companion into a "living" pair programmer that can build, configure, and debug your Quarkus applications in real time.

Why AI Needs a Standalone Agentic Connection

Standard code assistants operate entirely out-of-band. They read your static source files and generate code based on pre-trained patterns. They cannot interact with your running JVM, read console logs, or probe your local environment. This creates a tedious loop of copying terminal errors, pasting them into a chat window, receiving speculative fixes, and repeating the cycle.

While Quarkus offers an in-app Dev MCP server, it suffers from a fundamental limitation: it lives inside the running application process. If your code fails to compile or crashes on startup due to a missing bean, a bad database migration, or a broken dependency, the application dies — and the in-process MCP server dies with it. The agent loses its connection and is left completely blind.

The quarkus-agent-mcp server solves this by running as a completely standalone, always-available process. It wraps your active quarkus dev session as a managed child process. If the application crashes, the agent server survives, allowing the AI to inspect the compiler output, diagnose the error, and execute a fix.

Core Capabilities of the Quarkus Agent

By exposing a standardized control plane to tools like Claude Code, IBM Bob, Cursor,  and GitHub Copilot, the standalone agent server unlocks powerful automations:

• Project scaffolding: The quarkus_create tool can build a brand-new application from scratch. You can tell your agent to "create a Quarkus REST API with PostgreSQL," and it will select the right extensions, bootstrap the build system, and start dev mode automatically.
• Lifecycle control: The agent can programmatically start, stop, and restart your dev mode applications. It handles Maven and Gradle wrappers seamlessly under the hood.
• Dev MCP proxying: The standalone server proxies calls directly to the internal Dev UI. This allows the AI to trigger unit tests, inspect exposed REST endpoints, and manage dev services.
• Semantic documentation search: Instead of making up imaginary APIs, the agent can use semantic search (quarkus_searchDocs) to parse local, pre-indexed documentation.

┌──────────────────────────────────────────────────────────┐
│                      Your IDE with AI assistant          │
└────────────────────────────┬─────────────────────────────┘
                             │ Local JSON-RPC via MCP
                             ▼
┌──────────────────────────────────────────────────────────┐
│          Quarkus Agent MCP (Standalone Server)           │
└────────────────────────────┬─────────────────────────────┘
                             │ Process Mgmt & Dev UI Proxy
                             ▼
┌──────────────────────────────────────────────────────────┐
│                Your Running Quarkus App                  │
└──────────────────────────────────────────────────────────┘

Bootstrapping Your Agentic Setup With JBang

Getting started with quarkus-agent-mcp is incredibly straightforward, especially if you use JBang. You do not need to compile custom helper jars or configure complicated environment paths. You can boot the local MCP server directly from your terminal:

jbang quarkus-agent-mcp@quarkusio --port 8080 --project-dir ./my-quarkus-app

Once the server is running, you can connect your preferred AI agent. For instance, if you are using Claude Code, you can register the local tool server using standard input/output transport:

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

The editor automatically discovers the tool mappings, allowing the agent to safely read, modify, and manage your local workspace.

Skills Before Code: Guiding Your Assistant

One of the most powerful paradigms introduced by the Quarkus Agent is "skills before code". An agent can read specific extension skills via the quarkus_skills tool to learn optimal development patterns, common pitfalls, and testing practices before writing a single line of Java.

You can define custom, domain-specific skills using a simple SKILL.md markdown file in your repository. This acts as the source of truth for the AI assistant, ensuring it follows your team's architectural standards instead of guessing.

package com.example.skills;

import jakarta.enterprise.context.ApplicationScoped;
import io.quarkus.mcp.runtime.annotations.Tool;

@ApplicationScoped
public class CorporateArchitectureSkills {

  	@Tool(name = "scaffold_rest_endpoint", 
          description = "Generates a standardized, secure Quarkus REST resource.")
    public String scaffoldRestEndpoint(String entityName, String path) {
        return """

        package com.example.api;
    
        import jakarta.ws.rs.*;
        import jakarta.ws.rs.core.MediaType;
        import jakarta.transaction.Transactional;
        
        @Path("%s")
        @Produces(MediaType.APPLICATION_JSON)
        @Consumes(MediaType.APPLICATION_JSON)
        public class %sResource {
      
            @POST
            @Transactional
            public void create(%s entity) {
                // Enterprise persistence patterns
            }

        }
        """.formatted(path, entityName, entityName);

    }

}

When the AI assistant needs to create a new endpoint, it bypasses generic web training data, references your corporate skill, and directly calls your custom tool. The result is clean, company-compliant Java code on the first attempt.

Real-World Scenario: Automated Crash Recovery

Let’s trace a common development headache: a failing database migration. Imagine you are working on a service that depends on a PostgreSQL database. You write a new JPA entity, but make a typo in your Liquibase migration file, causing the Quarkus application to crash on startup.

Normally, this halts your momentum. You have to hunt down the stack trace in your terminal, locate the broken SQL block, search the documentation, fix the typo, and rebuild.

With the standalone quarkus-agent-mcp managing your workspace, the recovery loop is entirely automated:

1. Surviving the crash: While the application fails and shuts down, the standalone agent server remains running.
2. Locating the bug: The agent recognizes the crash and calls the Dev MCP proxy tool devui-exceptions_getLastException. This returns a clean JSON payload containing the exception class, the exact error message, and the specific file path.
3. Applying the fix: Using the precise error location, the assistant opens the Liquibase migration file, corrects the syntax, and saves it.
4. Restarting and verifying: The agent calls quarkus_start to reboot dev mode. It monitors the application log stream (quarkus_logs) to verify that the database connection successfully initializes and the app is ready for testing.

Managing Workspace Security and Privacy

A common concern with local agentic execution is security. Because the server is standalone and interacts over a secure stdio channel or local loopback HTTP interface, your code remains private.

The Quarkus Agent MCP runs entirely on your local machine. It does not harvest telemetry or transmit your source code to third-party endpoints. Network outbound calls are strictly gated — limited only to querying Maven Central for public extensions, pulling documentation updates, or fetching dependency updates. You have complete authority over which local tools you expose, creating a secure sandbox for AI pair programming.

Summary

The local developer experience is evolving rapidly. By integrating the standalone quarkus-agent-mcp with your environment, you move far beyond basic code completion. You create a highly collaborative assistant that understands your running JVM, leverages local documentation, and can actively recover from application crashes. This integration proves that modern Java with Quarkus is uniquely suited to lead the future of agentic AI development.