remote-mcp
A type-safe solution to remote MCP communication, enabling effortless integration for centralized management of Model Context.
Documentation
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
%% 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
endWhy 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 way just works right now.
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
Just put the following code in your MCP client settings, in here I'm using Claude as an example:
{
"mcpServers": {
"remote-mcp": {
"command": "npx",
"args": ["-y", "@remote-mcp/client"],
"env": {
"REMOTE_MCP_URL": "http://localhost:9512",
"HTTP_HEADER_Authorization": "Bearer "
}
}
}
}Code Your Own Local MCP Server
Install requirements:
$ npm install @remote-mcp/client @trpc/client@next zodthen write your own code like the following:
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.
Code Your Own Remote MCP Server
After `npm install @remote-mcp/server`, you can your own remote MCP server like the following:
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:
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 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
Frequently asked questions
What is remote-mcp?
remote-mcp is A type-safe solution to remote MCP communication, enabling effortless integration for centralized management of Model Context.
How do I install remote-mcp?
Open the GitHub repository and follow its README. Most MCP servers are added to your client's MCP config, then called by your agent.
Is remote-mcp open source?
Yes — it is hosted on GitHub at https://github.com/ssut/Remote-MCP and has 200 stars.
Related MCP tools
A text-based user interface (TUI) client for interacting with MCP servers using Ollama. Features include multi-server, dynamic model switching, streaming res...
Model Context Protocol server for GraphQL TypeScript-based implementation.
MCP Server for SearXNG TypeScript-based implementation.
An MCP server for Azure DevOps TypeScript-based implementation.
📦 Repomix is a powerful tool that packs your entire repository into a single, AI-friendly file. Perfect for when you need to feed your codebase to Large Lan...
Mcp-use is the easiest way to interact with mcp servers with custom agents TypeScript-based implementation. Trusted by 8100+ developers.
Run your own MCP server? See who uses it and what to fix.
Measure it with TrackMCP