Remote

Remote-MCP provides a way for a local MCP client to talk to a remote MCP server. The client configuration uses a pre-published or locally built @remote-mcp/client, accessed via npx, which points at the remote MCP server URL. This enables you to manage and access model contexts and tooling hosted remotely as if they were local MCP resources. You can either use the publicly published client package or run your own local server stack that connects to remote services.

To get started, configure your MCP client to reference the remote endpoint (for example, http://localhost:9512) and, if needed, set an authorization header. The repository demonstrates two usage paths: using the publicly published client package via npx (remote-mcp) and coding your own local server that talks to the remote server. The remote server implements the MCP interfaces and exposes tools and prompts over HTTP (tRPC) that the client can consume, enabling actions like performing calculations or fetching resources from the remote backend.

Prerequisites:

• Node.js and npm/yarn installed on your machine
• Basic familiarity with npm packages and running Node projects

1. Install prerequisites

• Ensure you have Node.js (14+ recommended) and npm installed.

2. Use the public client directly with npx (no local install required):

# Example: start using the remote MCP client via npx
npx -y @remote-mcp/client

3. If you prefer bundling or developing locally, install client and server libraries in your project:

# In your project directory
npm install @remote-mcp/client @remote-mcp/server zod @trpc/client@next

4. Start the remote MCP server (if you’re implementing your own server) as shown in the example:

# Example: start a local remote MCP server using the provided example setup
npm install @remote-mcp/server
node -e "console.log('Replace with your server bootstrap as shown in README examples')" 

5. Run and configure your connection:

• Set REMOTE_MCP_URL to your remote server address (default http://localhost:9512)
• Provide any required HTTP headers for authentication (e.g., Bearer token)

Note: The README includes code snippets for both using the pre-published client via npx and for coding your own remote MCP server that exposes tools like a calculator.

Tips:

• The remote client expects a remote MCP server to expose its API over HTTP (tRPC). Ensure your remote server is reachable from the client.
• Environment variables can include REMOTE_MCP_URL and HTTP_HEADER_Authorization for secured endpoints.
• If you encounter connection issues, verify that the remote server URL is correct and that any auth tokens are valid.
• When running via npx, you can override the URL by setting REMOTE_MCP_URL in your environment.
• The architecture shown in the README illustrates a decoupled setup where the client connects to a remote MCP server, which in turn accesses databases or APIs. This separation helps scale and centralize model contexts.
• See the examples directory in the repository for concrete implementations like cloudflare-workers and standalone Node.js servers.