mcp -as-http

This MCP HTTP server exposes a REST API interface that translates standard MCP protocol commands into HTTP requests. It acts as a gateway, allowing clients to interact with MCP servers via familiar HTTP endpoints and bearer token authentication. The server reads an MCP configuration (mcp_servers.config.json) that defines which MCP servers to load, including the npm-based MCP packages to execute. Once running, you can issue MCP commands through the HTTP API (for example, tools/list or other MCP methods) and receive JSON-RPC style responses. To protect access, enable Bearer token authentication and provide the token in the Authorization header when making requests. You can also disable authentication for testing by setting DISABLE_AUTH=true in the environment file.

Common usage flows:

• Start the HTTP gateway with the configured MCP server(s).
• Use the HTTP API (POST /api/v1) to send MCP commands via the request body containing the command payload.
• Retrieve results and handle errors or logs via the API responses or container logs.

Prerequisites:

• Docker or Docker Compose installed
• (Optional) Rust toolchain if you plan to build locally
• Node.js (for MCP servers invoked via npx), npm installed inside the container as needed

Install and run with Docker (recommended):

# 1) Build the image (via provided script or manually):
# Build the image using docker-build.sh (recommended)
chmod +x docker-build.sh
./docker-build.sh

# 2) Run the container (example):
# Assuming the built image tag is mcp-http-server and you want port 3000
docker run -d \
  --name mcp-http-server \
  -p 3000:3000 \
  --env-file .env \
  mcp-http-server

Alternatively, use Docker Compose if you have a compose setup:

docker-compose up -d

Configuration file: mcp_servers.config.json

{
  "brave-search": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-brave-search"]
  }
}

Environment variables (example):

# HTTP Server Authentication
env HTTP_API_KEY=your-secret-api-key-here
env DISABLE_AUTH=false

# MCP Server Configuration
env MCP_CONFIG_FILE=mcp_servers.config.json
env MCP_SERVER_KEY=brave-search

If you build locally from source, you may also run directly with cargo/node as described in the repository docs.

Tips and notes:

• Ensure the MCP server package name in mcp_servers.config.json is accessible from the container (npm packages are installed as needed).
• If you encounter authentication issues, verify the HTTP_API_KEY matches the token you send in the Authorization header.
• For debugging, enable Rust logs by setting RUST_LOG=debug in the .env file or environment.
• Health checks can be validated via the provided health endpoints (curl requests against the API) and by inspecting container logs with docker logs or docker-compose logs.
• When changing ports, update the Docker run -p mappings or docker-compose ports accordingly.
• If using a local development setup, ensure Node.js and npm are installed if you need to pre-install MCP server packages globally for testing.