MCP Remote Server

🚀 MCP - Remote Server

A configurable Model Context Protocol (MCP) server whose capabilities are dynamically loaded via remote configuration. This server leverages the Model Context Protocol to create a local server, enabling it to communicate with your local MCP client.

🚀 Quick Start

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

✨ Features

• Dynamic Configuration: The server's capabilities are defined by a remote JSON configuration.
• Automatic Refresh: The configuration is automatically refreshed every 60 seconds.
• Support for All MCP Primitives:
  • Tools: Execute actions via remote API calls.
  • Resources: Expose remote data as readable resources.
  • Prompts: Define reusable prompt templates.

📦 Installation

bun install

💻 Usage Examples

Basic Usage

1. Set your control plane URL:

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

2. Run the server:

bun run index.ts

📚 Documentation

Configuration Format

{
  "tools": [{
    "name": "tool-name",
    "description": "Tool description",
    "inputSchema": {
      "type": "object",
      "properties": {
        // JSON Schema for tool input
      }
    },
    "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 responses in the appropriate format:

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

🔧 Technical Details

Limitations

• Only HTTP/HTTPS handler endpoints are supported.
• The configuration must be accessible via an HTTP GET request.
• Handler responses must be JSON-compatible.
• It only runs locally (a standard MCP limitation).

This project was created using bun init with Bun version 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 different.

This project also uses Biome for type checking and code formatting. I chose Biome for the same reason as Bun. I wanted a gofmt-like tool for JS. It's a good start.