Skip to content
Back to search

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.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ssut--remote-mcp/badge.svg)](/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

i

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)

  1. # Remote-MCP: Remote Model Context Protocol
  2. A **type-safe, bidirectional and simple** solution for **remote MCP communication**, allowing remote access and centralized management of model contexts.
  3. ![preview](https://github.com/user-attachments/assets/a16804b9-8378-493c-8ca8-f61839458cde)
  4. ## Architecture
  5. ```mermaid
  6. %%{init: {"flowchart": {"htmlLabels": false}} }%%
  7. graph TD
  8. %% Modern, Bright Color Styling with white text
  9. classDef client fill:#22c55e,stroke:#059669,stroke-width:2px,color:#ffffff
  10. classDef gateway fill:#06b6d4,stroke:#0891b2,stroke-width:2px,color:#ffffff
  11. classDef backend fill:#f97316,stroke:#ea580c,stroke-width:2px,color:#ffffff
  12. classDef resource fill:#8b5cf6,stroke:#7c3aed,stroke-width:2px,color:#ffffff
  13. classDef server fill:#06b6d4,stroke:#0891b2,stroke-width:2px,color:#ffffff
  14. linkStyle default stroke:#64748b,stroke-width:1.5px,stroke-dasharray: 5 5
  15. %% Current MCP Setup (Multiple Local Servers)
  16. subgraph Current["Current Setup (Local)"]
  17. direction LR
  18. subgraph ClientGroup["Client"]
  19. A[Client]:::client
  20. end
  21. subgraph Servers["Local MCP Servers"]
  22. direction TB
  23. B1["Local MCP Server (DB)"]:::server -->|"DB Access"| C1[DB]:::resource
  24. B2["Local MCP Server (API 1)"]:::server -->|"API Access"| C2["Web API 1"]:::resource
  25. B3["Local MCP Server (API 2)"]:::server -->|"API Access"| C3["Web API 2"]:::resource
  26. end
  27. A -->|"MCP Protocol"| B1
  28. A -->|"MCP Protocol"| B2
  29. A -->|"MCP Protocol"| B3
  30. end
  31. %% Vertical separator
  32. Current --> Proposed
  33. %% Proposed MCP Architecture (Decoupled)
  34. subgraph Proposed["Proposed Architecture (Remote)"]
  35. direction LR
  36. D[Client/Host]:::client -->|"MCP Protocol"| E["Local MCP Server (@remote-mcp/client)"]:::server
  37. E <-->|"tRPC(HTTP)"| F["Remote MCP Server (@remote-mcp/server)"]:::backend
  38. %% Separated Resources
  39. F -->|"DB Access"| G1[DB]:::resource
  40. F -->|"API Access"| G2["Web API 1"]:::resource
  41. F -->|"API Access"| G3["Web API 2"]:::resource
  42. end
  43. ```
  44. ## Why I Made This (Now)
  45. 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.
  46. Note: I don't want this to be a sophisticated or overcomplicated thing. This way **just works right now**.
  47. ## Getting Started
  48. > *Note: This project is currently under active development and is considered experimental. Expect breaking changes and potential issues.*
  49. ## Client Usage
  50. ### Use Publicly Published Package
  51. Just put the following code in your MCP client settings, in here I'm using Claude as an example:
  52. ```json
  53. {
  54. "mcpServers": {
  55. "remote-mcp": {
  56. "command": "npx",
  57. "args": ["-y", "@remote-mcp/client"],
  58. "env": {
  59. "REMOTE_MCP_URL": "http://localhost:9512",
  60. "HTTP_HEADER_Authorization": "Bearer <token>"
  61. }
  62. }
  63. }
  64. }
  65. ```
  66. ### Code Your Own Local MCP Server
  67. Install requirements:
  68. ```sh
  69. $ npm install @remote-mcp/client @trpc/client@next zod
  70. ```
  71. then write your own code like the following:
  72. ```ts
  73. import { RemoteMCPClient } from "@remote-mcp/client";
  74. const client = new RemoteMCPClient({
  75. remoteUrl: "http://localhost:9512",
  76. onError: (method, error) => console.error(`Error in ${method}:`, error)
  77. });
  78. void client.start();
  79. ```
  80. ## Server Usage (Remote MCP Implementation)
  81. You can see some examples in the `examples` directory.
  82. - [Cloudflare Workers](examples/cloudflare-workers)
  83. - [Standalone Node.js](examples/simple-server)
  84. ### Code Your Own Remote MCP Server
  85. After `npm install @remote-mcp/server`, you can your own remote MCP server like the following:
  86. ```typescript
  87. import { MCPRouter, LogLevel } from "@remote-mcp/server";
  88. import { createHTTPServer } from '@trpc/server/adapters/standalone';
  89. import { z } from "zod";
  90. // Create router instance
  91. const mcpRouter = new MCPRouter({
  92. logLevel: LogLevel.DEBUG,
  93. name: "example-server",
  94. version: "1.0.0",
  95. capabilities: {
  96. logging: {},
  97. },
  98. });
  99. // Add example tool
  100. mcpRouter.addTool(
  101. "calculator",
  102. {
  103. description:
  104. "Perform basic calculations. Add, subtract, multiply, divide. Invoke this every time you need to perform a calculation.",
  105. schema: z.object({
  106. operation: z.enum(["add", "subtract", "multiply", "divide"]),
  107. a: z.string(),
  108. b: z.string(),
  109. }),
  110. },
  111. async (args) => {
  112. const a = Number(args.a);
  113. const b = Number(args.b);
  114. let result: number;
  115. switch (args.operation) {
  116. case "add":
  117. result = Number(a) + b;
  118. break;
  119. case "subtract":
  120. result = a - b;
  121. break;
  122. case "multiply":
  123. result = a * b;
  124. break;
  125. case "divide":
  126. if (b === 0) throw new Error("Division by zero");
  127. result = a / b;
  128. break;
  129. }
  130. return {
  131. content: [{ type: "text", text: `${result}` }],
  132. };
  133. },
  134. );
  135. const appRouter = mcpRouter.createTRPCRouter();
  136. void createHTTPServer({
  137. router: appRouter,
  138. createContext: () => ({}),
  139. }).listen(Number(process.env.PORT || 9512));
  140. ```
  141. Then you can see like the following in your MCP client:
  142. <img src="https://github.com/user-attachments/assets/86cf500e-b937-47fc-9ac1-db106ab7a6a3" width="450">
  143. ## Packages
  144. This repository contains:
  145. * `@remote-mcp/client`: Client library acting as a local MCP server, connecting to a remote implementation.
  146. * `@remote-mcp/server`: Server library for creating remotely accessible MCP services (used as the remote implementation).
  147. ## Roadmap
  148. ### Core Features
  149. - [x] Basic *Type-safe* Client/Server Communication
  150. - [x] Basic MCP Command Support
  151. - [x] Basic MCP Tool Support
  152. - [x] Basic MCP Prompt Support
  153. - [ ] Crash-Safe Handling (WIP, top priority)
  154. - [ ] Complete Event Subscription System
  155. - [ ] Resource change notifications
  156. - [ ] Tool/Prompt list change notifications
  157. - [ ] HTTP Header Support
  158. - [x] Custom Headers
  159. - [ ] Authentication Middleware
  160. - [ ] Basic error handling improvements
  161. - [ ] Basic middleware support
  162. ### Framework Support
  163. - [ ] Nest.js Integration (`@remote-mcp/nestjs`)
  164. ### Advanced Features
  165. - [ ] Bidirectional communication
  166. - [ ] Server-to-client requests
  167. - [ ] Resource sharing between server/client
  168. - [ ] Basic monitoring & logging
  169. ## Contribute
  170. Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
  171. ## Disclaimer
  172. This library is a complementary extension, not part of the official MCP specification, built upon existing MCP concepts.
  173. ## License
  174. This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
  175. ## References
  176. * [Model Context Protocol](https://modelcontextprotocol.org/)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.