MCP Remote Shell Gateway

An implementation of the Model Context Protocol (MCP) Server Remote Access Client, leveraging SSH for secure connectivity to remote MCP infrastructure. This utility permits local agents to invoke tools and access data managed by remote servers, establishing an encrypted communication conduit for all MCP exchanges.

Core Capabilities

• Establish secure shell sessions to arbitrary remote MCP nodes.
• Encapsulate and relay all subsequent MCP protocol messages via the encrypted SSH tunnel.
• Native support for public/private key credential mechanisms.
• Full fidelity proxying for MCP primitives: tool invocation, prompt interaction, and resource retrieval.

Deployment Instructions

For environments managed by uv, integrate this package by:

uv add m2m-mcp-server-ssh-client

If utilizing pip for dependency resolution:

pip install m2m-mcp-server-ssh-client

To install directly from the source repository for development:

git clone https://github.com/Machine-To-Machine/m2m-mcp-server-ssh-client.git
cd m2m-mcp-server-ssh-client
pip install -e .

To initiate the gateway process within your execution context:

uv run m2m-mcp-server-ssh-client

Operational Scenarios

1. Immediate Access via Public Demonstration Endpoint

We provision a publicly accessible gateway server equipped with diverse pre-configured MCP functionalities for immediate testing. (This resource is transient until the decentralized MCP registry is fully operational.)

This demonstration server hosts integrations for knowledge sources like HackerNews, MLB Statistics, and Formula 1 data.

Integration with Claude Agents

Incorporate the following configuration stanza into your Claude Desktop settings:

"mcpServers": {
  "remote-mcp-tools": {
    "command": "uvx",
    "args": [
      "m2m-mcp-server-ssh-client", 
      "--host", "mcp-beta.machinetomachine.ai", 
      "--port", "8022", 
      "--use-key-server"
    ]
  }
}

Command-Line Invocation

# Connect to the M2M public gateway with automated credential exchange
uv run m2m-mcp-server-ssh-client --host mcp-beta.machinetomachine.ai --use-key-server

2. Local Environment Simulation

Refer to m2m-mcp-server-ssh-server documentation for setting up your own localized SSH infrastructure.

For testing against a self-hosted backend:

# Connect to a locally listening MCP SSH gateway
uv run m2m-mcp-server-ssh-client

The preceding command defaults to connecting to an SSH listener on TCP port 8022.

During local validation, credential provisioning is streamlined using the integrated key server:

# Leverage the key server for transparent key registration (requires server flag --run-key-server)
uv run m2m-mcp-server-ssh-client --use-key-server

This attempts to communicate with the key server instance presumed to be running on port 8000.

3. Connecting to Enterprise or Private Infrastructure

To access your independently provisioned MCP gateway:

# Utilizing pre-existing SSH credentials
uv run m2m-mcp-server-ssh-client --host your-server.example.com --client-key ~/.ssh/your_key --known-hosts ~/.ssh/known_hosts

Key management can be simplified by deploying the key exchange service on your remote host and configuring the client to use it.

Integration with Autonomous Platforms

Claude Desktop Configuration Snippet

Incorporate this into the platform's configuration manifest:

"mcpServers": {
  "remote-mcp-tools": {
    "command": "uvx",
    "args": [
      "m2m-mcp-server-ssh-client", 
      "--host", "mcp-beta.machinetomachine.ai", 
      "--port", "8022", 
      "--use-key-server"
    ]
  }
}

MCP Registry Inspection

For introspection or diagnostics of available remote capabilities:

npx @modelcontextprotocol/inspector -- uvx m2m-mcp-server-ssh-client --host mcp-beta.machinetomachine.ai --port 8022 --use-key-server

Operational Parameters

Command Line Arguments

• --host: Destination address of the remote SSH broker (Default: "localhost")
• --port: Network port utilized by the remote SSH broker (Default: 8022)
• --username: The user identity for the SSH session (Default: "mcp")
• --client-key: Path to the client's private authentication key file (Default: "~/.ssh/m2m_mcp_server_ssh_client")
• --known-hosts: Location of the file containing trusted host public keys (Default: "~/.ssh/known_hosts")
• --passphrase: Secret phrase required to unlock the private key (Default: null)
• --disable-host-key-checking: Bypass cryptographic verification of the remote host's identity (Default: False)
• --log-level: Verbosity setting for runtime diagnostics (Default: INFO)

Illustrative Examples

Establishing Basic Remote Conduit

Initiate a session to a remote gateway service listening on port 8022:

uvx m2m-mcp-server-ssh-client --host mcp.example.com

Utilizing Specific Authentication Material

Designate a unique SSH key pair for connection validation:

uvx m2m-mcp-server-ssh-client --host mcp.example.com --client-key ~/.ssh/mcp_custom_key

If the specified key is protected by a passphrase:

uvx m2m-mcp-server-ssh-client --host mcp.example.com --client-key ~/.ssh/mcp_custom_key --passphrase "your-passphrase"

Engaging Verbose Debug Mode

Activate extensive logging to diagnose connection establishment failures:

uvx m2m-mcp-server-ssh-client --host mcp.example.com --log-level DEBUG

Key Server Orchestration

The SSH Client is engineered to interact with an auxiliary key server for dynamic key provisioning and trust establishment:

uvx m2m-mcp-server-ssh-client --host mcp.example.com --use-key-server

When the key server mechanism is active:

1. The client fetches the server's public certificate from http://host:key-server-port/server_pub_key
2. The client registers its own public key via http://host:key-server-port/register
3. A transient known_hosts entry is synthesized for the SSH handshake

This dynamic mode supersedes the use of explicit --known-hosts and --disable-host-key-checking parameters.

Bypassing Host Identity Verification

🚨 CRITICAL SECURITY ALERT: Employing --disable-host-key-checking renders the connection susceptible to Man-in-the-Middle interception. Exercise extreme caution; restrict usage to isolated or development/testing networks.

uvx m2m-mcp-server-ssh-client --host localhost --disable-host-key-checking

Configuration for Claude Desktop (Alternative Format)

Adaptation for the desktop environment:

"mcpServers": {
  "remote-servers": {
    "command": "uvx",
    "args": [
      "m2m-mcp-server-ssh-client", 
      "--host", "example.com", 
      "--port", "8022", 
      "--username", "mcp"
    ]
  }
}

For a more hardened setup specifying credentials:

"mcpServers": {
  "remote-servers": {
    "command": "uvx",
    "args": [
      "m2m-mcp-server-ssh-client",
      "--host", "mcp-server.example.com",
      "--port", "8022",
      "--username", "claude-mcp",
      "--client-key", "~/.ssh/claude_mcp_key",
      "--known-hosts", "~/.ssh/mcp_remote_server"
    ]
  }
}

Internal Mechanics

The MCP Gateway Client initiates a secure shell session targeting the remote infrastructure running the corresponding MCP Server SSH Daemon (see m2m-mcp-server-ssh-server). The process involves:

1. Instantiating a local binding proxy that mirrors the functionality advertised by the remote MCP system.
2. Transparently piping all subsequent MCP API interactions through the established SSH tunnel.
3. Relay the remote server's output back to the originating local invocation context.

This architecture grants the illusion that remote computation modules are executing locally.

Trust Establishment Sequence

%%{init: {'theme':'default', 'themeVariables': { 'primaryColor': '#5D8AA8', 'primaryTextColor': '#fff', 'primaryBorderColor': '#1F456E', 'lineColor': '#5D8AA8', 'secondaryColor': '#006400', 'tertiaryColor': '#fff' }}}%% 

sequenceDiagram
    participant Host as Initiating Application
    participant Client as MCP SSH Gateway
    participant KeySrv as Credential Broker
    participant SSHSrv as Remote MCP SSH Daemon
    participant MCP as Remote MCP Services

    Note over Client,SSHSrv: Initial Trust Negotiation

    Client->>Client: Key Pair Generation (if absent)
    Client->>KeySrv: Request Server Public Key
    KeySrv->>Client: Return Remote Daemon Public Key
    Client->>Client: Cache server key in temporary trust file
    Client->>KeySrv: Register Client Public Key via POST
    KeySrv->>SSHSrv: Provision Client Key to Authorized List
    KeySrv->>Client: Acknowledgment

    Note over Client,SSHSrv: Secure Tunnel Initiation

    Client->>SSHSrv: SSH Handshake using Client Private Key
    SSHSrv->>SSHSrv: Validate Credential Against Provisioned List
    SSHSrv->>Client: Session Authorized

    Note over Client,SSHSrv: MCP Data Flow

    Host->>Client: JSON-RPC Payload
    Client->>SSHSrv: Encapsulated Request over Tunnel
    SSHSrv->>MCP: Dispatch to Target Service
    MCP->>SSHSrv: Processed Output
    SSHSrv->>Client: Tunnelled Response Data
    Client->>Host: Deliver JSON-RPC Result

    Note over Client,SSHSrv: Session Cleanup

alt Connection Closure
        Host->>Client: Signal End of Session
        Client->>SSHSrv: Terminate SSH Link
        SSHSrv->>SSHSrv: Deallocate Resources
    end

Security Posture

• For production deployments, always enforce host identity verification.
• Utilizing passphrases to safeguard private keys is strongly recommended.
• Employ dedicated, least-privilege SSH identities specifically for MCP routing tasks.
• Apply stringent filesystem permissions (e.g., 600) to key material.
• Configure the remote user account with minimal necessary shell access rights.

Diagnostic Procedures

Connection Refused Error

Error running MCP SSH client: [Errno 111] Connection refused

Remedy: Confirm the target host address and port are accurate, and ensure the requisite SSH daemon is actively running.

Credential Rejection

Error running MCP SSH client: Authentication failed

Remedy: Validate the path to the client key file. Confirm that the corresponding public key has been successfully enrolled on the destination gateway.

Host Key Mismatch

Error running MCP SSH client: Host key verification failed

Remedy: Manually inject the host key into your known_hosts index, or, solely for transient testing, invoke the --disable-host-key-checking flag.

Project Dependencies

• anyio (>=4.5.0)
• asyncssh (>=2.20.0)
• mcp (>=1.1.3)
• pydantic (>=2.0.0)

Development Workflow

Setup Development Environment

git clone https://github.com/Machine-To-Machine/m2m-mcp-server-ssh-client.git
cd m2m-mcp-server-ssh-client
uv venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
uv pip install -e ".[dev]"

Quality Assurance Checks

# Execute static analysis and style checks
uv run ruff check .

# Verify code formatting consistency
uv run ruff format --check .

# Run security vulnerability scanning
uv run bandit -r src/

Advanced Debugging

You can leverage the MCP inspector utility to trace the client's operations:

npx @modelcontextprotocol/inspector uvx m2m-mcp-server-ssh-client --host example.com

For in-depth diagnosis, follow this procedure:

1. Relaunch the client with the verbosity set to DEBUG (--log-level DEBUG).
2. Scrutinize the initial SSH negotiation and certificate exchange logs.
3. If custom credentials are in use, verify file accessibility and permission levels.
4. Isolate the issue by confirming basic connectivity using the native ssh -v command.

Contribution Model

We actively solicit contributions to enhance the robustness and feature set of m2m-mcp-server-ssh-client. Any input, be it feature proposals, performance optimizations, or documentation improvements, is highly valued.

We welcome all pull requests detailing fixes or new capabilities.

Contribution Protocol

1. Create a fork of this repository.
2. Establish a dedicated feature branch: git checkout -b new-capability-branch
3. Commit changes atomically: git commit -am 'Implement XYZ functionality'
4. Push the branch to your fork: git push origin new-capability-branch
5. Submit a Pull Request referencing the changes.

Licensing

This project is distributed under the MIT License. Refer to the LICENSE file for complete licensing terms.

Authorship

• Machine To Machine Team

WIKIPEDIA: XMLHttpRequest (XHR) is an API in the form of a JavaScript object whose methods transmit HTTP requests from a web browser to a web server. The methods allow a browser-based application to send requests to the server after page loading is complete, and receive information back. XMLHttpRequest is a component of Ajax programming. Prior to Ajax, hyperlinks and form submissions were the primary mechanisms for interacting with the server, often replacing the current page with another one.

== History == The concept behind XMLHttpRequest was conceived in 2000 by the developers of Microsoft Outlook. The concept was then implemented within the Internet Explorer 5 browser (1999). However, the original syntax did not use the XMLHttpRequest identifier. Instead, the developers used the identifiers ActiveXObject("Msxml2.XMLHTTP") and ActiveXObject("Microsoft.XMLHTTP"). As of Internet Explorer 7 (2006), all browsers support the XMLHttpRequest identifier. The XMLHttpRequest identifier is now the de facto standard in all the major browsers, including Mozilla's Gecko layout engine (2002), Safari 1.2 (2004) and Opera 8.0 (2005).

=== Standards === The World Wide Web Consortium (W3C) published a Working Draft specification for the XMLHttpRequest object on April 5, 2006. On February 25, 2008, the W3C published the Working Draft Level 2 specification. Level 2 added methods to monitor event progress, allow cross-site requests, and handle byte streams. At the end of 2011, the Level 2 specification was absorbed into the original specification. At the end of 2012, the WHATWG took over development and maintains a living document using Web IDL.

== Usage == Generally, sending a request with XMLHttpRequest has several programming steps.

Create an XMLHttpRequest object by calling a constructor: Call the "open" method to specify the request type, identify the relevant resource, and select synchronous or asynchronous operation: For an asynchronous request, set a listener that will be notified when the request's state changes: Initiate the request by calling the "send" method: Respond to state changes in the event listener. If the server sends response data, by default it is captured in the "responseText" property. When the object stops processing the response, it changes to state 4, the "done" state. Aside from these general steps, XMLHttpRequest has many options to control how the request is sent and how the response is processed. Custom header fields can be added to the request to indicate how the server should fulfill it, and data can be uploaded to the server by providing it in the "send" call. The response can be parsed from the JSON format into a readily usable JavaScript object, or processed gradually as it arrives rather than waiting for the entire text. The request can be aborted prematurely or set to fail if not completed in a specified amount of time.

== Cross-domain requests ==

In the early development of the World Wide Web, it was found possible to brea