Get started building your own client that can integrate with all MCP servers.
In this tutorial, you’ll learn how to build an LLM-powered chatbot client that connects to MCP servers. It helps to have gone through the Server quickstart that guides you through the basics of building your first server.
You can find the complete code for this tutorial here.
Before starting, ensure your system meets these requirements:
uv
installedFirst, create a new Python project with uv
:
You’ll need an Anthropic API key from the Anthropic Console.
Create a .env
file to store it:
Add your key to the .env
file:
Add .env
to your .gitignore
:
Make sure you keep your ANTHROPIC_API_KEY
secure!
First, let’s set up our imports and create the basic client class:
Next, we’ll implement the method to connect to an MCP server:
Now let’s add the core functionality for processing queries and handling tool calls:
Now we’ll add the chat loop and cleanup functionality:
Finally, we’ll add the main execution logic:
You can find the complete client.py
file here.
MCPClient
class initializes with session management and API clientsAsyncExitStack
for proper resource managementTool Handling
process_query()
to handle specific tool typesResponse Processing
User Interface
To run your client with any MCP server:
If you’re continuing the weather tutorial from the server quickstart, your command might look something like this: python client.py .../quickstart-resources/weather-server-python/weather.py
The client will:
Here’s an example of what it should look like if connected to the weather server from the server quickstart:
When you submit a query:
Error Handling
Resource Management
AsyncExitStack
for proper cleanupSecurity
.env
Example of correct path usage:
If you see:
FileNotFoundError
: Check your server pathConnection refused
: Ensure the server is running and the path is correctTool execution failed
: Verify the tool’s required environment variables are setTimeout error
: Consider increasing the timeout in your client configurationYou can find the complete code for this tutorial here.
Before starting, ensure your system meets these requirements:
uv
installedFirst, create a new Python project with uv
:
You’ll need an Anthropic API key from the Anthropic Console.
Create a .env
file to store it:
Add your key to the .env
file:
Add .env
to your .gitignore
:
Make sure you keep your ANTHROPIC_API_KEY
secure!
First, let’s set up our imports and create the basic client class:
Next, we’ll implement the method to connect to an MCP server:
Now let’s add the core functionality for processing queries and handling tool calls:
Now we’ll add the chat loop and cleanup functionality:
Finally, we’ll add the main execution logic:
You can find the complete client.py
file here.
MCPClient
class initializes with session management and API clientsAsyncExitStack
for proper resource managementTool Handling
process_query()
to handle specific tool typesResponse Processing
User Interface
To run your client with any MCP server:
If you’re continuing the weather tutorial from the server quickstart, your command might look something like this: python client.py .../quickstart-resources/weather-server-python/weather.py
The client will:
Here’s an example of what it should look like if connected to the weather server from the server quickstart:
When you submit a query:
Error Handling
Resource Management
AsyncExitStack
for proper cleanupSecurity
.env
Example of correct path usage:
If you see:
FileNotFoundError
: Check your server pathConnection refused
: Ensure the server is running and the path is correctTool execution failed
: Verify the tool’s required environment variables are setTimeout error
: Consider increasing the timeout in your client configurationYou can find the complete code for this tutorial here.
Before starting, ensure your system meets these requirements:
npm
installedFirst, let’s create and set up our project:
Update your package.json
to set type: "module"
and a build script:
Create a tsconfig.json
in the root of your project:
You’ll need an Anthropic API key from the Anthropic Console.
Create a .env
file to store it:
Add .env
to your .gitignore
:
Make sure you keep your ANTHROPIC_API_KEY
secure!
First, let’s set up our imports and create the basic client class in index.ts
:
Next, we’ll implement the method to connect to an MCP server:
Now let’s add the core functionality for processing queries and handling tool calls:
Now we’ll add the chat loop and cleanup functionality:
Finally, we’ll add the main execution logic:
To run your client with any MCP server:
If you’re continuing the weather tutorial from the server quickstart, your command might look something like this: node build/index.js .../quickstart-resources/weather-server-typescript/build/index.js
The client will:
When you submit a query:
Error Handling
Security
.env
Example of correct path usage:
If you see:
Error: Cannot find module
: Check your build folder and ensure TypeScript compilation succeededConnection refused
: Ensure the server is running and the path is correctTool execution failed
: Verify the tool’s required environment variables are setANTHROPIC_API_KEY is not set
: Check your .env file and environment variablesTypeError
: Ensure you’re using the correct types for tool argumentsThis 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.
Before starting, ensure your system meets these requirements:
Install npx (Node Package eXecute): First, make sure to install npm and then run:
Clone the repository:
Set up your API keys:
Build the application:
Run the application using Maven:
Make sure you keep your ANTHROPIC_API_KEY
and BRAVE_API_KEY
keys secure!
The application integrates Spring AI with the Brave Search MCP server through several components:
This activates the spring-ai-starter-mcp-client
to create one or more McpClient
s based on the provided server configuration.
The spring.ai.mcp.client.toolcallback.enabled=true
property enables the tool callback mechanism, that automatically registers all MCP tool as spring ai tools.
It is disabled by default.
mcp-servers-config.json
):The chatbot is implemented using Spring AI’s ChatClient with MCP tool integration:
Breaking change: From SpringAI 1.0.0-M8 onwards, use .defaultToolCallbacks(...)
instead of .defaultTool(...)
to register MCP tools.
Key features:
or
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:
The MCP client supports additional configuration options:
McpSyncClientCustomizer
or McpAsyncClientCustomizer
STDIO
and SSE
(Server-Sent Events)For WebFlux-based applications, you can use the WebFlux starter instead:
This provides similar functionality but uses a WebFlux-based SSE transport implementation, recommended for production deployments.
You can find the complete code for this tutorial here.
Before starting, ensure your system meets these requirements:
First, let’s install java
and gradle
if you haven’t already.
You can download java
from official Oracle JDK website.
Verify your java
installation:
Now, let’s create and set up your project:
After running gradle init
, you will be presented with options for creating your project.
Select Application as the project type, Kotlin as the programming language, and Java 17 as the Java version.
Alternatively, you can create a Kotlin application using the IntelliJ IDEA project wizard.
After creating the project, add the following dependencies:
Also, add the following plugins to your build script:
You’ll need an Anthropic API key from the Anthropic Console.
Set up your API key:
Make sure your keep your ANTHROPIC_API_KEY
secure!
First, let’s create the basic client class:
Next, we’ll implement the method to connect to an MCP server:
Also create a helper function to convert from JsonObject
to JsonValue
for Anthropic:
Now let’s add the core functionality for processing queries and handling tool calls:
We’ll add the chat loop:
Finally, we’ll add the main execution function:
To run your client with any MCP server:
If you’re continuing the weather tutorial from the server quickstart, your command might look something like this: java -jar build/libs/kotlin-mcp-client-0.1.0-all.jar .../samples/weather-stdio-server/build/libs/weather-stdio-server-0.1.0-all.jar
The client will:
Here’s a high-level workflow schema:
When you submit a query:
Error Handling
try-catch
blocks when exceptions are possibleSecurity
local.properties
, environment variables, or secret managersExample of correct path usage:
If you see:
Connection refused
: Ensure the server is running and the path is correctTool execution failed
: Verify the tool’s required environment variables are setANTHROPIC_API_KEY is not set
: Check your environment variablesYou can find the complete code for this tutorial here.
Before starting, ensure your system meets these requirements:
First, create a new .NET project:
Then, add the required dependencies to your project:
You’ll need an Anthropic API key from the Anthropic Console.
First, let’s setup the basic client class in the file Program.cs
:
This creates the beginnings of a .NET console application that can read the API key from user secrets.
Next, we’ll setup the MCP Client:
Add this function at the end of the Program.cs
file:
This creates a MCP client that will connect to a server that is provided as a command line argument. It then lists the available tools from the connected server.
Now let’s add the core functionality for processing queries and handling tool calls:
McpClientFactory.CreateAsync()
, which sets up the transport type and command to run the server.IChatClient
to use automatic tool (function) invocation.To run your client with any MCP server:
If you’re continuing the weather tutorial from the server quickstart, your command might look something like this: dotnet run -- path/to/QuickstartWeatherServer
.
The client will:
Here’s an example of what it should look like it connected to a weather server quickstart:
Check out our gallery of official MCP servers and implementations
View the list of clients that support MCP integrations
Learn how to use LLMs like Claude to speed up your MCP development
Understand how MCP connects clients, servers, and LLMs
Get started building your own client that can integrate with all MCP servers.
In this tutorial, you’ll learn how to build an LLM-powered chatbot client that connects to MCP servers. It helps to have gone through the Server quickstart that guides you through the basics of building your first server.
You can find the complete code for this tutorial here.
Before starting, ensure your system meets these requirements:
uv
installedFirst, create a new Python project with uv
:
You’ll need an Anthropic API key from the Anthropic Console.
Create a .env
file to store it:
Add your key to the .env
file:
Add .env
to your .gitignore
:
Make sure you keep your ANTHROPIC_API_KEY
secure!
First, let’s set up our imports and create the basic client class:
Next, we’ll implement the method to connect to an MCP server:
Now let’s add the core functionality for processing queries and handling tool calls:
Now we’ll add the chat loop and cleanup functionality:
Finally, we’ll add the main execution logic:
You can find the complete client.py
file here.
MCPClient
class initializes with session management and API clientsAsyncExitStack
for proper resource managementTool Handling
process_query()
to handle specific tool typesResponse Processing
User Interface
To run your client with any MCP server:
If you’re continuing the weather tutorial from the server quickstart, your command might look something like this: python client.py .../quickstart-resources/weather-server-python/weather.py
The client will:
Here’s an example of what it should look like if connected to the weather server from the server quickstart:
When you submit a query:
Error Handling
Resource Management
AsyncExitStack
for proper cleanupSecurity
.env
Example of correct path usage:
If you see:
FileNotFoundError
: Check your server pathConnection refused
: Ensure the server is running and the path is correctTool execution failed
: Verify the tool’s required environment variables are setTimeout error
: Consider increasing the timeout in your client configurationYou can find the complete code for this tutorial here.
Before starting, ensure your system meets these requirements:
uv
installedFirst, create a new Python project with uv
:
You’ll need an Anthropic API key from the Anthropic Console.
Create a .env
file to store it:
Add your key to the .env
file:
Add .env
to your .gitignore
:
Make sure you keep your ANTHROPIC_API_KEY
secure!
First, let’s set up our imports and create the basic client class:
Next, we’ll implement the method to connect to an MCP server:
Now let’s add the core functionality for processing queries and handling tool calls:
Now we’ll add the chat loop and cleanup functionality:
Finally, we’ll add the main execution logic:
You can find the complete client.py
file here.
MCPClient
class initializes with session management and API clientsAsyncExitStack
for proper resource managementTool Handling
process_query()
to handle specific tool typesResponse Processing
User Interface
To run your client with any MCP server:
If you’re continuing the weather tutorial from the server quickstart, your command might look something like this: python client.py .../quickstart-resources/weather-server-python/weather.py
The client will:
Here’s an example of what it should look like if connected to the weather server from the server quickstart:
When you submit a query:
Error Handling
Resource Management
AsyncExitStack
for proper cleanupSecurity
.env
Example of correct path usage:
If you see:
FileNotFoundError
: Check your server pathConnection refused
: Ensure the server is running and the path is correctTool execution failed
: Verify the tool’s required environment variables are setTimeout error
: Consider increasing the timeout in your client configurationYou can find the complete code for this tutorial here.
Before starting, ensure your system meets these requirements:
npm
installedFirst, let’s create and set up our project:
Update your package.json
to set type: "module"
and a build script:
Create a tsconfig.json
in the root of your project:
You’ll need an Anthropic API key from the Anthropic Console.
Create a .env
file to store it:
Add .env
to your .gitignore
:
Make sure you keep your ANTHROPIC_API_KEY
secure!
First, let’s set up our imports and create the basic client class in index.ts
:
Next, we’ll implement the method to connect to an MCP server:
Now let’s add the core functionality for processing queries and handling tool calls:
Now we’ll add the chat loop and cleanup functionality:
Finally, we’ll add the main execution logic:
To run your client with any MCP server:
If you’re continuing the weather tutorial from the server quickstart, your command might look something like this: node build/index.js .../quickstart-resources/weather-server-typescript/build/index.js
The client will:
When you submit a query:
Error Handling
Security
.env
Example of correct path usage:
If you see:
Error: Cannot find module
: Check your build folder and ensure TypeScript compilation succeededConnection refused
: Ensure the server is running and the path is correctTool execution failed
: Verify the tool’s required environment variables are setANTHROPIC_API_KEY is not set
: Check your .env file and environment variablesTypeError
: Ensure you’re using the correct types for tool argumentsThis 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.
Before starting, ensure your system meets these requirements:
Install npx (Node Package eXecute): First, make sure to install npm and then run:
Clone the repository:
Set up your API keys:
Build the application:
Run the application using Maven:
Make sure you keep your ANTHROPIC_API_KEY
and BRAVE_API_KEY
keys secure!
The application integrates Spring AI with the Brave Search MCP server through several components:
This activates the spring-ai-starter-mcp-client
to create one or more McpClient
s based on the provided server configuration.
The spring.ai.mcp.client.toolcallback.enabled=true
property enables the tool callback mechanism, that automatically registers all MCP tool as spring ai tools.
It is disabled by default.
mcp-servers-config.json
):The chatbot is implemented using Spring AI’s ChatClient with MCP tool integration:
Breaking change: From SpringAI 1.0.0-M8 onwards, use .defaultToolCallbacks(...)
instead of .defaultTool(...)
to register MCP tools.
Key features:
or
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:
The MCP client supports additional configuration options:
McpSyncClientCustomizer
or McpAsyncClientCustomizer
STDIO
and SSE
(Server-Sent Events)For WebFlux-based applications, you can use the WebFlux starter instead:
This provides similar functionality but uses a WebFlux-based SSE transport implementation, recommended for production deployments.
You can find the complete code for this tutorial here.
Before starting, ensure your system meets these requirements:
First, let’s install java
and gradle
if you haven’t already.
You can download java
from official Oracle JDK website.
Verify your java
installation:
Now, let’s create and set up your project:
After running gradle init
, you will be presented with options for creating your project.
Select Application as the project type, Kotlin as the programming language, and Java 17 as the Java version.
Alternatively, you can create a Kotlin application using the IntelliJ IDEA project wizard.
After creating the project, add the following dependencies:
Also, add the following plugins to your build script:
You’ll need an Anthropic API key from the Anthropic Console.
Set up your API key:
Make sure your keep your ANTHROPIC_API_KEY
secure!
First, let’s create the basic client class:
Next, we’ll implement the method to connect to an MCP server:
Also create a helper function to convert from JsonObject
to JsonValue
for Anthropic:
Now let’s add the core functionality for processing queries and handling tool calls:
We’ll add the chat loop:
Finally, we’ll add the main execution function:
To run your client with any MCP server:
If you’re continuing the weather tutorial from the server quickstart, your command might look something like this: java -jar build/libs/kotlin-mcp-client-0.1.0-all.jar .../samples/weather-stdio-server/build/libs/weather-stdio-server-0.1.0-all.jar
The client will:
Here’s a high-level workflow schema:
When you submit a query:
Error Handling
try-catch
blocks when exceptions are possibleSecurity
local.properties
, environment variables, or secret managersExample of correct path usage:
If you see:
Connection refused
: Ensure the server is running and the path is correctTool execution failed
: Verify the tool’s required environment variables are setANTHROPIC_API_KEY is not set
: Check your environment variablesYou can find the complete code for this tutorial here.
Before starting, ensure your system meets these requirements:
First, create a new .NET project:
Then, add the required dependencies to your project:
You’ll need an Anthropic API key from the Anthropic Console.
First, let’s setup the basic client class in the file Program.cs
:
This creates the beginnings of a .NET console application that can read the API key from user secrets.
Next, we’ll setup the MCP Client:
Add this function at the end of the Program.cs
file:
This creates a MCP client that will connect to a server that is provided as a command line argument. It then lists the available tools from the connected server.
Now let’s add the core functionality for processing queries and handling tool calls:
McpClientFactory.CreateAsync()
, which sets up the transport type and command to run the server.IChatClient
to use automatic tool (function) invocation.To run your client with any MCP server:
If you’re continuing the weather tutorial from the server quickstart, your command might look something like this: dotnet run -- path/to/QuickstartWeatherServer
.
The client will:
Here’s an example of what it should look like it connected to a weather server quickstart:
Check out our gallery of official MCP servers and implementations
View the list of clients that support MCP integrations
Learn how to use LLMs like Claude to speed up your MCP development
Understand how MCP connects clients, servers, and LLMs