mcp-proxy

This MCP server acts as a Python-based client and API gateway for connecting to a standalone MCP server (Node or Python) over stdio, while exposing a FastAPI interface for frontend integration. It uses Anthropic Claude to generate natural language responses, decide when to invoke tools, and manage multi-turn reasoning with external tools exposed by the MCP server. Through the embedded FastAPI app, you can query tools, list available tools, and retrieve server metadata. The client handles tool invocation, conversation state, and structured responses (including markdown, code blocks, and chart data) to seamlessly integrate with frontend experiences.

To use it, first ensure you have a running MCP server (Node or Python) that the client can connect to, and obtain an Anthropic API key. Start the MCP client server (the FastAPI server) by running the Python module specified in the configuration. Once running, the API is accessible at http://localhost:8000 by default. The API exposes endpoints such as POST /query to send a user query and receive Claude-generated responses, GET /tools to list available tools, and GET /server-name to return the server identifier. The client also provides a CLI for experimentation via python client.py, useful for local testing and debugging of tool invocations.

The workflow typically looks like: your frontend sends a query to the /query endpoint; the Claude-based client decides which tools to call, executes them via the MCP server, and returns a structured response to display to users. You can customize the Claude system prompt and tool schemas as needed by editing client.py and related configuration in your environment.

Prerequisites

• Python 3.10+
• An MCP server (Node or Python) that your client can connect to via stdio
• An Anthropic API Key for Claude

Step 1 - Clone the repository

git clone https://github.com/Kiran1689/mcp-proxy-server
cd mcp-proxy-server

Step 2 - Set up a Python virtual environment and install dependencies

python -m venv .venv
source .venv/bin/activate  # On Windows use: .venv\Scripts\activate
pip install -r requirements.txt

Step 3 - Configure environment variables Create a .env file in the project root with your Anthropic key:

ANTHROPIC_API_KEY=your-anthropic-api-key-here

Step 4 - Run the MCP Proxy client server

python -m client_server

Step 5 - Optional: Run the FastAPI server directly for testing

uvicorn client_server:app --reload

Step 6 - Verify the server is up

• Open http://localhost:8000 to access the API endpoints like /query, /tools, and /server-name.

Environment variables:

• ANTHROPIC_API_KEY must be set to your Claude API key.
• You can add additional environment variables as needed for your MCP server configuration.

Configuration tips:

• Ensure the MCP server you connect to is reachable and compatible (Node or Python).
• If you modify tool schemas, the client will detect them at runtime from the MCP server.
• Check logs for tool invocation details and Claude responses to troubleshoot issues.

Common issues:

• Invalid or missing Anthropic API key leads to Claude initialization failure.
• Mismatched MCP server path or command can cause the client to fail to connect; verify the path/config used by client.py.
• Port conflicts or firewalls may block the FastAPI endpoints; ensure port 8000 is available or configure uvicorn accordingly.