📌Overview

Purpose: To provide a type-safe, bidirectional, and simple solution for remote communication using the Model Context Protocol (MCP), enabling immediate remote access and centralized management of model contexts.

Overview: Remote-MCP is designed to bridge the gap in remote access capabilities for MCP users who cannot wait for the official roadmap implementation. It allows local clients to connect seamlessly to remote MCP servers for managing model contexts effectively.

Key Features:

Type-Safe Communication: Ensures safe and reliable data transmission between local and remote servers, reducing errors and improving usability.
Bidirectional Support: Facilitates two-way communication, enabling both clients and servers to send and receive data, enhancing interactivity and responsiveness.

Remote-MCP: Remote Model Context Protocol

A type-safe, bidirectional and simple solution for remote MCP communication, allowing remote access and centralized management of model contexts.

Architecture

%%{init: {"flowchart": {"htmlLabels": false}} }%%
graph TD
    classDef client fill:#22c55e,stroke:#059669,stroke-width:2px,color:#ffffff
    classDef gateway fill:#06b6d4,stroke:#0891b2,stroke-width:2px,color:#ffffff
    classDef backend fill:#f97316,stroke:#ea580c,stroke-width:2px,color:#ffffff
    classDef resource fill:#8b5cf6,stroke:#7c3aed,stroke-width:2px,color:#ffffff
    classDef server fill:#06b6d4,stroke:#0891b2,stroke-width:2px,color:#ffffff

    linkStyle default stroke:#64748b,stroke-width:1.5px,stroke-dasharray: 5 5

    subgraph Current["Current Setup (Local)"]
        direction LR
        subgraph ClientGroup["Client"]
            A[Client]:::client
        end

        subgraph Servers["Local MCP Servers"]
            direction TB
            B1["Local MCP Server (DB)"]:::server -->|"DB Access"| C1[DB]:::resource
            B2["Local MCP Server (API 1)"]:::server -->|"API Access"| C2["Web API 1"]:::resource
            B3["Local MCP Server (API 2)"]:::server -->|"API Access"| C3["Web API 2"]:::resource
        end

        A -->|"MCP Protocol"| B1
        A -->|"MCP Protocol"| B2
        A -->|"MCP Protocol"| B3
    end

    Current --> Proposed

    subgraph Proposed["Proposed Architecture (Remote)"]
        direction LR
        D[Client/Host]:::client -->|"MCP Protocol"| E["Local MCP Server (@remote-mcp/client)"]:::server
        E <-->|"tRPC(HTTP)"| F["Remote MCP Server (@remote-mcp/server)"]:::backend

        F -->|"DB Access"| G1[DB]:::resource
        F -->|"API Access"| G2["Web API 1"]:::resource
        F -->|"API Access"| G3["Web API 2"]:::resource
    end

Why I Made This (Now)

The official MCP roadmap includes remote MCP support expected in early 2025. However, the need for remote access was immediate for many users. This library bridges that gap, providing a way to connect to a remote MCP server from a local MCP client right now, without waiting for official implementations.

This solution aims to be simple and functional immediately.

Getting Started

Note: This project is currently under active development and is considered experimental. Expect breaking changes and potential issues.

Client Usage

Use Publicly Published Package

Add the following to your MCP client settings (example uses Claude):

{
  "mcpServers": {
    "remote-mcp": {
      "command": "npx",
      "args": ["-y", "@remote-mcp/client"],
      "env": {
        "REMOTE_MCP_URL": "http://localhost:9512",
        "HTTP_HEADER_Authorization": "Bearer <token>"
      }
    }
  }
}

Code Your Own Local MCP Server

Install the requirements:

npm install @remote-mcp/client @trpc/client@next zod

Then write your own client code:

import { RemoteMCPClient } from "@remote-mcp/client";

const client = new RemoteMCPClient({
  remoteUrl: "http://localhost:9512",

  onError: (method, error) => console.error(`Error in ${method}:`, error)
});

void client.start();

Server Usage (Remote MCP Implementation)

Examples are available in the examples directory:

Cloudflare Workers
Standalone Node.js

Code Your Own Remote MCP Server

Install the server package:

npm install @remote-mcp/server

Example server code:

import { MCPRouter, LogLevel } from "@remote-mcp/server";
import { createHTTPServer } from '@trpc/server/adapters/standalone';
import { z } from "zod";

const mcpRouter = new MCPRouter({
  logLevel: LogLevel.DEBUG,
  name: "example-server",
  version: "1.0.0",
  capabilities: {
    logging: {},
  },
});

mcpRouter.addTool(
  "calculator",
  {
    description:
      "Perform basic calculations. Add, subtract, multiply, divide. Invoke this every time you need to perform a calculation.",
    schema: z.object({
      operation: z.enum(["add", "subtract", "multiply", "divide"]),
      a: z.string(),
      b: z.string(),
    }),
  },
  async (args) => {
    const a = Number(args.a);
    const b = Number(args.b);

    let result: number;
    switch (args.operation) {
      case "add":
        result = a + b;
        break;
      case "subtract":
        result = a - b;
        break;
      case "multiply":
        result = a * b;
        break;
      case "divide":
        if (b === 0) throw new Error("Division by zero");
        result = a / b;
        break;
    }

    return {
      content: [{ type: "text", text: `${result}` }],
    };
  },
);

const appRouter = mcpRouter.createTRPCRouter();

void createHTTPServer({
  router: appRouter,
  createContext: () => ({}),
}).listen(Number(process.env.PORT || 9512));

Packages

This repository contains:

@remote-mcp/client: Client library acting as a local MCP server, connecting to a remote implementation.
@remote-mcp/server: Server library for creating remotely accessible MCP services (used as the remote implementation).

Roadmap

Core Features

Framework Support

Nest.js Integration (@remote-mcp/nestjs)

Advanced Features

Bidirectional communication
- Server-to-client requests
- Resource sharing between server/client
Monitoring & logging

Contribute

Contributions are welcome. See CONTRIBUTING.md for details.

Disclaimer

This library is a complementary extension, not part of the official MCP specification, built upon existing MCP concepts.

License

This project is licensed under the MIT License. See the LICENSE file for details.

References

Model Context Protocol