MCP Tools

This repository contains tools for working with the Model Context Protocol (MCP).

MCP Proxy

A proxy for the Model Context Protocol that forwards requests to an HTTP endpoint.

Overview

The MCP proxy forwards data from stdin to a specified HTTP endpoint and returns responses to stdout. It implements a simple proxy that can be used to communicate with remote MCP-compatible servers.

Why golang?

This code runs on the client side. Many languages require a runtime and correct set of libraries installed to do this. Go compiles to a single executable file. This cuts down on deployment difficulties, user support requests, breaking updates to the runtime or other issues that are usually taken care of by providing an http endpoint instead of deployment.

Usage

./mcp-proxy [options]

Options

• -endpoint: HTTP endpoint to proxy requests to (default: "http://localhost:8080")
• -content-type: Content-Type header for HTTP requests (default: "application/json")
• -timeout: HTTP request timeout in seconds (default: 30)
• -buffer: Buffer size in KB for reading from stdin (default: 64)

Example

./mcp-proxy -endpoint="https://api.example.com/mcp" -content-type="application/json"

MCP Server

A server that loads and manages MCP executables from a directory and exposes them to clients via HTTP or stdio.

Overview

The MCP server loads MCP executables from a directory and serves them to clients. When clients request a list of tools, the server returns all tools from all loaded MCPs, namespaced by the MCP name. The server can run in either HTTP mode or stdio mode.

Usage

./mcp-server [options]

Options

• -mcp-dir: Directory containing MCP executables (default: "./mcps")
• -http: HTTP server address (default: ":8080")
• -name: Name of the MCP server (default: "MCP Server")
• -version: Version of the MCP server (default: "1.0.0")
• -stdio: Use stdio instead of HTTP (default: false)

MCP Directory Structure

The server expects a directory containing MCP executables. Each executable must implement the MCP protocol using stdio. The server will:

1. Scan the directory for executable files
2. Run each executable to discover the tools it provides
3. Make these tools available to clients with namespaced names (mcpname.toolname)

Building and Running with Make

This project includes a Makefile that simplifies building and running the components.

Building

Build all components (proxy, server, and examples):

make

Or build specific components:

make build-proxy    # Build only the proxy
make build-server   # Build only the server
make build-examples # Build only the example MCPs

Running

Start the MCP server in HTTP mode (after building examples and copying them to the mcps directory):

make run-server

Start the MCP server in stdio mode:

make run-server-stdio

Run the proxy to connect to the local MCP server:

make run-proxy

Testing

Test the proxy with a basic tools/list request (requires server running):

make test-proxy

Test specific example tools through the proxy (requires server running):

make test-hello   # Test the hello tool
make test-add     # Test the calculator's add tool

Example MCPs

The repository includes example MCPs that demonstrate how to implement MCP-compatible tools:

• hello-mcp: A simple MCP that provides a "hello" tool
• calculator-mcp: An MCP that provides math operations

Build and install the examples to the mcps directory:

make examples

Development Tasks

Format Go code:

make fmt

Run Go vet for code analysis:

make vet

Update and tidy Go dependencies:

make tidy

Clean build artifacts:

make clean

Install binaries to GOPATH/bin:

make install

License

MIT