npm package: @remote-mcp/client
Description: > *Note: This project is currently under active development and is considered experimental. Expect breaking changes and potential issues.*
Author: Suhun Han
Latest version: 0.1.0

# Remote-MCP: Remote Model Context Protocol

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

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

<table>
<tr>
<td width="50%" style="height: 300px; vertical-align: middle;">
<img src="https://github.com/user-attachments/assets/86cf500e-b937-47fc-9ac1-db106ab7a6a3" style="max-height: 100%; object-fit: contain;">
</td>
<td width="50%" style="height: 300px; vertical-align: middle;">
<img src="https://github.com/user-attachments/assets/b06d7081-7748-4fc7-b972-e1c5e03245dd" style="max-height: 100%; object-fit: contain;">
</td>
</tr>
</table>

## Architecture

```mermaid
%%{init: {"flowchart": {"htmlLabels": false}} }%%
graph TD
    %% Modern, Bright Color Styling with white text
    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

    %% Current MCP Setup (Multiple Local Servers)
    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

    %% Vertical separator
    Current --> Proposed

    %% Proposed MCP Architecture (Decoupled)
    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

        %% Separated Resources
        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)

Yes, I know that the official MCP roadmap includes remote MCP support in the first quarter of 2025. However, the need for remote access was *immediate* for me, and likely for many others. This library was created to bridge that gap, providing a way to connect to a remote MCP server from a local MCP client *right now*, without waiting for future official implementations.

Note: I don't want this to be a sophisticated or overcomplicated thing. This **just works right now**.

## Getting Started

## Client Usage

### Use Publicly Published Package

This package is not yet published to the npm registry. (Coming soon)

Just put the following code in your MCP client settings, in here I'm using Claude as an example:

```json
{
  "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

```ts
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)

You can see some examples in the `examples` directory.

- [Cloudflare Workers](examples/cloudflare-workers)
- [Standalone Node.js](examples/simple-server)

### Code Your Own Remote MCP Server

After `npm install @remote-mcp/server`, you can your own remote MCP server like the following:

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

import { z } from "zod";

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

// Add example tool
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 = Number(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));
```

Then you can see like the following in your MCP client:

<img src="https://github.com/user-attachments/assets/86cf500e-b937-47fc-9ac1-db106ab7a6a3" width="450">

## 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

- [x] Basic *Type-safe* Client/Server Communication
  - [x] Basic MCP Command Support
  - [x] Basic MCP Tool Support
  - [x] Basic MCP Prompt Support
  - [ ] Crash-Safe Handling (WIP, top priority)
- [ ] Complete Event Subscription System
  - [ ] Resource change notifications
  - [ ] Tool/Prompt list change notifications
- [ ] HTTP Header Support
  - [x] Custom Headers
  - [ ] Authentication Middleware
- [ ] Basic error handling improvements
- [ ] Basic middleware support

### Framework Support

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

### Advanced Features

- [ ] Bidirectional communication
  - [ ] Server-to-client requests
  - [ ] Resource sharing between server/client
- [ ] Basic monitoring & logging

## Contribute

Contributions are welcome. See [CONTRIBUTING.md](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](LICENSE) file for details.

## References

*   [Model Context Protocol](https://modelcontextprotocol.org/)