mcp-remote-server

Here's an enhanced README with more technical details based on the codebase:

A configurable Model Context Protocol (MCP) server that dynamically loads its capabilities from a remote configuration. This leverages the ModelContextProtocol to create a local server that can communicate with your local MCP client.

Overview

mcp-remote-server acts as a bridge between MCP clients and remote APIs. It parses a remote hosted configuration (specified via MCP_CONTROL_PLANE_URL) that contains a list of tools, resources, and prompts, each pointing to remote API endpoints.

Key Features

Dynamic Configuration: Server capabilities are defined through a remote JSON configuration
Auto-Refresh: Configuration is automatically refreshed every 60 seconds
Supports All MCP Primitives:
- Tools: Execute actions through remote API calls
- Resources: Expose remote data as readable resources
- Prompts: Define reusable prompt templates

Configuration Format

{
  "tools": [{
    "name": "tool-name",
    "description": "Tool description",
    "inputSchema": {
      "type": "object",
      "properties": {
        // JSON Schema for tool inputs
      }
    },
    "handler": "https://api.example.com/tool-endpoint"
  }],
  "resources": [{
    "uri": "resource://identifier",
    "name": "Resource Name",
    "description": "Resource description",
    "mimeType": "application/json",
    "handler": "https://api.example.com/resource-endpoint"
  }],
  "prompts": [{
    "name": "prompt-name",
    "description": "Prompt description",
    "arguments": [{
      "name": "arg-name",
      "description": "Argument description",
      "required": true
    }],
    "handler": "https://api.example.com/prompt-endpoint"
  }]
}

Handler API Requirements

Remote handlers must return appropriately formatted responses:

Tool Handlers: Return JSON that will be stringified and wrapped in an MCP tool response
Resource Handlers: Return content that matches the specified mimeType
Prompt Handlers: Return either a string (automatically wrapped in a message) or an array of MCP-formatted messages

Installation

bun install

Usage

Set your control plane URL:

export MCP_CONTROL_PLANE_URL="https://your-config-endpoint"

Run the server:

bun run index.ts

Limitations

Only supports HTTP/HTTPS handler endpoints
Configuration must be accessible via HTTP GET request
Handler responses must be JSON-compatible
Runs locally only (standard MCP limitation)

This project was created using bun init in bun v1.1.32. Bun is a fast all-in-one JavaScript runtime. I chose Bun because it's fast and I wanted to try something a little different.

This project also uses Biome for type checking and linting. I chose Biome for the same reason as Bun. I wanted something different and I wish JS had a gofmt-like tool. This is a good start.

mcp-remote-server