610 lines
17 KiB
Text
610 lines
17 KiB
Text
---
|
|
title: "For Client Developers"
|
|
description: "Get started building your own client that can integrate with all MCP servers."
|
|
---
|
|
|
|
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](/quickstart/server) that guides you through the basic of building your first server.
|
|
|
|
<Tabs>
|
|
<Tab title="Python">
|
|
|
|
[You can find the complete code for this tutorial here.](https://github.com/modelcontextprotocol/quickstart-resources/tree/main/mcp-client)
|
|
|
|
## 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`:
|
|
|
|
```bash
|
|
# 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](https://console.anthropic.com/settings/keys).
|
|
|
|
Create a `.env` file to store it:
|
|
|
|
```bash
|
|
# Create .env file
|
|
touch .env
|
|
```
|
|
|
|
Add your key to the `.env` file:
|
|
```bash
|
|
ANTHROPIC_API_KEY=<your key here>
|
|
```
|
|
|
|
Add `.env` to your `.gitignore`:
|
|
```bash
|
|
echo ".env" >> .gitignore
|
|
```
|
|
|
|
<Warning>
|
|
Make sure you keep your `ANTHROPIC_API_KEY` secure!
|
|
</Warning>
|
|
|
|
## Creating the Client
|
|
|
|
### Basic Client Structure
|
|
First, let's set up our imports and create the basic client class:
|
|
|
|
```python
|
|
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:
|
|
|
|
```python
|
|
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:
|
|
|
|
```python
|
|
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:
|
|
|
|
```python
|
|
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:
|
|
|
|
```python
|
|
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.](https://gist.github.com/zckly/f3f28ea731e096e53b39b47bf0a2d4b1)
|
|
|
|
## 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
|
|
|
|
1. **Tool Handling**
|
|
- Modify `process_query()` to handle specific tool types
|
|
- Add custom error handling for tool calls
|
|
- Implement tool-specific response formatting
|
|
|
|
2. **Response Processing**
|
|
- Customize how tool results are formatted
|
|
- Add response filtering or transformation
|
|
- Implement custom logging
|
|
|
|
3. **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:
|
|
|
|
```bash
|
|
uv run client.py path/to/server.py # python server
|
|
uv run client.py path/to/build/index.js # node server
|
|
```
|
|
|
|
<Note>
|
|
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`
|
|
</Note>
|
|
|
|
The client will:
|
|
1. Connect to the specified server
|
|
2. List available tools
|
|
3. 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:
|
|
|
|
<Frame>
|
|
<img src="/images/client-claude-cli-python.png" />
|
|
</Frame>
|
|
|
|
## How It Works
|
|
|
|
When you submit a query:
|
|
|
|
1. The client gets the list of available tools from the server
|
|
2. Your query is sent to Claude along with tool descriptions
|
|
3. Claude decides which tools (if any) to use
|
|
4. The client executes any requested tool calls through the server
|
|
5. Results are sent back to Claude
|
|
6. Claude provides a natural language response
|
|
7. The response is displayed to you
|
|
|
|
## Best practices
|
|
|
|
1. **Error Handling**
|
|
- Always wrap tool calls in try-catch blocks
|
|
- Provide meaningful error messages
|
|
- Gracefully handle connection issues
|
|
|
|
2. **Resource Management**
|
|
- Use `AsyncExitStack` for proper cleanup
|
|
- Close connections when done
|
|
- Handle server disconnections
|
|
|
|
3. **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:
|
|
```bash
|
|
# 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
|
|
|
|
</Tab>
|
|
|
|
<Tab title="Java">
|
|
|
|
<Note>
|
|
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](/sdk/java/mcp-client) documentation
|
|
</Note>
|
|
|
|
This example demonstrates how to build an interactive chatbot that combines Spring AI's Model Context Protocol (MCP) with the [Brave Search MCP Server](https://github.com/modelcontextprotocol/servers/tree/main/src/brave-search). 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.](https://github.com/spring-projects/spring-ai-examples/tree/main/model-context-protocol/web-search/brave-chatbot)
|
|
|
|
## 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
|
|
|
|
1. Install npx (Node Package eXecute):
|
|
First, make sure to install [npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)
|
|
and then run:
|
|
```bash
|
|
npm install -g npx
|
|
```
|
|
|
|
2. Clone the repository:
|
|
```bash
|
|
git clone https://github.com/spring-projects/spring-ai-examples.git
|
|
cd model-context-protocol/brave-chatbot
|
|
```
|
|
|
|
3. Set up your API keys:
|
|
```bash
|
|
export ANTHROPIC_API_KEY='your-anthropic-api-key-here'
|
|
export BRAVE_API_KEY='your-brave-api-key-here'
|
|
```
|
|
|
|
4. Build the application:
|
|
```bash
|
|
./mvnw clean install
|
|
```
|
|
|
|
5. Run the application using Maven:
|
|
```bash
|
|
./mvnw spring-boot:run
|
|
```
|
|
|
|
<Warning>
|
|
Make sure you keep your `ANTHROPIC_API_KEY` and `BRAVE_API_KEY` keys secure!
|
|
</Warning>
|
|
|
|
|
|
## How it Works
|
|
|
|
The application integrates Spring AI with the Brave Search MCP server through several components:
|
|
|
|
### MCP Client Configuration
|
|
|
|
1. Required dependencies in pom.xml:
|
|
```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>
|
|
```
|
|
|
|
2. Application properties (application.yml):
|
|
```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 `McpClient`s based on the provided server configuration.
|
|
|
|
3. MCP Server Configuration (`mcp-servers-config.json`):
|
|
```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:
|
|
|
|
```java
|
|
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
|
|
|
|
```bash
|
|
./mvnw clean install
|
|
java -jar ./target/ai-mcp-brave-chatbot-0.0.1-SNAPSHOT.jar
|
|
```
|
|
|
|
or
|
|
|
|
```bash
|
|
./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:
|
|
|
|
```xml
|
|
<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.
|
|
|
|
</Tab>
|
|
|
|
</Tabs>
|
|
|
|
## Next steps
|
|
|
|
<CardGroup cols={2}>
|
|
<Card
|
|
title="Example servers"
|
|
icon="grid"
|
|
href="/examples"
|
|
>
|
|
Check out our gallery of official MCP servers and implementations
|
|
</Card>
|
|
<Card
|
|
title="Clients"
|
|
icon="cubes"
|
|
href="/clients"
|
|
>
|
|
View the list of clients that support MCP integrations
|
|
</Card>
|
|
<Card
|
|
title="Building MCP with LLMs"
|
|
icon="comments"
|
|
href="/building-mcp-with-llms"
|
|
>
|
|
Learn how to use LLMs like Claude to speed up your MCP development
|
|
</Card>
|
|
<Card
|
|
title="Core architecture"
|
|
icon="sitemap"
|
|
href="/docs/concepts/architecture"
|
|
>
|
|
Understand how MCP connects clients, servers, and LLMs
|
|
</Card>
|
|
</CardGroup>
|