Content
# MCP Test
Small Python workspace for experimenting with Model Context Protocol (MCP) servers, clients, gateways, and third-party MCP integrations.
The repository contains examples for:
- Creating a local MCP server with `FastMCP`
- Connecting to an MCP server over `stdio`
- Running an MCP server over streamable HTTP
- Loading MCP tools through LangChain MCP adapters
- Trying community/third-party MCP servers such as DuckDuckGo, Tavily, and AWS ECS
- Mounting/proxying external MCP servers behind a FastMCP gateway
## Project Structure
```text
.
|-- create_mcp/
| |-- first_mcp_server_stdio.py # Local stdio FastMCP server
| |-- python_client.py # Native MCP stdio client
| `-- langchain_client.py # LangChain MCP client for stdio server
|-- http_mcp/
| |-- http_mcp.py # FastMCP HTTP server on port 8050
| `-- langchain_client.py # LangChain client for stdio + HTTP MCP servers
|-- 3rd party mcp/
| |-- community_mcp.py # DuckDuckGo MCP server example
| |-- tavily_mcp.py # Tavily remote MCP example
| |-- aws.py # AWS ECS MCP + Groq model example
| `-- aws_tools_llm.py # AWS ECS MCP + LangGraph/Gemini example
|-- 4th_mcp_gateway/
| `-- mcp.py # FastMCP gateway/proxy example
|-- main.py # Minimal Python entry point
|-- pyproject.toml # Python project metadata and dependencies
|-- package.json # Basic Node package metadata
`-- uv.lock # uv lockfile
```
## Requirements
- Python `>=3.14` as configured in `pyproject.toml`
- [`uv`](https://docs.astral.sh/uv/) for dependency installation and running scripts
- `uvx` for examples that launch third-party MCP servers
- API keys for examples that call hosted LLMs or remote MCP services
- AWS credentials/profile for AWS ECS MCP examples
## Setup
Install dependencies:
```powershell
uv sync
```
Activate the virtual environment if you want to run Python directly:
```powershell
.\.venv\Scripts\Activate.ps1
```
Or run scripts through `uv run`, which uses the project environment automatically.
## Environment Variables
Create a local `.env` file for secrets used by remote examples. This file is ignored by git and should stay only on your machine.
```env
TAVILY_API_KEY="your-tavily-api-key"
GROQ_API_KEY="your-groq-api-key"
GOOGLE_API_KEY="your-google-api-key"
AWS_REGION="ap-south-1"
```
Do not commit real API keys. If you want to share required environment variables with other developers, create an `.env.example` file with placeholder values. `.env.example` is allowed by `.gitignore`, while `.env` and `.env.*` remain ignored.
Some prototype scripts currently contain hard-coded local paths or credentials; replace those with environment variables before sharing or using the project beyond local testing.
## Running the Examples
### Basic project entry point
```powershell
uv run python main.py
```
### Local stdio MCP server
Start the server:
```powershell
uv run python .\create_mcp\first_mcp_server_stdio.py
```
The server exposes two tools:
- `fetch`
- `process`
### Native Python stdio client
This client starts `first_mcp_server_stdio.py`, initializes an MCP session, and prints the available tools.
```powershell
uv run python .\create_mcp\python_client.py
```
### LangChain stdio client
```powershell
uv run python .\create_mcp\langchain_client.py
```
Before running, update the hard-coded Python executable and script paths in the file so they match your local checkout.
### HTTP MCP server
Start the HTTP server:
```powershell
uv run python .\http_mcp\http_mcp.py
```
The server listens on:
```text
http://localhost:8050/mcp
```
It exposes:
- `http_fetch`
- `http_process`
### LangChain HTTP client
In another terminal, after starting the HTTP server:
```powershell
uv run python .\http_mcp\langchain_client.py
```
This example loads tools from both the local stdio server and the HTTP MCP server.
### DuckDuckGo community MCP example
```powershell
uv run python '.\3rd party mcp\community_mcp.py'
```
This uses `uvx duckduckgo-mcp-server`, loads the exposed tools, and invokes the first search tool.
### Tavily remote MCP example
Set `TAVILY_API_KEY` in `.env`, then run:
```powershell
uv run python '.\3rd party mcp\tavily_mcp.py'
```
This connects to Tavily's remote MCP endpoint and lists available tools.
### AWS ECS MCP examples
These examples launch the AWS Labs ECS MCP server through `uvx`:
```powershell
uv run python '.\3rd party mcp\aws.py'
uv run python '.\3rd party mcp\aws_tools_llm.py'
```
You need valid AWS configuration before running them. The Groq example reads `GROQ_API_KEY` from `.env`, and the Gemini/LangGraph example reads `GOOGLE_API_KEY` from `.env`.
For write-capable operations, review the AWS ECS MCP server settings carefully before enabling any write or sensitive-data options.
### MCP gateway/proxy
```powershell
uv run python .\4th_mcp_gateway\mcp.py
```
This starts a FastMCP HTTP server on port `8050` and mounts a proxied external MCP server.
## Notes
- `create_mcp/langchain_client.py` and `http_mcp/langchain_client.py` include absolute Windows paths from the original local environment. Update them to use your current project path before running.
- `3rd party mcp/tavily_mcp.py` expects `TAVILY_API_KEY` from `.env`.
- `3rd party mcp/aws.py` expects `GROQ_API_KEY` from `.env`.
- `3rd party mcp/aws_tools_llm.py` expects `GOOGLE_API_KEY` from `.env`.
- Some scripts reference packages such as `python-dotenv` or `langgraph`; install them if your current lockfile does not include them.
- `package.json` is present, but the working examples in this repository are Python based.
## Security Checklist
- Keep `.env` out of git.
- Use `.env.example` for non-secret placeholders when documenting required variables.
- Replace hard-coded API keys with environment variables.
- Avoid committing local machine paths.
- Review third-party MCP tool permissions before connecting them to an LLM agent.
