MCP Docs
Quickstart
For Client Developers

For Client Developers

In this tutorial, you’ll learn how to build a LLM-powered chatbot client that connects to MCP servers. It helps to have gone through the Server quickstart that guides you through the basic of building your first server.

You can find the complete code for this tutorial here.

System Requirements

Before starting, ensure your system meets these requirements:

  • Mac or Windows computer
  • Latest Python version installed
  • Latest version of uv installed

Setting Up Your Environment

First, create a new Python project with uv:

# Create project directory
uv init mcp-client
cd mcp-client

# Create virtual environment
uv venv

# Activate virtual environment
# On Windows:
.venv\Scripts\activate
# On Unix or MacOS:
source .venv/bin/activate

# Install required packages
uv add mcp anthropic python-dotenv

# Remove boilerplate files
rm hello.py

# Create our main file
touch client.py

Setting Up Your API Key

You’ll need an Anthropic API key from the Anthropic Console.

Create a .env file to store it:

# Create .env file
touch .env

Add your key to the .env file:

ANTHROPIC_API_KEY=<your key here>

Add .env to your .gitignore:

echo ".env" >> .gitignore

Creating the Client

Basic Client Structure

First, let’s set up our imports and create the basic client class.

import asyncio
from typing import Optional
from contextlib import AsyncExitStack

from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

from anthropic import Anthropic
from dotenv import load_dotenv

load_dotenv()  # load environment variables from .env

class MCPClient:
    def __init__(self):
        # Initialize session and client objects
        self.session: Optional[ClientSession] = None
        self.exit_stack = AsyncExitStack()
        self.anthropic = Anthropic()

Server Connection Management

Next, we’ll implement the method to connect to an MCP server:

async def connect_to_server(self, server_script_path: str):
    """Connect to an MCP server

    Args:
        server_script_path: Path to the server script (.py or .js)
    """
    is_python = server_script_path.endswith('.py')
    is_js = server_script_path.endswith('.js')
    if not (is_python or is_js):
        raise ValueError("Server script must be a .py or .js file")

    command = "python" if is_python else "node"
    server_params = StdioServerParameters(
        command=command,
        args=[server_script_path],
        env=None
    )

    stdio_transport = await self.exit_stack.enter_async_context(stdio_client(server_params))
    self.stdio, self.write = stdio_transport
    self.session = await self.exit_stack.enter_async_context(ClientSession(self.stdio, self.write))

    await self.session.initialize()

    # List available tools
    response = await self.session.list_tools()
    tools = response.tools
    print("\nConnected to server with tools:", [tool.name for tool in tools])

Query Processing Logic

Now let’s add the core functionality for processing queries and handling tool calls:

async def process_query(self, query: str) -> str:
    """Process a query using Claude and available tools"""
    messages = [
        {
            "role": "user",
            "content": query
        }
    ]

    response = await self.session.list_tools()
    available_tools = [{
        "name": tool.name,
        "description": tool.description,
        "input_schema": tool.inputSchema
    } for tool in response.tools]

    # Initial Claude API call
    response = self.anthropic.messages.create(
        model="claude-3-5-sonnet-20241022",
        max_tokens=1000,
        messages=messages,
        tools=available_tools
    )

    # Process response and handle tool calls
    tool_results = []
    final_text = []

    assistant_message_content = []
    for content in response.content:
        if content.type == 'text':
            final_text.append(content.text)
            assistant_message_content.append(content)
        elif content.type == 'tool_use':
            tool_name = content.name
            tool_args = content.input

            # Execute tool call
            result = await self.session.call_tool(tool_name, tool_args)
            tool_results.append({"call": tool_name, "result": result})
            final_text.append(f"[Calling tool {tool_name} with args {tool_args}]")

            assistant_message_content.append(content)
            messages.append({
                "role": "assistant",
                "content": assistant_message_content
            })
            messages.append({
                "role": "user",
                "content": [
                    {
                        "type": "tool_result",
                        "tool_use_id": content.id,
                        "content": result.content
                    }
                ]
            })

            # Get next response from Claude
            response = self.anthropic.messages.create(
                model="claude-3-5-sonnet-20241022",
                max_tokens=1000,
                messages=messages,
                tools=available_tools
            )

            final_text.append(response.content[0].text)

    return "\n".join(final_text)

Interactive Chat Interface

Now we’ll add the chat loop and cleanup functionality:

async def chat_loop(self):
    """Run an interactive chat loop"""
    print("\nMCP Client Started!")
    print("Type your queries or 'quit' to exit.")

    while True:
        try:
            query = input("\nQuery: ").strip()

            if query.lower() == 'quit':
                break

            response = await self.process_query(query)
            print("\n" + response)

        except Exception as e:
            print(f"\nError: {str(e)}")

async def cleanup(self):
    """Clean up resources"""
    await self.exit_stack.aclose()

Main Entry Point

Finally, we’ll add the main execution logic:

async def main():
    if len(sys.argv) < 2:
        print("Usage: python client.py <path_to_server_script>")
        sys.exit(1)

    client = MCPClient()
    try:
        await client.connect_to_server(sys.argv[1])
        await client.chat_loop()
    finally:
        await client.cleanup()

if __name__ == "__main__":
    import sys
    asyncio.run(main())

Key Components Explained

1. Client Initialization

  • The MCPClient class initializes with session management and API clients
  • Uses AsyncExitStack for proper resource management
  • Configures the Anthropic client for Claude interactions

2. Server Connection

  • Supports both Python and Node.js servers
  • Validates server script type
  • Sets up proper communication channels
  • Initializes the session and lists available tools

3. Query Processing

  • Maintains conversation context
  • Handles Claude’s responses and tool calls
  • Manages message flow between Claude and tools
  • Combines results into a coherent response

4. Interactive Interface

  • Provides a simple command-line interface
  • Handles user input and displays responses
  • Includes basic error handling
  • Allows graceful exit

5. Resource Management

  • Proper cleanup of resources
  • Error handling for connection issues

Troubleshooting

Server Path Issues
  • Check if server script path is correct
  • Use absolute paths if relative paths don’t work
  • For Windows users, ensure using forward slashes(/) or escaped backslashes(\)
  • Verify server file has correct extension (.py for Python or .js for Node.js)

Example of correct path usage:

# Relative path
uv run client.py ./server/weather.py

# Absolute path
uv run client.py /Users/username/projects/mcp-server/weather.py

# Windows path (both formats work)
uv run client.py C:/projects/mcp-server/weather.py
uv run client.py C:\\projects\\mcp-server\\weather.py
Response Timing
  • First response may take up to 30 seconds
  • This is normal and happens during:
    • Server initialization
    • Claude processing query
    • Tool execution
  • Subsequent responses are typically faster
  • Don’t interrupt process during initial wait
ℹ️
This is a quickstart demo based on Spring AI MCP auto-configuration and boot starters. To learn how to create sync and async MCP Clients manually, consult the Java SDK Client documentation

System Requirements

Before starting, ensure your system meets these requirements:

  • Java 17 or later
  • Maven 3.6 or later
  • An IDE with Spring Boot support

Creating the Project

Create a new Spring Boot project with Maven:

mvn archetype:generate \
  -DgroupId=com.example \
  -DartifactId=ai-mcp-brave-chatbot \
  -DarchetypeArtifactId=maven-archetype-quickstart \
  -DinteractiveMode=false

Update your pom.xml:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.example</groupId>
    <artifactId>ai-mcp-brave-chatbot</artifactId>
    <version>0.0.1-SNAPSHOT</version>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.2.0</version>
    </parent>

    <properties>
        <java.version>17</java.version>
        <spring-ai.version>0.8.0</spring-ai.version>
    </properties>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-anthropic-spring-boot-starter</artifactId>
            <version>${spring-ai.version}</version>
        </dependency>
        <dependency>
            <groupId>org.modelcontext</groupId>
            <artifactId>mcp-spring-boot-starter</artifactId>
            <version>0.4.0</version>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
</project>

Application Configuration

Create application.yml:

spring:
  ai:
    anthropic:
      api-key: ${ANTHROPIC_API_KEY}
  mcp:
    servers:
      filesystem:
        command: npx
        args:
          - "-y"
          - "@modelcontextprotocol/server-filesystem"
          - "C:\\Users\\username\\Desktop"
          - "C:\\Users\\username\\Downloads"

Creating the Application

Create the main application class:

package com.example;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class BraveChatApplication {
    public static void main(String[] args) {
        SpringApplication.run(BraveChatApplication.class, args);
    }
}

Running the Application 

# Build and run
./mvnw clean install
java -jar ./target/ai-mcp-brave-chatbot-0.0.1-SNAPSHOT.jar

# Alternative
./mvnw spring-boot:run
⚠️
Remember to set your ANTHROPIC_API_KEY environment variable before running the application!

How It Works

The application integrates Spring AI with the MCP server through several components:

MCP Client Configuration

  1. Required dependencies in pom.xml:
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-mcp-client-spring-boot-starter</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-anthropic-spring-boot-starter</artifactId>
</dependency>
  1. Application properties (application.yml):
spring:
  ai:
    mcp:
      client:
        enabled: true
        name: brave-search-client
        version: 1.0.0
        type: SYNC
        request-timeout: 20s
        stdio:
          root-change-notification: true
          servers-configuration: classpath:/mcp-servers-config.json
    anthropic:
      api-key: ${ANTHROPIC_API_KEY}
  1. MCP Server Configuration (mcp-servers-config.json):
{
  "mcpServers": {
    "brave-search": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-brave-search"
      ],
      "env": {
        "BRAVE_API_KEY": "<PUT YOUR BRAVE API KEY>"
      }
    }
  }
}

Chat Implementation

The chatbot is implemented using Spring AI’s ChatClient with MCP tool integration:

var chatClient = chatClientBuilder
    .defaultSystem("You are useful assistant, expert in AI and Java.")
    .defaultTools((Object[]) mcpToolAdapter.toolCallbacks())
    .defaultAdvisors(new MessageChatMemoryAdvisor(new InMemoryChatMemory()))
    .build();

Key features:

  • Uses Claude AI model for natural language understanding
  • Integrates MCP for tool capabilities
  • Maintains conversation memory using InMemoryChatMemory
  • Runs as an interactive command-line application

Advanced Configuration

The MCP client supports additional configuration options:

  • Client customization through McpSyncClientCustomizer or McpAsyncClientCustomizer
  • Multiple clients with multiple transport types: STDIO and SSE (Server-Sent Events)
  • Integration with Spring AI’s tool execution framework
  • Automatic client initialization and lifecycle management

For WebFlux-based applications, you can use the WebFlux starter instead:

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-mcp-client-webflux-spring-boot-starter</artifactId>
</dependency>

This provides similar functionality but uses a WebFlux-based SSE transport implementation, recommended for production deployments.

Next steps

Core architecture
Understand how MCP connects clients, servers, and LLMs
Building MCP with LLMs
Use LLMs to speed up MCP development
Clients
View the list of clients that support MCP integrations
Example servers
Check out our gallery of official MCP servers
For Server DevelopersFor Claude Desktop Users