Skip to main content

Build an MCP client

In this tutorial, you'll learn how to build an LLM-powered chatbot client that connects to MCP servers.

Before you begin, it helps to have gone through our Build an MCP Server tutorial so you can understand how clients and servers communicate.

PythonTypeScriptJavaKotlinC#RubyRust

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
  • You must use the Python MCP SDK 2.0.0 or higher

Setting Up Your Environment

First, create a new Python project with uv:

macOS/LinuxWindows

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

# Create virtual environment
uv venv

# Activate virtual environment
source .venv/bin/activate

# Install required packages
uv add mcp anthropic python-dotenv

# Remove boilerplate files
rm main.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:

echo "ANTHROPIC_API_KEY=your-api-key-goes-here" > .env

Add .env to your .gitignore:

echo ".env" >> .gitignore

Warning

Make sure you keep your ANTHROPIC_API_KEY secure!

Creating the Client

Imports and Setup

First, let's set up our imports and the pieces the rest of the file shares:

import asyncio
import sys

from mcp import Client, StdioServerParameters
from mcp.client.stdio import stdio_client
from mcp_types import TextContent

from anthropic import Anthropic
from dotenv import load_dotenv

load_dotenv()  # load environment variables from .env

MODEL = "claude-opus-5"
anthropic = Anthropic()

Client is the single object your program talks to the server through. Listing the tools, calling one, reading a resource: each of those is a method on it.

Server Connection Management

Next, we'll work out which process to launch for a given server script:

def server_params(server_script_path: str) -> StdioServerParameters:
    """Describe the subprocess that runs an MCP server

    Args:
        server_script_path: Path to the server script (.py or .js)
    """
    if server_script_path.endswith(".py"):
        command = "python"
    elif server_script_path.endswith(".js"):
        command = "node"
    else:
        raise ValueError("Server script must be a .py or .js file")

    return StdioServerParameters(command=command, args=[server_script_path])

StdioServerParameters is configuration, not a connection. stdio_client() turns it into a stdio transport, and Client opens that transport when you enter its async with block. We'll do both in main().

Query Processing Logic

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

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

    tool_list = await client.list_tools()
    available_tools = [{
        "name": tool.name,
        "description": tool.description,
        "input_schema": tool.input_schema
    } for tool in tool_list.tools]

    # Initial Claude API call
    response = anthropic.messages.create(
        model=MODEL,
        max_tokens=1000,
        messages=messages,
        tools=available_tools
    )

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

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

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

            tool_results.append({
                "type": "tool_result",
                "tool_use_id": content.id,
                "content": "\n".join(
                    block.text
                    for block in result.content
                    if isinstance(block, TextContent)
                ),
                "is_error": result.is_error
            })

    if tool_results:
        messages.append({"role": "assistant", "content": response.content})
        messages.append({"role": "user", "content": tool_results})

        # Get next response from Claude
        response = anthropic.messages.create(
            model=MODEL,
            max_tokens=1000,
            messages=messages,
            tools=available_tools
        )

        for content in response.content:
            if content.type == 'text':
                final_text.append(content.text)

    return "\n".join(final_text)

call_tool returns a CallToolResult. Its content is a list of blocks, which is why we narrow to TextContent before reading .text. A tool that raises does not raise here: it answers with is_error set, and passing that flag on lets Claude read the message and try something else.

Interactive Chat Interface

Now we'll add the chat loop:

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

    while True:
        try:
            query = (await asyncio.to_thread(input, "\nQuery: ")).strip()
        except EOFError:
            break

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

        try:
            response = await process_query(client, query)
            print("\n" + response)
        except Exception as e:
            print(f"\nError: {e}")

input() blocks, so it runs on a worker thread. That keeps the event loop free to service the connection while you type.

Main Entry Point

Finally, we'll add the main execution logic:

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

    async with Client(stdio_client(server_params(sys.argv[1]))) as client:
        tool_list = await client.list_tools()
        tool_names = [tool.name for tool in tool_list.tools]
        print("\nConnected to server with tools:", tool_names)

        await chat_loop(client)


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

That async with is the entire connection lifecycle. Entering it launches the server and agrees a protocol version with it; leaving it disconnects and shuts the subprocess down. There is nothing to close by hand.

You can find the complete client.py file here.

Key Components Explained

1. Client Initialization

  • A single Client carries the connection, and async with is its whole lifecycle
  • There is no connect/close pair to call and nothing to clean up afterwards
  • Configures the Anthropic client for Claude interactions

2. Server Connection

  • Supports both Python and Node.js servers
  • Validates server script type
  • Launches the server as a subprocess and speaks stdio to it
  • Lists the available tools once the connection is open

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

  • Leaving the async with block disconnects and shuts the server subprocess down
  • A failing query is reported without ending the session
  • Typing quit, or closing standard input, exits cleanly

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:

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 .../quickstart-resources/weather-server-python/weather.py

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:

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

    • Check result.is_error rather than expecting a failing tool to raise
    • Provide meaningful error messages
    • Gracefully handle connection issues

  2. Resource Management

    • Let the async with block own the connection
    • Keep it open for as long as you need the server
    • Handle server disconnections

  3. Security

    • Store API keys securely in .env
    • Validate server responses
    • Be cautious with tool permissions

  4. Tool Names

    • Tool names can be validated according to the format specified here
    • If a tool name conforms to the specified format, it should not fail validation by an MCP client

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 raising read_timeout_seconds on the Client

Next steps

Example servers

Check out our gallery of official MCP servers and implementations

Edit on GitHub