DEV Community: Sebastiao Gazolla Jr

Our Java MCP Agent in Action: A Demo and the Results

Sebastiao Gazolla Jr — Thu, 25 Sep 2025 22:10:54 +0000

Follow-up to the "From Zero to AI Agent: My Journey into Java-based Intelligent Applications" series

After seven posts building our Java MCP client from scratch, it was time for a test recording a demo to see how our AI agent performs with some user queries. The results are here.

Today I'm sharing what happened during our demo session: the successes, the failures, and the valuable lessons learned about AI agent behavior.

The Demo Setup

Our JavaChatAI agent was running with:

Three MCP servers: FileSystem, Weather and Time services
LLM Provider: Groq with Llama model
Full multi-tool orchestration as built in our series
Three execution modes: DIRECT_ANSWER, SINGLE_TOOL, and MULTI_TOOL

The plan was simple: test various query types and see how our intelligent routing performs.

Test 1: "What is the capital of the United States?"

Expected Behavior: DIRECT_ANSWER (no tools needed)

What Happened:

🤖 Washington, D.C.

Result: PERFECT

Our agent correctly identified this as a knowledge-based query that doesn't require any external tools.

Test 2: "What time is it in Denver, CO?"

Expected Behavior: SINGLE_TOOL (time server)

What Happened:

Detected response modality: SINGLE_TOOL
🤖 It is 5:22 PM in Denver.

Result: PERFECT

The agent correctly identified this as a single-tool operation, selected the appropriate time server, and accurately extracted the required location parameter ("Denver, CO").

Our parameter extraction and tool selection logic is working.

Test 3: "How far is Denver, CO from Washington, D.C. by plane?"

Expected Behavior: DIRECT_ANSWER (no distance/flight tools available)

What Actually Happened:

Detected response modality: MULTI_TOOL
[Orchestrator attempts to create execution plan]
[Plan fails - no appropriate tools available]
🤖 The flight distance between Denver, CO and Washington, D.C. is approximately
** 1,600 miles (2,575 kilometers) **. The actual travel time will vary depending on the flight path and speed.

Result: CORRECT OUTPUT, WRONG PROCESS

Our agent initially misclassified this as a MULTI_TOOL query (get_current_time and get-forecast), but when the orchestrator couldn't find appropriate answer for distance calculation, it fell back to using the LLM's knowledge.

Test 4: "What time is it and How's the weather in Washington, DC?"

Expected Behavior: MULTI_TOOL with two parallel operations

What Actually Happened:

Detected response modality: MULTI_TOOL
[Creates plan with time tool, weather tool, and... file write tool?]
...
...
🤖 It's 7:22 PM Eastern Time. The weather in Washington, DC is currently 69°F with a chance of showers and thunderstorms tonight. Expect similar conditions for the next few days, with highs in the 70s and 80s.

Result: CORRECT INFORMATION, WRONG TOOL SELECTION

The agent successfully got both pieces of information we requested, but it hallucinated an additional step trying to save the results to a file! And it actually did save the file in the project's folder.

What These Results Tell Us

What's Working Well

The agent's architecture is built upon a basic routing logic that first distinguishes between queries requiring a DIRECT_ANSWER and those needing tool-based resolution. For the latter, it demonstrates proficiency in single-tool execution, accurately handling parameter extraction and making the appropriate tool call.

What Needs Improvement

First, there is a tendency for over-classification as MULTI_TOOL, where the agent is too aggressive in assuming queries require multiple tools. This is closely related to the issue of tool hallucination, where the agent adds unnecessary steps, like saving files, that were not requested by the user. To address these problems, the primary focus should be on analysis prompt tuning, making the criteria for when a multi-tool approach is actually needed much more precise and restrictive.

This demo reinforced something important: building AI agents is an iterative process. Our architecture is solid, our core functionality works, but the intelligence layer (prompt engineering and decision-making) needs continuous refinement.

Try It Yourself

The complete code from our series is available on GitHub. I encourage you to clone it, run your own tests, and see what interesting behaviors you discover.

Conclusion

This demo session showed us that our Java MCP agent is functional and can handle user queries, but it also highlighted areas where we need to improve the intelligence layer.

The agent never crashed, always provided some form of useful response, and demonstrated that our architecture can handle the complexity of AI interactions.

Follow @gazolla for more AI development using Java.

Multi-Tool Execution: When One Tool Isn't Enough

Sebastiao Gazolla Jr — Tue, 23 Sep 2025 01:53:18 +0000

Part 7 of the "From Zero to AI Agent: My Journey into Java-based Intelligent Applications" series

In our previous post, we built a query processor that could analyze natural language and execute single tools. But here's what I discovered while testing it: real users don't think in single-tool terms.

They say things like:

"Get the weather in Denver,CO and save it to a file"
"Create a backup folder and move all my documents there"
"Check prices on three websites and tell me the cheapest"

Each requires multiple tools working together. Today, we're solving this by building a multi-tool orchestration system that can coordinate complex workflows automatically.

The Evolution: From Single to Multi

Let's start with what we had in Part 5. Our SimpleInference could handle this:

// ✅ This worked fine
"What's the weather in NYC?" → Single tool → weather-server:weather_query

But it couldn't handle this:

// ❌ This required hardcoding or failed entirely  
"Get NYC weather and save it to weather.txt" → ??? → Two tools needed

The user wants one fluid action, but we need two separate tool calls with coordination between them.

The MultiToolOrchestrator:

Instead of trying to cram multi-tool logic into SimpleInference, we created a dedicated orchestrator that specializes in coordinating multiple tools:

public class MultiToolOrchestrator {
    private final LLMClient llmClient;
    private final MCPService mcpService;
    private final Map<String, ToolResult> stepResults = new HashMap<>();

    public ToolResult executePlan(MultiToolPlan plan) {
        return switch (plan.getPlanType()) {
            case SEQUENTIAL -> executeSequential(plan);
            case PARALLEL -> executeParallel(plan);
            case CHAINED -> executeChained(plan);
            case COMPETITIVE -> executeCompetitive(plan);
            // Note: CONDITIONAL and ITERATIVE are partially implemented
        };
    }
}

Key insight: Rather than having one complex method that tries to handle everything, we have specialized execution strategies for different types of multi-tool scenarios.

The Four Main Execution Patterns (Currently Implemented)

1. Sequential: "Do This, Then That"

When to use: Steps must happen in a specific order, but each step is independent (no data flow between them).

Example: "Send an email to John about the meeting, then set a calendar reminder for tomorrow"

private ToolResult executeSequential(MultiToolPlan plan) throws Exception {
    List<Step> steps = plan.getSteps();

    for (Step step : steps) {
        // Check if this step's dependencies are satisfied
        if (!areDependenciesSatisfied(step)) {
            return ToolResult.error("Dependencies not satisfied for step: " + step.id());
        }

        // Execute the step
        Map<String, Object> resolvedParams = resolveParameters(step);
        ToolResult result = mcpService.callTool(step.serverId(), step.toolName(), resolvedParams);

        // Store result for later steps to use
        stepResults.put(step.id(), result);

        if (!result.success()) {
            return result; // Stop on first failure
        }
    }

    return aggregateResults(new ArrayList<>(stepResults.values()), plan.getAggregationPrompt());
}

Why this pattern: The folder must exist before we can save a file to it. Sequential execution ensures proper ordering.

2. Parallel: "Do These All At Once"

When to use: Operations are independent and can run simultaneously.

Example: "Check the weather in Austin,TX; Chicago,IL and Atlanta,GA"

private ToolResult executeParallel(MultiToolPlan plan) throws Exception {
    List<Step> independentSteps = plan.getIndependentSteps();
    ExecutorService executor = getExecutorService();

    // Launch all independent steps simultaneously
    List<CompletableFuture<Void>> futures = independentSteps.stream()
        .map(step -> CompletableFuture.runAsync(() -> {
            try {
                Map<String, Object> resolvedParams = resolveParameters(step);
                ToolResult result = mcpService.callTool(step.serverId(), step.toolName(), resolvedParams);
                synchronized (stepResults) {
                    stepResults.put(step.id(), result);
                }
            } catch (Exception e) {
                synchronized (stepResults) {
                    stepResults.put(step.id(), ToolResult.error("Parallel execution failed: " + e.getMessage()));
                }
            }
        }, executor))
        .toList();

    // Wait for all to complete
    CompletableFuture.allOf(futures.toArray(new CompletableFuture[0])).join();

    return aggregateResults(new ArrayList<>(stepResults.values()), plan.getAggregationPrompt());
}

Why this pattern: Getting weather for different cities doesn't depend on each other, so we can do them all at once for better performance.

3. Chained: "Output Becomes Input"

When to use: Steps must happen in a specific order, but each step is independent (no data flow between them)

Example: "Get the weather in NYC and save it to weather.txt in documents"

private ToolResult executeChained(MultiToolPlan plan) throws Exception {
    List<Step> steps = plan.getSteps();

    for (int i = 0; i < steps.size(); i++) {
        Step step = steps.get(i);
        Map<String, Object> resolvedParams = resolveParameters(step);

        // Automatically pipe previous result as input
        if (i > 0 && !stepResults.isEmpty()) {
            ToolResult previousResult = stepResults.get(steps.get(i - 1).id());
            if (previousResult != null && previousResult.success()) {
                resolvedParams.putIfAbsent("input", previousResult.content());
            }
        }

        ToolResult result = mcpService.callTool(step.serverId(), step.toolName(), resolvedParams);
        stepResults.put(step.id(), result);

        if (!result.success()) {
            return result;
        }
    }

    return aggregateResults(new ArrayList<>(stepResults.values()), plan.getAggregationPrompt());
}

Why this pattern: Each step transforms the data from the previous step, creating a processing pipeline.

4. Competitive: "Race for the Best Result"

When to use: Multiple tools can do the same thing, and you want the best/fastest result.

Example: "Check laptop prices on three sites and recommend the cheapest"

private ToolResult executeCompetitive(MultiToolPlan plan) throws Exception {
    ExecutorService executor = getExecutorService();

    // Run all steps in parallel and race them
    List<CompletableFuture<ToolResult>> futures = plan.getSteps().stream()
        .map(step -> CompletableFuture.supplyAsync(() -> {
            try {
                Map<String, Object> resolvedParams = resolveParameters(step);
                return mcpService.callTool(step.serverId(), step.toolName(), resolvedParams);
            } catch (Exception e) {
                return ToolResult.error("Competitive execution failed: " + e.getMessage());
            }
        }, executor))
        .toList();

    // Return first successful result
    List<ToolResult> results = futures.stream()
        .map(CompletableFuture::join)
        .toList();

    for (ToolResult result : results) {
        if (result.success()) {
            return result; // First success wins
        }
    }

    return ToolResult.error("All competitive executions failed");
}

Why this pattern: Sometimes multiple tools can accomplish the same goal, and we want the fastest or best result.

The Smart Planning: From Natural Language to Execution Plan

The deal happens in how we determine which pattern to use. We enhanced our SimpleInference with this analysis:

private String executeMultiTool(QueryAnalysis analysis, String originalQuery) throws Exception {
    if (orchestrator == null) {
        return "Multi-tool execution not available - orchestrator not configured";
    }

    // Generate a plan using specialized AI analysis
    MultiToolPlan plan = analyzeMultiToolQuery(originalQuery);

    if (!plan.isValid()) {
        return "Could not create valid execution plan for this query.";
    }

    // Execute the plan using the appropriate pattern
    ToolResult result = orchestrator.executePlan(plan);

    if (result.success()) {
        return generateToolResponse(originalQuery, "multi-tool plan", result.content());
    } else {
        // Fallback to direct answer if execution fails
        String fallbackPrompt = PromptTemplates.getFallbackPrompt(originalQuery);
        return llmClient.send(fallbackPrompt);
    }
}

The Variable Resolution

One of the interesting features is how steps can reference results from previous steps:

private String resolveVariables(String value) {
    Pattern pattern = Pattern.compile("\\$\\{([^.]+)\\.([^}]+)\\}");
    Matcher matcher = pattern.matcher(value);

    StringBuffer resolved = new StringBuffer();
    while (matcher.find()) {
        String stepId = matcher.group(1);
        String field = matcher.group(2);

        ToolResult stepResult = stepResults.get(stepId);
        if (stepResult != null && stepResult.success()) {
            String replacement = extractField(stepResult, field);
            matcher.appendReplacement(resolved, Matcher.quoteReplacement(replacement));
        }
    }
    matcher.appendTail(resolved);

    return resolved.toString();
}

This allows us to create plans like:

{
  "steps": [
    {
      "id": "get_weather",
      "toolName": "weather_query",
      "parameters": {"location": "NYC"}
    },
    {
      "id": "save_weather", 
      "toolName": "write_file",
      "parameters": {
        "path": "weather.txt",
        "content": "${get_weather.result}"  // ← Magic happens here
      },
      "dependencies": ["get_weather"]
    }
  ]
}

One Example:

Let's trace through a complete example:

User: "Get the weather in NYC and save it to weather.txt in documents"

1. Analysis Phase - LLM determines:

QueryAnalysis[
   execution=MULTI_TOOL, 
   details=CHAINED, 
   parameters={toolsInfo=weather-server:get-forecast:
     Retrieve weather data for NYC, filesystem-
     server:write_file: Save the weather data to    
     weather.txt in documents, 
     reasoning=The query requires getting the weather in NYC and saving it to a file, which involves two distinct actions: retrieving weather data and writing to a file. The output of getting the weather becomes the input for saving it to a file., 
     planName=CHAINED}, 
     multiToolPlan=Optional.empty]

2. Planning Prompt:

Create a detailed execution plan for this multi-tool 
query:"Get the weather in NYC and save it to weather.txt in documents"

         Available tools:
         - filesystem-server:read_file 
         - filesystem-server:read_multiple_files 
         - filesystem-server:write_file - 
         - .....
         - weather-server:get-forecast 

         Analyze the query and return a JSON plan with:
         - planType: "SEQUENTIAL", "PARALLEL", "CHAINED", "CONDITIONAL", "COMPETITIVE", or "ITERATIVE"
         - steps: array of objects with {"id": "unique_id", "serverId": "server_id", "toolName": "tool_name", "parameters": {}, "dependencies": []}
         - conditionPrompt: (optional) for conditional/iterative logic
         - aggregationPrompt: (optional) for result consolidation

         Guidelines:
         - Use SEQUENTIAL for dependent operations
         - Use PARALLEL for independent operations
         - Use CHAINED when output of one becomes input of next
         - Include dependencies array with step IDs this step depends on
         - Use variable substitution like ${previous_step_id.result} in parameters
         - For file paths, use RELATIVE paths only (e.g., "documents/file.txt" NOT "/documents/file.txt")
         - All paths must be relative to the current working directory
         - Do not use leading slashes (/) in file paths

 CRITICAL CONSTRAINTS:
- ONLY use tools from the "Available tools" list above - do NOT invent tools
- Use your complete knowledge base to provide any required parameters (coordinates, timezones, conversions, etc.)
- Match tool names and parameter names exactly as specified in tool descriptions
- If multiple independent operations of same type, use PARALLEL planType for efficiency

         Return ONLY the JSON plan:

3. Plan Generation:

{
  "planType": "SEQUENTIAL",
  "steps": [
    {
      "id": "step1",
      "serverId": "weather-server",
      "toolName": "get-forecast",
      "parameters": {
        "latitude": 40.7128,
        "longitude": -74.0060
      },
      "dependencies": []
    },
    {
      "id": "step2",
      "serverId": "filesystem-server",
      "toolName": "write_file",
      "parameters": {
        "path": "documents/weather.txt",
        "content": "${step1.result}"
      },
      "dependencies": ["step1"]
    }
  ]
}

4. Execution:

Step 1: Get weather

  mcpService.callTool("weather-server", "get-forecast", {
      "latitude": 40.7128, 
      "longitude": -74.006
  })

→ Returns: "Sunny, 22°C in NYC"

Variable resolution:

  orchestrator.resolveVariable("${step1.result}")

→ "${step1.result}" becomes "Sunny, 22°C in NYC"

Step 2: Save file with resolved content

  mcpService.callTool("filesystem-server", "write_file", {
      "path": "documents/weather.txt",
      "content": "Sunny, 22°C in NYC"  // resolved from ${step1.result}
  })

→ Returns: "Successfully wrote to documents/weather.txt"

Final response generation:

  generateToolResponse(
      originalQuery: "Get the weather in NYC and save it to weather.txt in documents",
      toolName: "multi-tool plan", 
      toolResult: "Result 1: Successfully wrote to documents/weather.txt\n\nResult 2: Forecast for 40.7128, -74.006:\n\nTonight:\nTemperature: 63°F..."
  )

→ Result: "I've got the weather forecast for NYC. Tonight it's partly cloudy with a temperature of 63°F, and tomorrow is partly sunny with a high of 81°F, but there's a slight chance of rain showers. I've saved the full 7-day forecast to a file called weather.txt in your documents folder. You can check it out for more details on the rest of the week."

Chain execution flow:
weather-server:get-forecast → variable substitution → filesystem-server:write_file → response synthesis

Integration is Seamless

Our existing ChatInterface doesn't need any changes:

public ChatInterface(MCPService mcpService, LLMClient llmClient, MultiToolOrchestrator orchestrator) {
    this.mcpService = mcpService;
    this.inference = new SimpleInference(mcpService, llmClient);
    this.inference.setOrchestrator(orchestrator); // Just inject the orchestrator
    this.scanner = new Scanner(System.in);
}

Current Limitations (Being Honest)

While we've implemented the core patterns, some features are still evolving:

Partially Implemented:

Conditional execution currently falls back to sequential
Iterative execution has basic loop logic but limited condition checking

Testing Status:

CHAINED and SEQUENTIAL: Thoroughly tested and working reliably
PARALLEL: Basic implementation tested with simple scenarios
COMPETITIVE, CONDITIONAL, ITERATIVE: Limited testing - prompt adjustments may be needed based on real-world usage patterns
Complex multi-step scenarios: Some edge cases in variable resolution and dependency handling may require prompt refinement

Future Enhancements:

More sophisticated error recovery
Dynamic plan modification during execution
Performance monitoring and metrics
Prompt optimization based on comprehensive testing of all plan types across diverse query patterns

Note: The LLM-driven planning approach means that prompt engineering is an ongoing process. As we encounter more varied queries, we may need to refine the analysis and planning templates to handle edge cases and improve classification accuracy.

What's Next?

We've built it! An AI agent that can take natural language instructions and orchestrate workflows across multiple tools. The core architecture contains query analysis, multi-tool orchestration and some execution patterns.

But there's so much more to explore! This is just the foundation. We could add:

Advanced error recovery strategies
Dynamic plan modification during execution
Performance monitoring and optimization
More sophisticated LLM prompt engineering
Integration with additional MCP servers
Real-time streaming responses
Agent memory and learning capabilities

Want to contribute?

The project is open source and we'd love your help!
The complete source code is available in our GitHub repository.

This is part 7 of "From Zero to AI Agent: My Journey into Java-based Intelligent Applications" series. The complete series shows you how to build AI MCP client in Java from scratch!

Follow @gazolla for more practical AI development insights!

Building a Chat Interface: From Components to Conversation

Sebastiao Gazolla Jr — Mon, 22 Sep 2025 18:11:05 +0000

Part 6 of the "From Zero to AI Agent: My Journey into Java-based Intelligent Applications" series

We've built all the core components: MCPService for tool connections (Post 3), LLMClient for AI intelligence (Post 4), and SimpleInference for smart query processing (Posts 5). Now it's time to bring everything together into something people can actually use: a simple chat interface.

Today we'll create a minimal but functional chat application that makes interacting with MCP tools feel natural.

The Goal: Simple Conversation

Instead of complex commands, users should be able to chat naturally:

AI Assistant Ready! Type 'exit' to quit.

You: What's the weather like?
Assistant: The current weather is 22°C with partly cloudy skies.

You: Save that to weather.txt  
Assistant: I've saved the weather information to weather.txt successfully.

You: exit
Assistant: Goodbye!

Simple, clean, functional.

The ChatInterface Class

Here's our complete chat interface - much simpler than you might expect:

import java.util.Scanner;

public class ChatInterface {
    private final SimpleInference inference; // From Posts 5
    private final MCPService mcpService;     // From Post 3
    private final Scanner scanner;
    private boolean running = true;

    public ChatInterface(MCPService mcpService, LLMClient llmClient) {
        this.mcpService = mcpService;
        this.inference = new SimpleInference(mcpService, llmClient);
        this.scanner = new Scanner(System.in);
    }

    public void startChat() {
        showWelcome();

        while (running) {
            String input = getUserInput();

            if (isExitCommand(input)) {
                running = false;
                System.out.println("Goodbye!");
                continue;
            }

            processUserQuery(input);
        }

        cleanup();
    }

    private void showWelcome() {
        List<Tool> tools = mcpService.getAllAvailableTools();
        System.out.println("AI Assistant Ready! Connected to " + tools.size() + " tools.");
        System.out.println("Type 'exit' to quit.\n");
    }

    private String getUserInput() {
        System.out.print("You: ");
        return scanner.nextLine().trim();
    }

    private boolean isExitCommand(String input) {
        String lower = input.toLowerCase();
        return lower.equals("exit") || lower.equals("quit") || lower.equals("bye");
    }

    private void processUserQuery(String input) {
        if (input.isEmpty()) {
            return;
        }

        try {
            String response = inference.processQuery(input);
            System.out.println(Assistant: " + response + "\n");

        } catch (Exception e) {
            System.out.println("Sorry, I encountered an error: " + e.getMessage() + "\n");
        }
    }

    private void cleanup() {
        scanner.close();
        mcpService.close();
    }
}

That's it! One class, six methods, everything working.

Complete Application

Here's how to tie everything together:

public class ChatApp {
    public static void main(String[] args) {
        try {
            // Initialize components from previous posts
            MCPService mcpService = new MCPService();
            LLMClient llmClient = createLLMClient();

            // Start chat
            ChatInterface chat = new ChatInterface(mcpService, llmClient);
            chat.startChat();

        } catch (Exception e) {
            System.err.println("Failed to start: " + e.getMessage());
        }
    }

    private static LLMClient createLLMClient() {
        String groqKey = System.getenv("GROQ_API_KEY");
        if (groqKey != null && !groqKey.isEmpty()) {
            return LLMClientFactory.createGroqClient(groqKey);
        }

        String geminiKey = System.getenv("GEMINI_API_KEY");
        if (geminiKey != null && !geminiKey.isEmpty()) {
            return LLMClientFactory.createGeminiClient(geminiKey);
        }

        throw new RuntimeException("Set GROQ_API_KEY or GEMINI_API_KEY environment variable");
    }
}

Real Conversation Example

Here's what a real conversation looks like:

AI Assistant Ready! Connected to 8 tools.
Type 'exit' to quit.

You: what's the weather in Tokyo?
Assistant: The current weather in Tokyo is 22°C with partly cloudy skies and light winds.

You: save that to weather-tokyo.txt
Assistant: I've saved the weather information to weather-tokyo.txt successfully.

You: list my files
Assistant: I found 4 files in your current directory: weather-tokyo.txt, config.json, notes.md, and data.csv.

You: what is 2+2?
Assistant: 2+2 equals 4. This is a basic addition operation.

You: read the weather file
Assistant: The weather file contains: The current weather in Tokyo is 22°C with partly cloudy skies and light winds.

You: exit
Assistant: Goodbye!

Notice how it seamlessly handles:

Weather queries using MCP weather tools
File operations with context ("that" refers to weather data)
Direct questions using LLM knowledge
Context references between queries

Integration Highlights

Our chat interface successfully uses all components from previous posts:

MCPService (Post 3):

mcpService.getAllAvailableTools()  // Show connection status
mcpService.close()                 // Cleanup on exit
// Used internally by SimpleInference for tool execution

LLMClient (Post 4):

LLMClientFactory.createGroqClient(apiKey)  // Client creation
// Used internally by SimpleInference for intelligence

SimpleInference (Post 5):

inference.processQuery(input)  // Main query processing
// Handles analysis, tool selection, parameter extraction

Everything works together seamlessly with zero additional complexity.

Error Handling

Our simple approach to handle errors:

private void processUserQuery(String input) {
    if (input.isEmpty()) {
        return;
    }

    try {
        String response = inference.processQuery(input);
        System.out.println("Assistant: " + response + "\n");

    } catch (Exception e) {
        System.out.println("Sorry, I encountered an error: " + e.getMessage() + "\n");
    }
}

Why This Simple Approach Works

We're using a very simple approach for this project for educational purposes, aiming to facilitate understanding and learning. The chat is not our main focus but rather a complementary tool to illustrate concepts clearly.

Running the Application

Set your API key:

   export GROQ_API_KEY=your_key_here

Install MCP servers:

   npm install -g @modelcontextprotocol/server-weather
   npm install -g @modelcontextprotocol/server-filesystem

Run the chat:

   # Compile project
   mvn compile

   # Run interactive chat
   mvn exec:java -Dexec.mainClass="com.gazapps.ChatApp"

Start chatting naturally!

Current Limitations

Our simple approach has some intentional limitations:

Single user only - No multi-session support
Basic context - Only remembers last result for "that" references
Console only - No web interface (yet)
No persistence - Conversation doesn't save between sessions

These limitations keep the code simple while providing core functionality.

What's Next?

Our next post will dive into multi-tool execution, the 7th part of our "From Zero to AI Agent: My Journey into Java-based Intelligent Applications" series! We'll explore how to build a system that orchestrates complex workflows, handling real-user requests like "Get the weather in Tokyo and save it to a file" or "Check prices on three websites and tell me the cheapest" by coordinating multiple tools seamlessly. Stay tuned!

The complete source code is available in our GitHub repository.

This is part 6 of our series on building Java AI agents with the Model Context Protocol. Next up: robust error handling and advanced conversation patterns!

LLM-Powered Query Processing: From Natural Language to Tool Execution

Sebastiao Gazolla Jr — Sat, 20 Sep 2025 00:20:25 +0000

Part 5 of the "From Zero to AI Agent: My Journey into Java-based Intelligent Applications" series

We now have our MCPService connecting to real MCP tools (Post 3) and our LLM clients ready to provide intelligence (Post 4).

Today we'll build a complete query processing system that uses LLM intelligence to analyze natural language, select appropriate tools, all in one integrated approach.

The Three Types of Queries

Every user query falls into one of three categories:

Direct Answer - "What is 2+2?" → Use LLM knowledge directly
Single Tool - "What's the weather in Tokyo?" → Use one MCP tool
Multi Tool - "Get weather and save to file" → Use multiple tools (we'll cover this conceptually)

The key breakthrough: instead of building complex parsing logic, we let the LLM do the heavy lifting of understanding intent.

Query Analysis Evolution

Let's start with QueryAnalysis record:

package com.gazapps.inference;

import java.util.Map;

record QueryAnalysis(
    ExecutionType execution,
    String details, 
    Map<String, Object> parameters 
) {
    enum ExecutionType { DIRECT_ANSWER, SINGLE_TOOL, MULTI_TOOL }
}

This record captures three key components: the execution type (indicating whether the query requires a direct answer, a single tool, or multiple tools), the details (specifying the tool name for SINGLE_TOOL or reasoning for other types), and the parameters (a map of key-value pairs for tool execution, if applicable). By consolidating these elements, the QueryAnalysis record provides a structured way to represent the results of query.

Tool Schema Enhancement

Our Tool class now includes the input schema:

package com.gazapps.mcp;

import java.util.Collections;
import java.util.Map;

public class Tool {
    private final String name;
    private final String description;
    private final String serverId;
    private final Map<String, Object> inputSchema; // New: parameter definitions from MCP

    public Tool(String name, String description, String serverId, Map<String, Object> inputSchema) {
        this.name = name;
        this.description = description;
        this.serverId = serverId;
        this.inputSchema = inputSchema != null ? inputSchema : Collections.emptyMap();
    }

    public String name() { return name; }
    public String description() { return description; }
    public String serverId() { return serverId; }
    public Map<String, Object> inputSchema() { return inputSchema; } // Schema-driven parameters
}

This schema comes directly from the MCP servers and tells us exactly what parameters each tool expects, their types, and which ones are required.

Enhanced MCPService Integration

Our MCPService now loads these schemas when connecting to servers:

// In MCPService.loadServerTools()
private void loadServerTools(Server server, McpSyncClient client) {
    try {
        ListToolsResult toolsResult = client.listTools();

        for (io.modelcontextprotocol.spec.McpSchema.Tool mcpTool : toolsResult.tools()) {
            // Now we extract the input schema too
            Map<String, Object> inputSchema = mcpTool.inputSchema() != null ? 
                mcpTool.inputSchema() : Collections.emptyMap();

            Tool tool = new Tool(mcpTool.name(), mcpTool.description(), 
                               server.id(), inputSchema);
            server.addTool(tool);
        }

    } catch (Exception e) {
        System.out.println("Error loading tools for " + server.id() + ": " + e.getMessage());
    }
}

This method connects to an MCP server via the McpSyncClient, retrieves the list of available tools, and extracts each tool’s name, description, and input schema. The schema is stored as a Map to support parameter extraction in the inference process.

SimpleInference Implementation

public class SimpleInference {
    private final MCPService mcpService;
    private final LLMClient llmClient;
    private final ObjectMapper objectMapper;
    private String lastResult = "";

    public String processQuery(String query) {
        try {
            // Single LLM call does analysis + parameter extraction
            QueryAnalysis analysis = analyzeQuery(query);

            String result = switch (analysis.execution()) {
                case DIRECT_ANSWER -> generateDirectResponse(query);
                case SINGLE_TOOL -> executeSingleTool(analysis, query);
                case MULTI_TOOL -> "Multi-tool queries coming in future posts!";
            };

            // Store context for "that"/"it" references
            if (analysis.execution() == QueryAnalysis.ExecutionType.SINGLE_TOOL) {
                lastResult = result;
            }

            return result;

        } catch (Exception e) {
            return "Error: " + e.getMessage();
        }
    }
}

This implementation orchestrates the inference process by analyzing the query, routing it to the appropriate execution path (DIRECT_ANSWER, SINGLE_TOOL, or MULTI_TOOL), and managing context for conversational continuity. The processQuery method uses a single LLM call to classify the query and extract parameters, leveraging the QueryAnalysis record to determine the execution type.

Schema-Driven Tool Formatting

private String formatToolsForPrompt(List<Tool> availableTools) throws JsonProcessingException {
    StringBuilder toolList = new StringBuilder();
    for (Tool tool : availableTools) {
        toolList.append("- ").append(tool.serverId()).append(":")
                .append(tool.name()).append(" - ")
                .append(tool.description())
                .append(" (Parameters: ")
                .append(formatParameters(tool.inputSchema())) // Use real schema!
                .append(")\n");
    }
    return toolList.toString();
}

private String formatParameters(Map<String, Object> inputSchema) throws JsonProcessingException {
    Map<String, Object> properties = (Map<String, Object>) inputSchema.getOrDefault("properties", Collections.emptyMap());
    List<String> required = (List<String>) inputSchema.getOrDefault("required", Collections.emptyList());

    if (properties.isEmpty()) {
        return "None";
    }

    List<String> paramDescriptions = new ArrayList<>();
    for (Map.Entry<String, Object> entry : properties.entrySet()) {
        String paramName = entry.getKey();
        Map<String, Object> paramSchema = (Map<String, Object>) entry.getValue();
        String paramType = (String) paramSchema.getOrDefault("type", "unknown");
        String paramDesc = (String) paramSchema.getOrDefault("description", "");
        boolean isRequired = required.contains(paramName);

        StringBuilder desc = new StringBuilder(paramName + " (" + paramType);
        if (isRequired) {
            desc.append(", required");
        }
        if (!paramDesc.isEmpty()) {
            desc.append(", ").append(paramDesc);
        }
        desc.append(")");
        paramDescriptions.add(desc.toString());
    }

    return String.join(", ", paramDescriptions);
}

The formatToolsForPrompt and formatParameters methods are designed to generate a formatted string representation of available tools and their input schemas for inclusion in an LLM prompt. The formatToolsForPrompt method iterates over a list of Tool objects, constructing a string for each tool. It relies on formatParameters to process the tool's input schema, which is expected to be a JSON-like Map containing properties and required fields.

Prompt Engineering

private static final String ANALYSIS_PROMPT_TEMPLATE = """
Perform syntactic and semantic analysis on the following query to classify it, select 
            the appropriate tool (if needed), and extract all required parameters:

            Query: "%s"

            Available tools:
            %s

            Previous result: %s

            Instructions:
            1. Analyze the query's syntactic structure (e.g., identify key verbs, nouns, entities, and sentence patterns).
            2. Determine the semantic intent (e.g., what the user wants to achieve, such as getting the time, day, weather, or performing a file operation).
            3. Classify the query into one of:
               - DIRECT_ANSWER: Use for informational, broad, or general knowledge queries that don’t require specific tool actions (e.g., asking about a city, concept, or fact).
               - SINGLE_TOOL: if one tool is sufficient, specify the tool and extract its parameters.
               - MULTI_TOOL: if multiple tools are required.
            4. For SINGLE_TOOL:
               - Select the most appropriate tool based on the intent and tool description.
               - Extract ALL required parameters (e.g., location, date, path, filename).
               - Handle special cases:
                 - If the query refers to "that" or "it", use the previous result as context.
                 - If a parameter is missing and cannot be inferred, use reasonable defaults.
            5. Respond in this EXACT format:
               For DIRECT_ANSWER:
               DIRECT_ANSWER: [reason]
               For SINGLE_TOOL:
               SINGLE_TOOL: [server_id]:[tool_name]
               REASONING: [why you chose this tool]
               PARAMS: {"param1": "value1", "param2": "value2"}
               For MULTI_TOOL:
               MULTI_TOOL: multiple tools needed
            6. Don't explain anything.   
    """;

This prompt instructs the LLM to perform syntactic and semantic analysis to classify queries, select tools, and extract parameters. It prioritizes DIRECT_ANSWER for informational queries, ensures tools are only used for explicit actions, and uses context from previous results only when relevant.

Response Parsing

Our parsing handles the structured LLM response:

private QueryAnalysis parseAnalysis(String response) {
    String cleaned = response.trim();
    String[] lines = cleaned.split("\n");

    if (cleaned.startsWith("DIRECT_ANSWER:")) {
        String reasoning = cleaned.substring("DIRECT_ANSWER:".length()).trim();
        return new QueryAnalysis(QueryAnalysis.ExecutionType.DIRECT_ANSWER, reasoning, null);
    }

    if (cleaned.startsWith("SINGLE_TOOL:")) {
        String toolLine = lines[0].substring("SINGLE_TOOL:".length()).trim();
        String[] toolParts = toolLine.split(":");
        if (toolParts.length != 2) {
            return new QueryAnalysis(QueryAnalysis.ExecutionType.DIRECT_ANSWER, "Invalid tool format", null);
        }

        String serverId = toolParts[0];
        String toolName = toolParts[1];
        Map<String, Object> parameters = new HashMap<>();

        // Extract parameters from PARAMS line
        for (String line : lines) {
            if (line.startsWith("PARAMS:")) {
                String paramLine = line.substring("PARAMS:".length()).trim();
                if (!paramLine.equals("{}")) {
                    try {
                        parameters = objectMapper.readValue(paramLine, Map.class);
                    } catch (Exception e) {
                        System.out.println("Failed to parse parameters: " + e.getMessage());
                    }
                }
                break;
            }
        }

        return new QueryAnalysis(QueryAnalysis.ExecutionType.SINGLE_TOOL, serverId + ":" + toolName, parameters);
    }

    // Fallback to direct answer
    return new QueryAnalysis(QueryAnalysis.ExecutionType.DIRECT_ANSWER, "Could not parse", null);
}

This method parses the LLM’s response to extract the execution type, details (tool name or reasoning), and parameters, producing a QueryAnalysis record.

Complete Integration Example

Here's how everything works together for a real query:

Input: "What's the weather tomorrow in Tokyo?"

Step 1 - LLM receives prompt with schema:

Available tools:
- weather-server:get_current_weather - Get current weather (Parameters: location (string, required), units (string, optional))

Step 2 - LLM analyzes and responds:

SINGLE_TOOL: weather-server:get_current_weather
REASONING: User wants weather forecast for specific location and date
PARAMS: {"location": "Tokyo", "units": "metric"}

Step 3 - Execute tool:

ToolResult result = mcpService.callTool("weather-server", "get_current_weather", 
    Map.of("location", "Tokyo", "units", "metric"));

Step 4 - Generate natural response:

String response = generateToolResponse(originalQuery, "get_current_weather", result.content());
// Returns: "Tomorrow's weather in Tokyo will be 22°C with partly cloudy skies."

Structured Prompt Templates

We organize prompts in a clean template system:

private static final class PromptTemplates {
    // Analysis prompt for query classification and parameter extraction
    public static String getAnalysisPrompt(String query, String toolList) {
        return ANALYSIS_PROMPT_TEMPLATE.formatted(query, toolList);
    }

    // Direct answer prompt for knowledge-based queries
    public static String getDirectAnswerPrompt(String query) {
        return DIRECT_ANSWER_PROMPT_TEMPLATE.formatted(query);
    }

    // Tool response prompt for natural conversation
    public static String getToolResponsePrompt(String query, String toolName, String toolResult) {
        return TOOL_RESPONSE_PROMPT_TEMPLATE.formatted(query, toolName, toolResult);
    }

    // Fallback prompt when tools fail
    public static String getFallbackPrompt(String query) {
        return FALLBACK_PROMPT_TEMPLATE.formatted(query);
    }
}

This keeps prompts organized, reusable, and easy to modify.

Multi-Tool Execution (Conceptual Overview)

Queries that require multiple tools can be approached in various ways, depending on the nature of the task. Below are some theoretical patterns for handling such queries:

1. Sequential Dependent Tasks

Execute tools in a specific order, where the output of one tool serves as input for the next.
Example: "Get the weather in Tokyo and save it to a file" requires first querying the weather and then saving the result.

2. Parallel Tasks with Summarization

Execute multiple tools simultaneously and combine their results into a consolidated response.
Example: "Check the weather in Tokyo, Osaka, and Kyoto and summarize the conditions" involves parallel calls and a final analysis.

3. Conditionally Dependent Tasks

Select the next tool based on the result of a previous tool.
Example: "If it's raining in Tokyo, get the extended forecast; otherwise, suggest outdoor activities."

4. Chained Tasks with Transformation

Each tool transforms the data in a specific way, forming a pipeline.
Example: "Extract text from a PDF, translate it to Spanish, and send it via email."

5. Parallel Tasks with Competitive Aggregation

Execute multiple tools in parallel and select the best result based on criteria like cost or quality.
Example: "Check the price of a product on three websites and recommend the cheapest."

6. Iterative Tasks with Feedback

Execute tools repeatedly, refining results based on feedback.
Example: "Write a draft, check its grammar, and adjust until it's perfect."

These patterns demonstrate the flexibility of multi-tool usage. Implementation involves challenges such as query decomposition, state management between tools, and result consolidation, which we'll cover in future posts.

Complete Usage Example

public class InferenceDemo {
    public static void main(String[] args) {
        MCPService mcpService = new MCPService(); // Connects to real MCP servers
        LLMClient llmClient = LLMClientFactory.createGroqClient(System.getenv("GROQ_API_KEY"));

        SimpleInference inference = new SimpleInference(mcpService, llmClient);

        // Test schema-driven parameter extraction
        System.out.println("=== Schema-Driven Query Processing Demo ===\n");

        testQuery(inference, "What is 2+2?");
        testQuery(inference, "What's the weather in NYC?");
        testQuery(inference, "What's the day today in nyc?");
        testQuery(inference, "tell me more about nyc");

        mcpService.close();
    }

    private static void testQuery(SimpleInference inference, String query) {
        System.out.println("Query: " + query);
        String response = inference.processQuery(query);
        System.out.println("Response: " + response);
        System.out.println();
    }
}

Sample Output:

=== Schema-Driven Query Processing Demo ===

Query: What is 2+2?
Response: 2+2 equals 4. This is a basic addition operation.

Query: What's the weather in NYC?
Response: The current weather in NYC is 22°C with partly cloudy skies and light winds.

Query: What's the day today in nyc?
Response: It's Friday, September 19th in New York City.

Query: tell me more about nyc
Response: The city that never sleeps! New York City (NYC) is a global hub for culture, entertainment, finance, and innovation. Located in the state of New York, NYC is the most populous city in the United States, with over 8.4 million people calling it home.

What We've Built

The SimpleInference class processes user queries by analyzing their intent through LLM reasoning, extracts parameters using schema definitions from MCP servers, combines analysis and extraction in a single call, employs structured prompt templates, handles errors with fallback mechanisms.

What's Next?

In our next post, we'll build the conversational interface that ties everything together - a chat application where users can naturally interact with all our MCP tools through the intelligent query processing we built today.

The complete source code is available in our GitHub repository. Our query processing system now rivals commercial AI assistants in capability while remaining simple and maintainable!

This is part 5 of "From Zero to AI Agent: My Journey into Java-based Intelligent Applications" series. Next up: building the conversational chat interface!

Connecting to LLMs: Building a Simple HTTP Client for AI Integration

Sebastiao Gazolla Jr — Fri, 19 Sep 2025 00:20:26 +0000

Part 4 of the "From Zero to AI Agent: My Journey into Java-based Intelligent Applications" series

Now that we have our MCPService handling tool connections, we need to add the "intelligence" to our agent. This means connecting to Large Language Models (LLMs) that will help us understand user queries and decide which tools to use.

Today we'll build a HTTP client that can talk to popular LLM providers like Groq and Google Gemini. No complex libraries, just modern Java HTTP calls with clean JSON parsing using records and Jackson.

Why These LLM Providers?

These providers are chosen for their generous free tiers, offering high token quotas ideal for prototyping and learning.

Groq: Fast inference with Llama models, great for real-time apps. Its free tier supports up to 131,072 tokens per minute, allowing millions daily for rapid iteration.

Google Gemini: Strong reasoning for complex queries. Its free tier offers up to 1 million tokens per context window and high daily quotas, supporting token-heavy tasks like code generation.

Both: Simple REST APIs, good for learning and for building and testing AI integrations.

The LLM Client Interface

Let's start with a simple interface that any LLM provider can implement:

public interface LLMClient {
    String send(String prompt) throws Exception;
    String getProviderName();
    boolean isHealthy();
}

Building the HTTP Foundation

Here's our base class with all the common HTTP functionality:

import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;
import com.fasterxml.jackson.databind.ObjectMapper;

public abstract class BaseLLMClient implements LLMClient {
    protected final HttpClient httpClient = HttpClient.newBuilder()
        .connectTimeout(Duration.ofSeconds(30))
        .build();

    protected final ObjectMapper objectMapper = new ObjectMapper()
        .configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false);

    protected final String apiKey;

    public BaseLLMClient(String apiKey) {
        this.apiKey = apiKey;
        if (apiKey == null || apiKey.isBlank()) {
            throw new IllegalArgumentException("API key is required");
        }
    }

    @Override
    public String send(String prompt) throws RuntimeException {
        if (prompt == null || prompt.isBlank()) {
            throw new RuntimeException("Prompt cannot be null or empty");
        }

        try {
            HttpRequest request = buildRequest(prompt);
            HttpResponse<String> response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());

            if (response.statusCode() != 200) {
                throw new RuntimeException("API error: status=%d, body=%s".formatted(
                    response.statusCode(), response.body()));
            }

            return extractAnswer(response.body()).trim();

        } catch (Exception e) {
            throw new RuntimeException("Error sending request: " + e.getMessage(), e);
        }
    }

    protected abstract HttpRequest buildRequest(String prompt) throws Exception;
    protected abstract String extractAnswer(String jsonResponse) throws Exception;

    @Override
    public boolean isHealthy() {
        try {
            send("Hello");
            return true;
        } catch (Exception e) {
            return false;
        }
    }
}

The BaseLLMClient Java class is an abstract base for interacting with large language model (LLM) APIs. The class requires an API key, validated in the constructor, and provides a send method to transmit a prompt to the LLM, handling HTTP requests and responses. The buildRequest method, also abstract, must be implemented by subclasses to define the HTTP request structure.

Groq Implementation with Records

Groq uses an OpenAI-compatible API. Here's our clean implementation using Java records:

import java.net.URI;
import java.net.http.HttpRequest;
import java.util.List;

public class GroqClient extends BaseLLMClient {
    private static final String GROQ_URL = "https://api.groq.com/openai/v1/chat/completions";
    private final String model;

    public GroqClient(String apiKey, String model) {
        super(apiKey);
        this.model = model != null ? model : "llama-3.3-70b-versatile";
    }

    @Override
    protected HttpRequest buildRequest(String prompt) throws Exception {
        String jsonBody = objectMapper.writeValueAsString(
            new GroqRequest(
                model,
                List.of(new GroqRequest.Message("user", prompt)),
                1000,
                0.1
            )
        );

        return HttpRequest.newBuilder(URI.create(GROQ_URL))
            .header("Content-Type", "application/json")
            .header("Authorization", "Bearer %s".formatted(apiKey))
            .POST(HttpRequest.BodyPublishers.ofString(jsonBody))
            .build();
    }

    @Override
    protected String extractAnswer(String jsonResponse) throws Exception {
        GroqResponse response = objectMapper.readValue(jsonResponse, GroqResponse.class);
        List<GroqResponse.Choice> choices = response.choices();

        if (choices == null || choices.isEmpty()) {
            throw new IllegalStateException("No choices in response");
        }

        return choices.getFirst().message().content();
    }

    @Override
    public String getProviderName() {
        return "Groq (%s)".formatted(model);
    }
}

// Clean record definitions for JSON mapping
record GroqRequest(
    String model,
    List<Message> messages,
    int max_tokens,
    double temperature
) {
    record Message(String role, String content) {}
}

record GroqResponse(List<Choice> choices) {
    record Choice(Message message) {}
    record Message(String content) {}
}

Google Gemini Implementation

Gemini has a different API structure, but the pattern is the same:

import java.net.URI;
import java.net.http.HttpRequest;
import java.util.List;

public class GeminiClient extends BaseLLMClient {
    private static final String BASE_URL = "https://generativelanguage.googleapis.com/v1beta/models/";
    private final String model;
    private final String endpointUrl;

    public GeminiClient(String apiKey, String model) {
        super(apiKey);
        this.model = model != null ? model : "gemini-1.5-flash";
        this.endpointUrl = "%s%s:generateContent?key=%s".formatted(BASE_URL, this.model, apiKey);
    }

    @Override
    protected HttpRequest buildRequest(String prompt) throws Exception {
        String jsonBody = objectMapper.writeValueAsString(
            new GeminiRequest(
                List.of(new GeminiRequest.Content(List.of(new GeminiRequest.Part(prompt)))),
                new GeminiRequest.GenerationConfig(0.1, 1000)
            )
        );

        return HttpRequest.newBuilder(URI.create(endpointUrl))
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(jsonBody))
            .build();
    }

    @Override
    protected String extractAnswer(String jsonResponse) throws Exception {
        GeminiResponse response = objectMapper.readValue(jsonResponse, GeminiResponse.class);
        List<GeminiResponse.Candidate> candidates = response.candidates();

        if (candidates == null || candidates.isEmpty()) {
            throw new IllegalStateException("No candidates in response");
        }

        List<GeminiResponse.Part> parts = candidates.getFirst().content().parts();
        if (parts == null || parts.isEmpty()) {
            throw new IllegalStateException("No parts in content");
        }

        return parts.getFirst().text();
    }

    @Override
    public String getProviderName() {
        return "Google Gemini (%s)".formatted(model);
    }
}

// Gemini request/response records
record GeminiRequest(
    List<Content> contents,
    GenerationConfig generationConfig
) {
    record Content(List<Part> parts) {}
    record Part(String text) {}
    record GenerationConfig(double temperature, int maxOutputTokens) {}
}

record GeminiResponse(List<Candidate> candidates) {
    record Candidate(Content content) {}
    record Content(String role, List<Part> parts) {}
    record Part(String text) {}
}

Simple Factory for Easy Creation

Keep client creation clean and simple:

public class LLMClientFactory {

    public static LLMClient createGroqClient(String apiKey) {
        return new GroqClient(apiKey, "llama-3.3-70b-versatile");
    }

    public static LLMClient createGeminiClient(String apiKey) {
        return new GeminiClient(apiKey, "gemini-1.5-flash");
    }
}

Usage Example

Here's how simple it is to use our LLM clients:

public class LLMClientDemo {
    public static void main(String[] args) {
        testGroq();
        testGemini();
    }

    private static void testGroq() {
        try {
            LLMClient groq = LLMClientFactory.createGroqClient(System.getenv("GROQ_API_KEY"));

            System.out.println("Testing " + groq.getProviderName());
            String response = groq.send("What is 2+2? Answer briefly.");
            System.out.println("Response: " + response);
            System.out.println("Healthy: " + groq.isHealthy());
            System.out.println();

        } catch (Exception e) {
            System.out.println("Groq test failed: " + e.getMessage());
        }
    }

    private static void testGemini() {
        try {
            LLMClient gemini = LLMClientFactory.createGeminiClient(System.getenv("GEMINI_API_KEY"));

            System.out.println("Testing " + gemini.getProviderName());
            String response = gemini.send("What is the capital of France? Answer briefly.");
            System.out.println("Response: " + response);
            System.out.println("Healthy: " + gemini.isHealthy());
            System.out.println();

        } catch (Exception e) {
            System.out.println("Gemini test failed: " + e.getMessage());
        }
    }
}

Sample Output:

Testing Groq (llama-3.3-70b-versatile)
Response: 2+2 = 4
Healthy: true

Testing Google Gemini (gemini-1.5-flash)
Response: The capital of France is Paris.
Healthy: true

Environment Setup

Make sure to set your API keys as environment variables:

# Windows
set GROQ_API_KEY=your_groq_key_here
set GEMINI_API_KEY=your_gemini_key_here

# Unix/MacOS
export GROQ_API_KEY=your_groq_key_here
export GEMINI_API_KEY=your_gemini_key_here

What's Next?

In our next post, we'll build a simple inference strategy that bridges the gap between user queries and tool execution. We'll keep it minimal and focused - just enough to understand the core concepts.

The clean HTTP foundation we built today will power all the intelligent features in our Java MCP client!

This is part 4 of our series "From Zero to AI Agent: My Journey into Java-based Intelligent Applications". Next up: inference strategies that bring it all together!

Building the Heart of Your Java MCP Client: The MCPService Core

Sebastiao Gazolla Jr — Thu, 18 Sep 2025 02:01:39 +0000

Part 3 of the "From Zero to AI Agent: My Journey into Java-based Intelligent Applications" series

In our previous post, we created our first MCP client in 30 lines. Now it's time to build something more complex for a real application: the MCPService. This service handles everything: connecting to servers, managing tools, executing commands, and keeping everything healthy.

Today we'll build a service that can handle multiple MCP servers simultaneously. Let's try to make it as simple as possible.

The Core MCPService Class

Let's start with the essential structure and some common MCP servers hardcoded for simplicity:

import java.util.*;
import java.util.concurrent.ConcurrentHashMap;
import io.modelcontextprotocol.client.McpClient;
import io.modelcontextprotocol.client.McpSyncClient;
import io.modelcontextprotocol.spec.McpSchema.*;

public class MCPService {
    private final Map<String, Server> servers;
    private final Map<String, McpSyncClient> clients;

    public MCPService() {
        this.servers = new ConcurrentHashMap<>();
        this.clients = new ConcurrentHashMap<>();

        initializeServers();
    }

    private void initializeServers() {
        // Hardcoded servers for learning - in production, load from config
        connectToWeatherServer();
        connectToFilesystemServer();
        connectToTimeServer();
    }
}

It maintains two thread-safe ConcurrentHashMaps: one storing references to Server objects, each identified by a unique string key such as a server ID or name, and another holding McpSyncClient instances, typically keyed to match their respective servers, for synchronous communication within the framework.

Hardcoded Server Connections

Let's implement the three common MCP servers:

private void connectToWeatherServer() {
    try {
        String[] command = {"npx", "-y", "@modelcontextprotocol/server-weather"};
        McpSyncClient client = createClient("weather-server", command);

        if (client != null) {
            Server server = new Server("weather-server", "Weather", true);
            loadServerTools(server, client);

            servers.put("weather-server", server);
            clients.put("weather-server", client);

            System.out.println("✅ Weather server connected with " + server.getToolCount() + " tools");
        }
    } catch (Exception e) {
        System.out.println("❌ Weather server failed: " + e.getMessage());
    }
}

private void connectToFilesystemServer() {
    try {
        String[] command = {"npx", "-y", "@modelcontextprotocol/server-filesystem", "/tmp"};
        McpSyncClient client = createClient("filesystem-server", command);

        if (client != null) {
            Server server = new Server("filesystem-server", "Filesystem", true);
            loadServerTools(server, client);

            servers.put("filesystem-server", server);
            clients.put("filesystem-server", client);

            System.out.println("✅ Filesystem server connected with " + server.getToolCount() + " tools");
        }
    } catch (Exception e) {
        System.out.println("❌ Filesystem server failed: " + e.getMessage());
    }
}

private void connectToTimeServer() {
    try {
        String[] command = {"uvx", "mcp-server-time"};
        McpSyncClient client = createClient("time-server", command);

        if (client != null) {
            Server server = new Server("time-server", "Time", true);
            loadServerTools(server, client);

            servers.put("time-server", server);
            clients.put("time-server", client);

            System.out.println("✅ Time server connected with " + server.getToolCount() + " tools");
        }
    } catch (Exception e) {
        System.out.println("❌ Time server failed: " + e.getMessage());
    }
}

Each server connection is explicit and easy to understand. Weather and filesystem use Node.js (npx), while time server uses Python (uvx).

Client Creation

private McpSyncClient createClient(String serverId, String[] command) {
    try {
        // Handle Windows vs Unix commands
        String[] fullCommand;
        if (System.getProperty("os.name").toLowerCase().contains("win")) {
            fullCommand = new String[command.length + 2];
            fullCommand[0] = "cmd.exe";
            fullCommand[1] = "/c";
            System.arraycopy(command, 0, fullCommand, 2, command.length);
        } else {
            fullCommand = command;
        }

        ServerParameters serverParams = ServerParameters.builder(fullCommand[0])
            .args(Arrays.copyOfRange(fullCommand, 1, fullCommand.length))
            .build();

        StdioClientTransport transport = new StdioClientTransport(serverParams);

        McpSyncClient client = McpClient.sync(transport)
            .requestTimeout(Duration.ofSeconds(15))
            .build();

        // Initialize MCP protocol
        client.initialize();

        return client;

    } catch (Exception e) {
        System.out.println("Failed to create client for " + serverId + ": " + e.getMessage());
        return null;
    }
}

The createClient creates an McpSyncClient for a server identified by serverId, launching a subprocess with the given command array. It formats the command for Windows (prefixing cmd.exe /c) or Unix (using it as-is), builds ServerParameters for the subprocess, and uses StdioClientTransport to manage stdio communication.

Tool Discovery and Loading

Once connected, we need to discover what tools the server offers:

private void loadServerTools(Server server, McpSyncClient client) {
    try {
        ListToolsResult toolsResult = client.listTools();

        for (io.modelcontextprotocol.spec.McpSchema.Tool mcpTool : toolsResult.tools()) {
            Tool tool = new Tool(mcpTool.name(), mcpTool.description(), server.id());
            server.addTool(tool);
        }

    } catch (Exception e) {
        System.out.println("Error loading tools for " + server.id() + ": " + e.getMessage());
    }
}

The loadServerTools method invokes the listTools method on the client to retrieve a List of Tools. The method iterates over these tools, creating a new Tool object and then adds it to the server’s internal tool collection.

Tool Execution: Where the Action Happens

public ToolResult callTool(String serverId, String toolName, Map<String, Object> args) {
    // Validate inputs
    Server server = servers.get(serverId);
    if (server == null) {
        return ToolResult.error("Server not found: " + serverId);
    }

    if (!server.isConnected()) {
        return ToolResult.error("Server is not connected");
    }

    Tool tool = server.getTool(toolName);
    if (tool == null) {
        return ToolResult.error("Tool not found: " + toolName);
    }

    // Execute with retry logic
    McpSyncClient client = clients.get(server.id());

    CallToolRequest request = new CallToolRequest(tool.name(), args != null ? args : Map.of());
    CallToolResult result = client.callTool(request);

    if (result.isError() != null && result.isError()) {
        throw new Exception("Tool execution failed: " + result.toString());
    }

    String content = extractContent(result.content());
    return ToolResult.success(tool, content);
}

The callTool method in MCPService executes a tool on a server by serverId, using toolName and optional args. It validates the server’s existence, connection, and tool availability, returning ToolResult.error if any check fails. Using the McpSyncClient from the clients map, it sends a CallToolRequest and throws an Exception if the CallToolResult indicates an error. Otherwise, it extracts the result’s content and returns ToolResult.success with the tool and content.

Content Extraction: Making Sense of Results

MCP returns content in various formats. Let's make it simple:

private String extractContent(List<Content> contentList) {
    if (contentList == null || contentList.isEmpty()) {
        return "No content returned";
    }

    for (Content content : contentList) {
        if (content instanceof TextContent textContent) {
            if (textContent.text() != null && !textContent.text().trim().isEmpty()) {
                return textContent.text();
            }
        }
    }

    return "No text content found";
}

We prefer text content, but handle cases where there's no content gracefully.

Simplified Data Structures for MCP Framework

Below are the data structures used in our code to manage tools, servers, and tool execution results efficiently.

public record Tool(String name, String description, String serverId) {
    // Records automatically generate constructor, getters, equals, hashCode, toString
}

public static class Server {
    private final String id;
    private final String name;
    private boolean connected;
    private final List<Tool> tools;

    public Server(String id, String name, boolean connected) {
        this.id = id;
        this.name = name;
        this.connected = connected;
        this.tools = new ArrayList<>();
    }

    public void addTool(Tool tool) {
        tools.add(tool);
    }

    public Tool getTool(String toolName) {
        return tools.stream()
            .filter(tool -> tool.name().equals(toolName))
            .findFirst()
            .orElse(null);
    }

    public int getToolCount() {
        return tools.size();
    }

    // Getters using record-style naming
    public String id() { return id; }
    public String name() { return name; }
    public boolean isConnected() { return connected; }
    public List<Tool> getTools() { return List.copyOf(tools); }
}

The Tool structure is an immutable data container that stores a tool’s name, description, and associated server ID.
The Server structure, implemented as a class due to its mutable nature, manages a server’s ID, name, connection status, and a list of tools. It supports dynamic updates by allowing tools to be added and the connection status to be modified, with methods to retrieve a tool by name, count tools, and access server properties safely via immutable getters.

The ToolResult Record

Using a record with static factory methods for clean result handling:

public record ToolResult(
    boolean success,
    Tool tool,
    String content,
    String message,
    Exception error
) {
    public static ToolResult success(Tool tool, String content) {
        return new ToolResult(true, tool, content, "Success", null);
    }

    public static ToolResult error(String message) {
        return new ToolResult(false, null, null, message, null);
    }

    public static ToolResult error(String message, Exception error) {
        return new ToolResult(false, null, null, message, error);
    }
}

The ToolResult structure encapsulates the outcome of a tool execution, holding a success flag, the executed tool, output content, a message, and an optional error.

Utility Methods: The Convenience Layer

A few helper methods make the service much easier to use:

public List<Tool> getAllAvailableTools() {
    return servers.values().stream()
        .filter(Server::isConnected)
        .flatMap(server -> server.getTools().stream())
        .toList();
}

public boolean isServerConnected(String serverId) {
    Server server = servers.get(serverId);
    return server != null && server.isConnected();
}

public Map<String, Server> getConnectedServers() {
    return servers.entrySet().stream()
        .filter(entry -> entry.getValue().isConnected())
        .collect(Collectors.toMap(Map.Entry::getKey, Map.Entry::getValue));
}

public void close() {
    new ArrayList<>(servers.keySet()).forEach(this::disconnectServer);
    servers.clear();
    clients.clear();
}

private void disconnectServer(String serverId) {
    try {
        McpSyncClient client = clients.remove(serverId);
        if (client != null) {
            client.close();
        }

        Server server = servers.get(serverId);
        if (server != null) {
            System.out.println("Server " + serverId + " disconnected");
        }

    } catch (Exception e) {
        System.out.println("Error disconnecting server " + serverId + ": " + e.getMessage());
    }
}

Usage Example

Here's how to use our MCPService:

public class MCPServiceDemo {
    public static void main(String[] args) {
        // Create and initialize service
        MCPService mcpService = new MCPService();

        // List available tools
        List<Tool> tools = mcpService.getAllAvailableTools();
        System.out.println("\nAvailable tools: " + tools.size());
        for (Tool tool : tools) {
            System.out.println("  • " + tool.name() + " (" + tool.serverId() + ")");
        }

        // Test weather tool
        Map<String, Object> weatherArgs = Map.of("location", "Tokyo");
        ToolResult weatherResult = mcpService.callTool("weather-server", "get_weather", weatherArgs);

        if (weatherResult.success()) {
            System.out.println("\nWeather: " + weatherResult.content());
        } else {
            System.out.println("\nWeather error: " + weatherResult.message());
        }

        // Test filesystem tool
        Map<String, Object> fileArgs = Map.of("path", "/tmp");
        ToolResult fileResult = mcpService.callTool("filesystem-server", "list_directory", fileArgs);

        if (fileResult.success()) {
            System.out.println("\nFiles: " + fileResult.content());
        } else {
            System.out.println("\nFile error: " + fileResult.message());
        }

        // Cleanup
        mcpService.close();
    }
}

Sample Output:

✅ Weather server connected with 2 tools
✅ Filesystem server connected with 6 tools
❌ Time server failed: uvx not found

Available tools: 8
  • get_weather (weather-server)
  • get_forecast (weather-server)
  • read_file (filesystem-server)
  • write_file (filesystem-server)
  • list_directory (filesystem-server)
  • create_directory (filesystem-server)
  • delete_file (filesystem-server)
  • move_file (filesystem-server)

Weather: Current temperature in Tokyo: 22°C, partly cloudy

Files: ["file1.txt", "file2.txt", "directory1"]

Prerequisites for Running

Before running this code, make sure you have:

# For weather and filesystem servers (Node.js)
npm install -g npx

# For time server (Python)
pip install uv
# or
pipx install uv

What's Next?

In the next post, we’ll build an HTTP client layer to connect our MCPService to Large Language Models like Groq and Gemini, enabling real-time AI-driven responses.

With MCPService, we’ve created a robust foundation for managing multiple MCP servers and their tools. Now, it’s time to bring AI into the mix!

This is part 3 of our series "From Zero to AI Agent: My Journey into Java-based Intelligent Applications". Next up: connecting to LLMs with HTTP clients!

MCP Fundamentals: Your First Java Client in 30 Lines of Code

Sebastiao Gazolla Jr — Tue, 16 Sep 2025 19:07:56 +0000

In the previous post I talked about what MCP is conceptually. Today I want to show you exactly how it works by walking through the simplest possible MCP client in Java. We're going to create a file using just 30 lines of code, but more importantly, understand what each line does and why.

The Complete Code First

Let me show you the entire working example, then we'll break it down piece by piece:

package com.example.mcp;
import java.time.Duration;
import java.util.Map;

import io.modelcontextprotocol.client.McpClient;
import io.modelcontextprotocol.client.McpSyncClient;
import io.modelcontextprotocol.client.transport.ServerParameters;
import io.modelcontextprotocol.client.transport.StdioClientTransport;
import io.modelcontextprotocol.spec.McpSchema.CallToolRequest;
import io.modelcontextprotocol.spec.McpSchema.CallToolResult;

public class SimpleClientMCP {
    public static void main(String[] args) {
        int requestTimeoutSeconds = 30;
        String basePath = System.getProperty("user.home") + "/Documents";

        StdioClientTransport stdioTransport = new StdioClientTransport(
            ServerParameters.builder("cmd.exe")
                .args("/c", "npx @modelcontextprotocol/server-filesystem " + basePath)
                .build());

        McpSyncClient client = McpClient.sync(stdioTransport)
            .requestTimeout(Duration.ofSeconds(requestTimeoutSeconds))
            .build();

        client.initialize();

        CallToolRequest request = new CallToolRequest("write_file", Map.of(
            "path", basePath + "\\test.txt",
            "content", "Olá!\n\nThis is a sample using Model Context Protocol."
        ));

        CallToolResult result = client.callTool(request);
        System.out.println(result.toString());
    }
}

When you run this, it creates a file called test.txt in your Documents folder with some content. Simple, right? But there's a lot happening under the hood.

The MCP Architecture in This Example

Before diving into the code, let's understand what's actually happening:

Your Java Application (the client, called host application in the MCP documentation)
MCP Protocol (the communication layer, the MCP Client)
Filesystem Server (the tool provider)

[Java App] ←→ [MCP Protocol] ←→ [Filesystem Server] ←→ [Your Files]

Your Java code doesn't directly touch the filesystem. It talks to an MCP server that provides filesystem tools, and that server does the actual file operations.

Breaking Down Each Section

The Imports: What You Need

import io.modelcontextprotocol.client.McpClient;
import io.modelcontextprotocol.client.McpSyncClient;
import io.modelcontextprotocol.client.transport.ServerParameters;
import io.modelcontextprotocol.client.transport.StdioClientTransport;
import io.modelcontextprotocol.spec.McpSchema.CallToolRequest;
import io.modelcontextprotocol.spec.McpSchema.CallToolResult;

These imports give you the core MCP functionality:

McpClient/McpSyncClient: The main client that handles MCP communication.
ServerParameters/StdioClientTransport: How to connect to MCP servers
CallToolRequest/CallToolResult: How to call tools and get results

Setting Up Basic Configuration

int requestTimeoutSeconds = 30;
String basePath = System.getProperty("user.home") + "/Documents";

This is straightforward setup. The timeout prevents your application from hanging if the MCP server doesn't respond. The basePath determines where the filesystem server can operate - it's both a working directory and a security boundary.

Creating the Transport: How to Talk to the Server

StdioClientTransport stdioTransport = new StdioClientTransport(
    ServerParameters.builder("cmd.exe")
        .args("/c", "npx @modelcontextprotocol/server-filesystem " + basePath)
        .build());

This is where the magic starts. Let's break it down:

STDIO Transport means we're communicating with a subprocess through standard input/output. It's like having a conversation through a pipe.

ServerParameters.builder("cmd.exe") tells the transport to run a Windows command. On Linux/Mac, you'd use "sh" or "bash".

.args("/c", "npx @modelcontextprotocol/server-filesystem " + basePath) specifies the actual command to run. This starts the filesystem MCP server and tells it to operate in your Documents folder.

What happens here is:

Your Java app starts a subprocess: cmd.exe /c npx @modelcontextprotocol/server-filesystem C:\Users\YourName\Documents
That subprocess runs the Node.js filesystem server
The server starts up and waits for MCP protocol messages
Your Java app can now talk to it through stdin/stdout

Building the Client: The MCP Connection

McpSyncClient client = McpClient.sync(stdioTransport)
    .requestTimeout(Duration.ofSeconds(requestTimeoutSeconds))
    .build();

McpClient.sync() creates a synchronous client. There's also an async version, but sync is easier to understand and debug.
.requestTimeout() sets how long to wait for responses. MCP operations can involve file I/O or network calls, so timeouts are important.
.build() creates the actual client instance. At this point, the subprocess is running but the MCP handshake hasn't happened yet.

Initializing the Connection: The MCP Handshake

client.initialize();

This single line does a lot:

Protocol Negotiation: Client and server agree on MCP version
Capability Exchange: They tell each other what features they support
Authentication (if needed): Some servers require credentials
Tool Discovery: The server tells the client what tools are available

After initialize() completes, your client knows exactly what the server can do.

Making the Tool Call: The Actual Work

CallToolRequest request = new CallToolRequest("write_file", Map.of(
    "path", basePath + "\\test.txt",
    "content", "Olá!\n\nThis is a sample using Model Context Protocol."
));

CallToolResult result = client.callTool(request);

CallToolRequest specifies:

Tool name: "write_file" (this must match exactly what the server provides)
Parameters: A map of parameter names to values

The filesystem server expects these specific parameters for write_file:

path: Where to create the file
content: What to put in the file

client.callTool() sends this request to the server and waits for the response.

Understanding the Result

System.out.println(result.toString());

The result contains:

Success/failure status
Content: What the tool returned (usually a success message)
Error details (if something went wrong)

For a successful file write, you'll see something like:

CallToolResult{content=[TextContent{text=File written successfully}], isError=false}

What's Happening Under the Hood

When you call client.callTool(request), here's the actual flow:

Your Java app serializes the request to JSON
Transport layer sends JSON over stdin to the subprocess
Filesystem server receives and parses the JSON
Server validates the parameters (path exists? content is valid?)
Server performs the actual file operation
Server sends response back as JSON over stdout
Transport layer receives the JSON response
Your Java app deserializes it to CallToolResult

All of this happens transparently. You just see the high-level tool call.

Why This Architecture Matters

Security: The filesystem server only operates in the directory you specify. It can't access your entire system.

Isolation: If the server crashes, it doesn't take down your Java application.

Language Independence: The server is written in Node.js, but your client is Java. MCP bridges different technologies.

Tool Reusability: Other applications can use the same filesystem server. You're not writing filesystem code; you're using a standard tool.

Common Issues and Solutions

"Command not found" errors: Make sure you have Node.js and npm installed. The npx command needs to be in your PATH.

Permission errors: The server can only access the directory you specify in basePath. Make sure that directory exists and is writable.

Timeout errors: Some operations (especially on network drives) can be slow. Increase requestTimeoutSeconds if needed.

Path separator issues: On Windows, use \\ or / in paths. The File.separator constant is helpful for cross-platform code.

Extending This Example

Want to try more tools? The filesystem server provides several:

// Read a file
CallToolRequest readRequest = new CallToolRequest("read_file", Map.of(
    "path", basePath + "\\test.txt"
));

// List directory contents
CallToolRequest listRequest = new CallToolRequest("list_files", Map.of(
    "path", basePath
));

// Move a file
CallToolRequest moveRequest = new CallToolRequest("move_file", Map.of(
    "source", basePath + "\\test.txt",
    "destination", basePath + "\\renamed.txt"
));

Each tool has different parameters, but the calling pattern is the same.

What We've Learned

This simple example demonstrates the core MCP concepts:

Transport: How client and server communicate (STDIO in this case)
Initialization: The protocol handshake that establishes the connection
Tool Calls: The request/response pattern for using server functionality
Error Handling: How failures are communicated back to the client

Next post, I'll show you how to connect to multiple MCP servers simultaneously and how to discover tools dynamically. We'll build on this foundation to create more sophisticated applications.

The key insight is that MCP turns tools into network services, but with a standardized protocol that any client can use. Your Java application doesn't need to know how to write files, it just needs to know how to talk MCP.

Try running this code and experimenting with different file operations. What other MCP servers are you curious about? Let me know in the comments!

From Zero to AI Agent: My Journey into Java-based Intelligent Applications

Sebastiao Gazolla Jr — Tue, 16 Sep 2025 00:32:26 +0000

How I went from "AI is just hype" to building production AI agents in Java

Mid-2024. I was scrolling through yet another "AI will replace developers" article when I decided to build something with AI. Not just calling an API and pretending it's magic, but really understanding how to make Java applications that think (I mean, agentic apps).

That curiosity turned into months of late-night coding, debugging mysterious errors, and slowly figuring out how to build AI agents that actually work. Or at least, start to work.

Why Java? (Yes, really)

Everyone kept telling me to use Python for AI. "That's where all the libraries are," they said. "Java is too verbose for AI," they said.

But here's the thing, I'm a seasoned Java developer and I know how to build applications in Java. And honestly? Most of the AI demos I saw were impressive but felt fragile.

I wanted to build something with good old Java code.

The Model Context Protocol Discovery

This is where things got interesting. In late 2024 Anthropic announced the Model Context Protocol (MCP). Think of it as a standardized way for AI models to talk to external tools and data sources.

So I trashed all my code that said "when user says X, call API Y,". MCP lets you connect AI models to tools dynamically. The AI can discover what tools are available and figure out how to use them based on natural language requests.

Here's what blew my mind: with MCP, I could say "save the weather forecast for NYC to a file" and the AI would:

Understand it needs weather data
Find the weather tool
Get the forecast for NYC
Find the file-writing tool
Save the data

No hardcoded logic. No if-else chains. Just natural language instructions.

My First "Hello World" Moment

After finding the official Java SDK for MCP servers and clients and take a look in documentation, I came out with this:

import java.time.Duration;
import java.util.Map;

import io.modelcontextprotocol.client.McpClient;
import io.modelcontextprotocol.client.McpSyncClient;
import io.modelcontextprotocol.client.transport.ServerParameters;
import io.modelcontextprotocol.client.transport.StdioClientTransport;
import io.modelcontextprotocol.spec.McpSchema.CallToolRequest;
import io.modelcontextprotocol.spec.McpSchema.CallToolResult;

public class SimpleClientMCP {
    public static void main(String[] args) {
        int requestTimeoutSeconds = 30;
        String basePath = System.getProperty("user.home") + "/Documents";

        StdioClientTransport stdioTransport = new StdioClientTransport(
            ServerParameters.builder("cmd.exe")
                .args("/c", "npx @modelcontextprotocol/server-filesystem " + basePath)
                .build());

        McpSyncClient client = McpClient.sync(stdioTransport)
            .requestTimeout(Duration.ofSeconds(requestTimeoutSeconds))
            .build();

        client.initialize();

        CallToolRequest request = new CallToolRequest("write_file", Map.of(
            "path", basePath + "\\test.txt",
            "content", "Hello from Java MCP client!"
        ));

        CallToolResult result = client.callTool(request);
        System.out.println(result.toString());
    }
}

When I ran this and saw "Hello from Java MCP client!" appear in a file created by my Java code through an AI protocol, it was awesome. But I noticed that nothing will repent magically.

What I Learned Right Away

Let me be honest about this sample:

Tool discovery was manual. I had to hardcode which servers to connect to and manually map user requests to specific tools. It worked, but it wasn't intelligent.

No natural language understanding. My first version was basically "if user says 'save file' then call write_file tool." Very brittle and not really AI-powered.

To make the magic happen, I needed to code a way to let LLM understand that it has to execute a tool and call it.

Where This Journey Led

That simple file-writing example was just the beginning. Over the next few months, I built:

A system that can connect to multiple MCP servers simultaneously
Natural language tool selection using LLMs
A chat interface where users can request "complex" operations in plain English
Integration with multiple AI providers (Groq, Gemini, OpenAI)

But most importantly, I learned that building AI agents isn't about the AI part being perfect. It's about building systems with new functionality that we didn't achieve before.

What's Coming Next

In the next posts, I'll walk through:

How MCP actually works under the hood
Building your first multi-server MCP client
Adding natural language tool selection with LLMs
The debugging nightmares I lived through (and how to avoid them)
Architecture patterns to make LLMs select tools.

This isn't going to be a series of perfect demos. I'll share what I learned building agentic apps.

Why Share This?

I'm writing this series because when I started, there weren't many resources about building production AI applications in Java.

If you're a Java developer curious about AI, or an AI enthusiast who wants to build something without using any AI framework, maybe these posts will save you some of the time I spent figuring things out the hard way.

Next post, I'll dive into the Model Context Protocol itself. What it is, why it matters, and how it's different from everything else you've probably used.

Have you tried building AI applications in Java? What challenges did you hit? I'd love to hear about your experiences in the comments.