My IBM Bob Day Demo Failed. Quarkus Agent MCP Got Better.
A dead Podman session is a rude demo partner. It is also a very efficient way to find out whether your agent tooling understands the difference between a code problem and an infrastructure problem.
Yesterday at IBM Bob Day, I was supposed to show the new Quarkus Agent MCP.
Instead, I showed a live failure.
Podman was not running. The app I wanted to demo leaned on Quarkus Dev Services. Quarkus did exactly what Quarkus does in that situation: it produced a wall of very real logs. Bob then did the thing I least wanted on stage. It read the failure, treated the mess like it might be a code or configuration problem, and started drifting toward the wrong fixes.
The demo died. That part was annoying. The useful part came right after.
The failure became issue #109, a very plain question with a very real consequence: what if Podman is not running? A few hours later, PR #114 landed with a better answer. The server now detects container-runtime problems earlier, surfaces them more clearly, and tells the agent to ask the human to start Docker or Podman instead of trying random code fixes like an eager intern with too much confidence.
So this article is the introduction I meant to give before the live demo went sideways.
Bob can already edit Java files. What it needs help with is the Quarkus operating model. Which extension should we add instead of hand-rolling the feature? How do we check whether the project is already behind on Quarkus upgrades before we start changing code? Where do we get the last real exception when hot reload falls over? Which dev-mode tools exist in this application right now, not in some old screenshot from three releases ago?
That is where Quarkus Agent MCP gets interesting.
It gives Bob a Quarkus-shaped workflow server. It runs as a separate local process, manages the application lifecycle, proxies the app’s own Dev MCP tools when the app is up, reads extension skills before code gets written, and can search Quarkus documentation locally through a pre-indexed container.
The important part is the opinion behind it: stop making the agent rediscover how Quarkus works from scratch every time.
What You Need
You need IBM Bob, Java 21 or newer, and JBang. If you want semantic documentation search, you also need Docker or Podman because the server starts a local pgvector-backed docs container on first use. The rest of the workflow works without that part.
IBM Bob (other agents work too, of course!)
Java 21 or newer
Docker or Podman for
quarkus_searchDocs
Wire It Into Bob
The basic Bob setup is refreshingly boring. Add the server to your project-level .bob/mcp.json:
{
"mcpServers": {
"quarkus-agent": {
"command": "jbang",
"args": ["quarkus-agent-mcp@quarkusio"],
"env": {
"JAVA_HOME": "/Users/<youruser>/.sdkman/candidates/java/current"
},
}
}
}That is enough to get Bob talking to the server over stdio.
If Bob runs as a desktop app and cannot find jbang, use an absolute path instead. You can also add the JAVA_HOME variable like I did in the example above. The upstream README calls this out explicitly, and it is the same old PATH problem we keep meeting in GUI tools: your shell knows where JBang lives, your desktop app sometimes does not.
It Gives Bob A Quarkus Operating Model
The config file is the easy part. What matters is what Bob learns once the server is attached.
When I initialized the server locally, the response was pleasantly bossy. It returned a very opinionated workflow:
For an existing project, start with
quarkus_updateStart dev mode with
quarkus_startRead extension guidance with
quarkus_skillsSearch docs with
quarkus_searchDocsDiscover live Dev MCP tools with
quarkus_searchToolsExecute them with
quarkus_callTool
I like that because it pushes Bob away from the lazy agent habit of treating every framework as “some files plus Maven.”
Quarkus is not just a build. It has Dev UI, Dev Services, hot reload, extension-specific tooling, and now Dev MCP. If the framework already exposes that surface, I want Bob using it instead of pretending grep, mvn test, and a guess from stale documentation are the same thing.
It Keeps Working When The App Does Not
Quarkus already has Dev MCP inside the running application. That is good, and you should use it. But built-in Dev MCP only exists after the app is up and healthy enough to expose it.
Think of Dev MCP as the application’s own tool surface and Quarkus Agent MCP as the outer driver that gets Bob to that surface and keeps helping when the application faceplants before the inner tools are reachable.
That leaves a nasty gap right where agent workflows tend to get dumb: first boot, broken reload, bad config, compile errors, or a fresh change that takes the app down before the in-app tools are reachable.
Quarkus Agent MCP lives outside that crash radius.
It wraps quarkus dev as a child process, keeps running when the application falls over, and can still help Bob recover. Once the app had already started at least once, Bob can use the structured exception endpoint through quarkus_callTool and devui-exceptions_getLastException. If the app never got that far, the server instructions explicitly tell the agent to fall back to quarkus_logs.
That sounds small until you watch an agent get lost in startup noise.
The usual failure mode with agents is that the moment the happy path breaks, they retreat to raw log scraping and hand-wavy diagnosis. Here, the toolchain already knows the difference between “the app is down,” “the last hot reload failed,” and “you need the last structured exception, not 400 lines of terminal noise.”
That is proper framework leverage.
Skills Before Code Is The Right Bias
Another thing the server gets right is the insistence on quarkus_skills before editing code.
I have written before that AI work gets much better when the context stops living only in the current prompt. Quarkus Agent MCP operationalizes that idea for framework behavior.
Instead of hoping Bob remembers the right Panache pattern, the right REST stack, the right testing approach, or the right CDI usage, the server can load extension-specific skills first. That means the agent does not just know “this project uses Quarkus.” It can learn the conventions and footguns of the extensions actually present in this application.
That is much closer to how a good senior developer works.
You do not walk into an unfamiliar Quarkus service, ignore its stack, and start freehanding. You check what extensions are there, what patterns they expect, and what tooling the project already gives you. Bob should do the same.
The Dev MCP Proxy Is Better Than Another Shell Script
Once the app is running, Quarkus Agent MCP becomes a broker to the application’s own dynamic tool surface.
That is what quarkus_searchTools and quarkus_callTool are for.
The tool list is not static. It changes with the extensions in the app. Add a new capability and there may be new Dev MCP tools worth using. Remove one and the surface changes again. That dynamic discovery model fits Quarkus unusually well because the framework has always treated extensions as first-class units of behavior instead of decorative dependencies.
In practice, this means Bob can do framework-native things like:
Discover test tools and run them without falling back to shell parsing
Inspect endpoints and configuration through the app’s dev surface
Work with extension-provided Dev MCP tools when they exist
Recover from exceptions using Quarkus metadata instead of vague stack-trace archaeology
I prefer this strongly over teaching the agent one more pile of handwritten shell commands.
The Failed Demo Is Already In The Product
This is the part I enjoyed, once I was done being mildly annoyed by the demo.
The failure from yesterday is already encoded in the tool.
Issue #109 was simple: Bob saw Quarkus fail because Podman was not running, read the logs badly, and started chasing the wrong class of fix. PR #114 answered that in two ways.
First, it added a proactive warning when quarkus_start or quarkus_create launches a project that likely depends on Dev Services containers. If Docker or Podman is not available, the agent gets told early that this is an environment problem.
Second, it added reactive diagnosis. When logs or status output match known container-runtime failure patterns, the server appends explicit guidance telling the agent to stop changing code, configuration, or dependencies and ask the user to start the container runtime.
I like this fix because it does not add more vibe. It adds better interpretation.
That is what I want from agent infrastructure. When a live failure happens, the lesson should move into the product quickly and in a way that changes agent behavior the next time around. Thanks Phillip for the swift optimization!
The Local Docs Search Is Real
I tested the docs search locally through the server, and the behavior is very literal.
On first use, quarkus_searchDocs checked for a container runtime, reused a local ghcr.io/quarkusio/chappie-ingestion-quarkus:latest container with pre-indexed docs, connected to pgvector, and loaded the local BGE embedding model before answering the query.
I like that shape for two reasons.
First, the search stays local. I like that for enterprise work.
Second, the cost is explicit. You are not getting “instant magic.” You are starting local infrastructure, loading an embedding model, and then querying a semantic index. That means the first call has some weight to it. After that, the experience is much nicer.
There is also a practical footgun here: without Docker or Podman, the server returns a clean error saying docs search is unavailable while the rest of the toolset still works. I like that behavior too. It fails honestly instead of pretending the feature is present and then slowly disappointing you.
Use It Like A Quarkus Control Plane
The easiest mistake here is to install the server and then keep talking to Bob as if nothing changed.
Do not do that.
Ask Bob to use the Quarkus workflow on purpose:
Use Quarkus Agent MCP to inspect this project, run quarkus_update, and tell me whether we should upgrade before making changes.Start the application with quarkus_start, load the relevant quarkus_skills, then add a REST endpoint for order lookup and run the Quarkus test tools.Use quarkus_searchTools to find the testing tools for this app, run the failing test, and if reload broke, fetch the last structured exception instead of just dumping logs.Search the Quarkus docs for OIDC bearer-token configuration, then summarize the options that apply to this project.These prompts are boring on purpose. Boring is good here. The point is to keep Bob inside the control surface Quarkus already exposes instead of letting it drift back to generic IDE assistant behavior.
Where It Still Bites
This is still agent tooling, so a few rough edges remain.
Docs search depends on a working Docker or Podman setup
Desktop-app PATH issues can break JBang discovery unless you use an absolute path
The Dev MCP surface is dynamic, so Bob should re-discover tools after extension changes
The best exception recovery path depends on whether the app ever started successfully before it failed
This Is The Shape I Want More Of
I do not want agents that are merely better at editing files.
I want agents that understand the operating model of the framework they are touching.
For Quarkus, that means version awareness, extension awareness, Dev UI and Dev MCP awareness, hot-reload awareness, and a real path through failure instead of a cheerful guess. Quarkus Agent MCP gets much closer to that than a generic coding assistant prompt ever will.
So yes, IBM Bob was already useful before this server existed.
But Quarkus Agent MCP makes Bob feel less like a smart autocomplete with ambition and more like a development partner that finally knows where the framework boundaries are.
That is a much better place to start.