For Client Developers - Model Context Protocol

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

Make sure you keep your ANTHROPIC_API_KEY secure!

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()
    # methods will go here

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

You can find the complete client.py file here.

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 the 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
Graceful shutdown procedures

Common Customization Points

Tool Handling
- Modify process_query() to handle specific tool types
- Add custom error handling for tool calls
- Implement tool-specific response formatting
Response Processing
- Customize how tool results are formatted
- Add response filtering or transformation
- Implement custom logging
User Interface
- Add a GUI or web interface
- Implement rich console output
- Add command history or auto-completion

Running the Client

To run your client with any MCP server:

uv run client.py path/to/server.py # python server
uv run client.py path/to/build/index.js # node server

If you’re continuing the weather tutorial from the server quickstart, your command might look something like this: python client.py .../weather/src/weather/server.py

The client will:

Connect to the specified server
List available tools
Start an interactive chat session where you can:
- Enter queries
- See tool executions
- Get responses from Claude

Here’s an example of what it should look like if connected to the weather server from the server quickstart:

How It Works

When you submit a query:

The client gets the list of available tools from the server
Your query is sent to Claude along with tool descriptions
Claude decides which tools (if any) to use
The client executes any requested tool calls through the server
Results are sent back to Claude
Claude provides a natural language response
The response is displayed to you

Best practices

Error Handling
- Always wrap tool calls in try-catch blocks
- Provide meaningful error messages
- Gracefully handle connection issues
Resource Management
- Use AsyncExitStack for proper cleanup
- Close connections when done
- Handle server disconnections
Security
- Store API keys securely in .env
- Validate server responses
- Be cautious with tool permissions

Troubleshooting

Server Path Issues

Double-check the path to your server script is correct
Use the absolute path if the relative path isn’t working
For Windows users, make sure to use forward slashes (/) or escaped backslashes (\) in the path
Verify the server file has the 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 (either format works)
uv run client.py C:/projects/mcp-server/weather.py
uv run client.py C:\\projects\\mcp-server\\weather.py

Response Timing

The first response might take up to 30 seconds to return
This is normal and happens while:
- The server initializes
- Claude processes the query
- Tools are being executed
Subsequent responses are typically faster
Don’t interrupt the process during this initial waiting period

Common Error Messages

If you see:

FileNotFoundError: Check your server path
Connection refused: Ensure the server is running and the path is correct
Tool execution failed: Verify the tool’s required environment variables are set
Timeout error: Consider increasing the timeout in your client configuration

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

Make sure you keep your ANTHROPIC_API_KEY secure!

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()
    # methods will go here

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

You can find the complete client.py file here.

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 the 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
Graceful shutdown procedures

Common Customization Points

Tool Handling
- Modify process_query() to handle specific tool types
- Add custom error handling for tool calls
- Implement tool-specific response formatting
Response Processing
- Customize how tool results are formatted
- Add response filtering or transformation
- Implement custom logging
User Interface
- Add a GUI or web interface
- Implement rich console output
- Add command history or auto-completion

Running the Client

To run your client with any MCP server:

uv run client.py path/to/server.py # python server
uv run client.py path/to/build/index.js # node server

If you’re continuing the weather tutorial from the server quickstart, your command might look something like this: python client.py .../weather/src/weather/server.py

The client will:

Connect to the specified server
List available tools
Start an interactive chat session where you can:
- Enter queries
- See tool executions
- Get responses from Claude

Here’s an example of what it should look like if connected to the weather server from the server quickstart:

How It Works

When you submit a query:

The client gets the list of available tools from the server
Your query is sent to Claude along with tool descriptions
Claude decides which tools (if any) to use
The client executes any requested tool calls through the server
Results are sent back to Claude
Claude provides a natural language response
The response is displayed to you

Best practices

Error Handling
- Always wrap tool calls in try-catch blocks
- Provide meaningful error messages
- Gracefully handle connection issues
Resource Management
- Use AsyncExitStack for proper cleanup
- Close connections when done
- Handle server disconnections
Security
- Store API keys securely in .env
- Validate server responses
- Be cautious with tool permissions

Troubleshooting

Server Path Issues

Double-check the path to your server script is correct
Use the absolute path if the relative path isn’t working
For Windows users, make sure to use forward slashes (/) or escaped backslashes (\) in the path
Verify the server file has the 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 (either format works)
uv run client.py C:/projects/mcp-server/weather.py
uv run client.py C:\\projects\\mcp-server\\weather.py

Response Timing

The first response might take up to 30 seconds to return
This is normal and happens while:
- The server initializes
- Claude processes the query
- Tools are being executed
Subsequent responses are typically faster
Don’t interrupt the process during this initial waiting period

Common Error Messages

If you see:

FileNotFoundError: Check your server path
Connection refused: Ensure the server is running and the path is correct
Tool execution failed: Verify the tool’s required environment variables are set
Timeout error: Consider increasing the timeout in your client configuration

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

This example demonstrates how to build an interactive chatbot that combines Spring AI’s Model Context Protocol (MCP) with the Brave Search MCP Server. The application creates a conversational interface powered by Anthropic’s Claude AI model that can perform internet searches through Brave Search, enabling natural language interactions with real-time web data. You can find the complete code for this tutorial here.

System Requirements

Before starting, ensure your system meets these requirements:

Java 17 or higher
Maven 3.6+
npx package manager
Anthropic API key (Claude)
Brave Search API key

Setting Up Your Environment

Install npx (Node Package eXecute): First, make sure to install npm and then run:
```
npm install -g npx
```

Clone the repository:

git clone https://github.com/spring-projects/spring-ai-examples.git
cd model-context-protocol/brave-chatbot

Set up your API keys:

export ANTHROPIC_API_KEY='your-anthropic-api-key-here'
export BRAVE_API_KEY='your-brave-api-key-here'

Build the application:
```
./mvnw clean install
```
Run the application using Maven:
```
./mvnw spring-boot:run
```

Make sure you keep your ANTHROPIC_API_KEY and BRAVE_API_KEY keys secure!

How it Works

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

MCP Client Configuration

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>

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}

This activates the spring-ai-mcp-client-spring-boot-starter to create one or more McpClients based on the provided server configuration.

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 Brave Search through MCP for real-time web search capabilities
Maintains conversation memory using InMemoryChatMemory
Runs as an interactive command-line application

Build and run

./mvnw clean install
java -jar ./target/ai-mcp-brave-chatbot-0.0.1-SNAPSHOT.jar

./mvnw spring-boot:run

The application will start an interactive chat session where you can ask questions. The chatbot will use Brave Search when it needs to find information from the internet to answer your queries.

The chatbot can:

Answer questions using its built-in knowledge
Perform web searches when needed using Brave Search
Remember context from previous messages in the conversation
Combine information from multiple sources to provide comprehensive answers

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

Example servers

Check out our gallery of official MCP servers and implementations

Clients

View the list of clients that support MCP integrations

Building MCP with LLMs

Learn how to use LLMs like Claude to speed up your MCP development

Core architecture

Understand how MCP connects clients, servers, and LLMs

Getting Started

Core Concepts

SDK Documentation

Development

​System Requirements

​Setting Up Your Environment

​Setting Up Your API Key

​Creating the Client

​Basic Client Structure

​Server Connection Management

​Query Processing Logic

​Interactive Chat Interface

​Main Entry Point

​Key Components Explained

​1. Client Initialization

​2. Server Connection

​3. Query Processing

​4. Interactive Interface

​5. Resource Management

​Common Customization Points

​Running the Client

​How It Works

​Best practices

​Troubleshooting

​Server Path Issues

​Response Timing

​Common Error Messages

​System Requirements

​Setting Up Your Environment

​Setting Up Your API Key

​Creating the Client

​Basic Client Structure

​Server Connection Management

​Query Processing Logic

​Interactive Chat Interface

​Main Entry Point

​Key Components Explained

​1. Client Initialization

​2. Server Connection

​3. Query Processing

​4. Interactive Interface

​5. Resource Management

​Common Customization Points

​Running the Client

​How It Works

​Best practices

​Troubleshooting

​Server Path Issues

​Response Timing

​Common Error Messages

​System Requirements

​Setting Up Your Environment

​How it Works

​MCP Client Configuration

​Chat Implementation

​Build and run

​Advanced Configuration

​Next steps

Example servers

Clients

Building MCP with LLMs

Core architecture

System Requirements

Setting Up Your Environment

Setting Up Your API Key

Creating the Client

Basic Client Structure

Server Connection Management

Query Processing Logic

Interactive Chat Interface

Main Entry Point

Key Components Explained

1. Client Initialization

2. Server Connection

3. Query Processing

4. Interactive Interface

5. Resource Management

Common Customization Points

Running the Client

How It Works

Best practices

Troubleshooting

Server Path Issues

Response Timing

Common Error Messages

System Requirements

Setting Up Your Environment

Setting Up Your API Key

Creating the Client

Basic Client Structure

Server Connection Management

Query Processing Logic

Interactive Chat Interface

Main Entry Point

Key Components Explained

1. Client Initialization

2. Server Connection

3. Query Processing

4. Interactive Interface

5. Resource Management

Common Customization Points

Running the Client

How It Works

Best practices

Troubleshooting

Server Path Issues

Response Timing

Common Error Messages

System Requirements

Setting Up Your Environment

How it Works

MCP Client Configuration

Chat Implementation

Build and run

Advanced Configuration

Next steps