mcp-remote-server

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

1. Set your control plane URL:

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

2. 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.