Remote-MCP
A type-safe solution to remote MCP communication, enabling effortless integration for centralized management of Model Context.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/ssut--remote-mcp)HTML
<a href="/listings/ssut--remote-mcp"><img src="/api/listings/ssut--remote-mcp/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
> *Note: This project is currently under active development and is considered experimental. Expect breaking changes and potential issues.*
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 238 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # 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
- ```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 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:
- ```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
- Install requirements:
- ```sh
- $ npm install @remote-mcp/client @trpc/client@next zod
- ```
- then write your own code like the following:
- ```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/)
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.