Building AI agents, atomically
MCP Agent Example
This directory contains a complete example of a Model Context Protocol (MCP) implementation, including both client and server components. It demonstrates how to build an intelligent agent that leverages MCP tools via different transport methods.
Components
This example consists of two main components:
1. Example Client (example-client/)
An interactive agent that:
- Connects to MCP servers using multiple transport methods (STDIO, SSE, HTTP Stream)
- Dynamically discovers available tools
- Processes natural language queries
- Selects appropriate tools based on user intent
- Executes tools with extracted parameters (sync and async)
- Provides responses in a conversational format
The client features a universal launcher that supports multiple implementations:
- stdio: Blocking STDIO CLI client (default)
- stdio_async: Async STDIO client
- sse: SSE CLI client
- http_stream: HTTP Stream CLI client
- fastapi: FastAPI HTTP API server
2. Example MCP Server (example-mcp-server/)
A server that:
- Provides MCP tools and resources
- Supports both STDIO and SSE (HTTP) transport methods
- Includes example tools for demonstration
- Can be extended with custom functionality
- Features auto-reload for development
View Example MCP Server README
Understanding the Example
This example shows the flexibility of the MCP architecture with two distinct transport methods:
STDIO Transport
- The client launches the server as a subprocess
- Communication occurs through standard input/output
- No network connectivity required
- Good for local development and testing
SSE Transport
- The server runs as a standalone HTTP service
- The client connects via Server-Sent Events (SSE)
- Multiple clients can connect to one server
- Better for production deployments
HTTP Stream Transport
- The server exposes a single
/mcpHTTP endpoint for session negotiation, JSON-RPC calls, and termination - Supports GET (stream/session ID), POST (JSON-RPC payloads), and DELETE (session cancel)
- Useful for HTTP clients that prefer a single transport endpoint
Getting Started
Clone the repository:
git clone https://github.com/eigenwise/atomic-agents cd atomic-agents/atomic-examples/mcp-agentSet up the server:
cd example-mcp-server uv syncSet up the client:
cd ../example-client uv syncRun the example:
Using STDIO transport (default):
cd example-client uv run python -m example_client.main --client stdio # or simply: uv run python -m example_client.mainUsing async STDIO transport:
cd example-client uv run python -m example_client.main --client stdio_asyncUsing SSE transport (Deprecated):
# First terminal: Start the server cd example-mcp-server uv run python -m example_mcp_server.server --mode=sse # Second terminal: Run the client with SSE transport cd example-client uv run python -m example_client.main --client sseUsing HTTP Stream transport:
# First terminal: Start the server cd example-mcp-server uv run python -m example_mcp_server.server --mode=http_stream # Second terminal: Run the client with HTTP Stream transport cd example-client uv run python -m example_client.main --client http_streamUsing FastAPI client:
# First terminal: Start the MCP server cd example-mcp-server uv run python -m example_mcp_server.server --mode=http_stream # Second terminal: Run the FastAPI client cd example-client uv run python -m example_client.main --client fastapi # Then visit http://localhost:8000 for the API interface
Note: When using SSE, FastAPI or HTTP Stream transport, make sure the server is running before starting the client. The server runs on port 6969 by default.
Example Queries
The example includes a set of basic arithmetic tools that demonstrate the agent's capability to break down and solve complex mathematical expressions:
Available Demo Tools
- AddNumbers: Adds two numbers together (number1 + number2)
- SubtractNumbers: Subtracts the second number from the first (number1 - number2)
- MultiplyNumbers: Multiplies two numbers together (number1 * number2)
- DivideNumbers: Divides the first number by the second (handles division by zero)
Conversation Flow
When you interact with the agent, it:
- Analyzes your input to break it down into sequential operations
- Selects appropriate tools for each operation
- Shows its reasoning for each tool selection
- Executes the tools in sequence
- Maintains context between operations to build up the final result
For example, when calculating (5-9)*0.123:
- First uses
SubtractNumbersto compute (5-9) = -4 - Then uses
MultiplyNumbersto compute (-4 * 0.123) = -0.492 - Provides the final result with clear explanation
For more complex expressions like ((4**3)-10)/100)**2, the agent:
- Breaks down the expression into multiple steps
- Uses
MultiplyNumbersrepeatedly for exponentiation (4**3) - Uses
SubtractNumbersfor the subtraction operation - Uses
DivideNumbersfor division by 100 - Uses
MultiplyNumbersagain for the final squaring operation
Each step in the conversation shows:
- The tool being executed
- The parameters being used
- The intermediate result
- The agent's reasoning for the next step
Try queries like:
# Simple arithmetic
"What is 2+2?"
# Uses AddNumbers tool directly
# Complex expressions
"(5-9)*0.123"
# Uses SubtractNumbers followed by MultiplyNumbers
# Multi-step calculations
"((4**3)-10)/100)**2"
# Uses multiple tools in sequence to break down the complex expression
# Natural language queries
"Calculate the difference between 50 and 23, then multiply it by 3"
# Understands natural language and breaks it down into appropriate tool calls