mcp-remote-server
@sirmews
A declarative, composable model context protocol server that uses a remote config
Overview
What is mcp-remote-server?
A configurable Model Context Protocol (MCP) server that dynamically loads its capabilities from a remote configuration. It acts as a bridge between MCP clients and remote APIs by parsing a hosted JSON configuration defining tools, resources, and prompts.
How to use mcp-remote-server?
Install with bun install, set the MCP_CONTROL_PLANE_URL environment variable to your configuration endpoint, then run bun run index.ts.
Key features of mcp-remote-server?
- Dynamic configuration loaded from a remote JSON endpoint
- Configuration auto-refreshes every 60 seconds
- Supports tools, resources, and prompts as MCP primitives
- Handlers are remote HTTP/HTTPS API endpoints
- Handler responses must be JSON-compatible
Use cases of mcp-remote-server
—
FAQ from mcp-remote-server
How does mcp-remote-server load its capabilities?
It fetches a JSON configuration from the URL specified in the MCP_CONTROL_PLANE_URL environment variable. The configuration lists tools, resources, and prompts, each with a remote handler endpoint.
What are the handler API requirements?
Tool handlers must return JSON that the server wraps in an MCP tool response. Resource handlers must return content matching the specified mimeType. Prompt handlers can return either a string (wrapped in a message) or an array of MCP-formatted messages.
What are the limitations of mcp-remote-server?
Only HTTP/HTTPS handler endpoints are supported. The configuration must be accessible via HTTP GET. Handler responses must be JSON-compatible. The server runs locally only (standard MCP limitation).
How often is the configuration refreshed?
The configuration is automatically refreshed every 60 seconds.
What runtime does mcp-remote-server require?
It requires Bun (v1.1.32 or later) as the JavaScript runtime.
