MCP Server SSH Gateway Tunnel Client

A Machine-To-Machine Model Context Protocol (MCP) Remote Access Client leveraging Secure Shell (SSH) to bridge local systems with remote MCP infrastructure servers. This client furnishes a secure transport layer, permitting the invocation and utilization of remote MCP assets as if they resided on the local machine.

Core Capabilities

• Facilitate secure ingress to any designated MCP infrastructure server via SSH protocol.
• Tunnel all native MCP protocol communications through the hardened SSH channel.
• Comprehensive support for cryptographic key-based identity verification.
• Full exposure of remote MCP functionalities, encompassing utility modules, interactive prompts, and managed data resources.

Deployment Instructions

Within a project managed by uv, integrate this dependency via:

bash uv add m2m-mcp-server-ssh-client

Alternatively, for projects utilizing pip for dependency resolution: bash pip install m2m-mcp-server-ssh-client

To initiate installation directly from the source repository:

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

To activate the gateway service within your operational environment:

uv run m2m-mcp-server-ssh-client

Practical Scenarios

1. Immediate Access Using Public Demo Endpoint

We maintain a publicly accessible staging server populated with diverse, pre-configured MCP utilities for immediate experimentation. (This resource is provisional until the decentralized registry becomes fully operational.)

This demonstration endpoint hosts several MCP servers offering tools like HackerNews interfacing, MLB Statistics retrieval, and Formula 1 telemetry access.

Integration with Claude Environment

To link Claude Desktop to this remote endpoint, integrate the following configuration snippet into your 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

bash

Establish connection to the M2M demonstration gateway with automated key exchange

uv run m2m-mcp-server-ssh-client --host mcp-beta.machinetomachine.ai --use-key-server

2. Local Development and Simulation Testing

Refer to m2m-mcp-server-ssh-server documentation for setting up your own local SSH endpoint.

For testing workflows locally against your customized MCP assets:

bash

Connect to an internally hosted MCP SSH gateway

uv run m2m-mcp-server-ssh-client

The preceding command attempts linkage with a local SSH listener operating on TCP port 8022.

During local verification, key exchange can be streamlined using the associated key server component:

bash

Leverage the key server for automated credential management (if the server permits --run-key-server)

uv run m2m-mcp-server-ssh-client --use-key-server

The command above attempts to interface with the key server running on port 8000 for key provisioning.

3. Connecting to Proprietary Remote Infrastructure

Accessing your self-managed MCP hosting solution:

bash

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

Credential negotiation can be streamlined by deploying the key server component on your remote infrastructure and configuring the client to utilize it.

Orchestration with AI Frameworks

Claude Desktop Configuration

Incorporate this setup into your Claude configuration file:

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

MCP Inspector Utility

For diagnostics or inventory inspection of available remote resources:

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

Operational Usage

Command Argument Specification

• --host: IP address or hostname of the target SSH gateway (Default: "localhost")
• --port: Network socket designation for the SSH server (Default: 8022)
• --username: Designated SSH access identity (Default: "mcp")
• --client-key: Path to the client's private authentication material (Default: "~/.ssh/m2m_mcp_server_ssh_client")
• --known-hosts: Location of the file containing trusted remote host signatures (Default: "~/.ssh/known_hosts")
• --passphrase: Secret required to unlock the private key material (Default: None)
• --disable-host-key-checking: Bypass integrity check of the server's signature (Default: False)
• --log-level: Verbosity setting for diagnostic output (Default: INFO)

Detailed Usage Examples

Standard Connection to a Remote Host

Initiate communication with a remote MCP gateway (SSH service) listening on port 8022:

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

Employing a Specific SSH Credential File

Designate a unique SSH key pair for authenticating access:

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

If key protection is enforced with a passphrase:

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

Debug Mode for Diagnostics

Activate verbose logging to trace connectivity anomalies:

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

Key Server Interoperability

The MCP SSH Client supports dynamic credential provisioning via an auxiliary key server:

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

When utilizing the key server mechanism:

1. The client retrieves the gateway's public key 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 duration of the SSH session

This operational mode is mutually exclusive with the use of --known-hosts and --disable-host-key-checking arguments.

Bypassing Host Key Validation

⚠️ Critical Security Alert: Invoking --disable-host-key-checking exposes the connection to potential Man-in-the-Middle incursions. Reserve this option exclusively for trusted internal networks or controlled development/testing scenarios.

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

Configuration for Claude Desktop Integration

Add the following stanza to your Claude settings manifest:

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

For heightened security using explicit credential paths:

"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" ] } }

Mechanism of Operation

The MCP Gateway SSH Client fabricates a persistent SSH session directed toward a remote host running the requisite m2m-mcp-server-ssh-server component, which manages the MCP tool ecosystem. The process involves:

1. Synthesizing a local proxy service that accurately mirrors the remote MCP server's advertised capabilities.
2. Redirecting all incoming MCP protocol requests through the established, secured SSH conduit.
3. Relay the processed responses originating from the remote infrastructure back to the initiating local client.

This abstraction enables local applications to interact with computational assets situated on disparate remote machines transparently.

Authentication Sequence Diagram

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

sequenceDiagram participant Host as MCP Host
(Claude/Cursor) participant Client as MCP SSH Client participant KeySrv as Key Server
(HTTP API) participant SSHSrv as MCP SSH Server participant MCP as MCP Servers

Note over Client,SSHSrv: Initial Key Exchange & Authentication

Client->>Client: Generate SSH key pair<br>if does not exist
Client->>KeySrv: GET /server_pub_key
KeySrv->>Client: Return server's public key
Client->>Client: Store server key in<br>temporary known_hosts
Client->>KeySrv: POST /register<br>{client_pub_key: "ssh-ed25519 AAAA..."}
KeySrv->>SSHSrv: Store client public key<br>in authorized keys
KeySrv->>Client: {status: "success"}

Note over Client,SSHSrv: Secure SSH Connection

Client->>SSHSrv: SSH handshake with<br>client key authentication
SSHSrv->>SSHSrv: Verify client key<br>against authorized keys
SSHSrv->>Client: Authentication successful

Note over Client,SSHSrv: MCP Communication

Host->>Client: JSONRPC request
Client->>SSHSrv: Forward request<br>over SSH tunnel
SSHSrv->>MCP: Route request to<br>appropriate MCP server
MCP->>SSHSrv: Process and return results
SSHSrv->>Client: Send response over SSH
Client->>Host: Return JSONRPC response

Note over Client,SSHSrv: Session Termination

alt Session Termination
    Host->>Client: Close connection
    Client->>SSHSrv: Terminate SSH session
    SSHSrv->>SSHSrv: Clean up resources
end

Security Posture

• Always mandate host signature validation in production settings.
• Favor SSH credentials protected by passphrases for superior security.
• Utilize distinct SSH keys specifically provisioned for MCP gateway interactions.
• Enforce strict file permissions (600 mode) on all private key assets.
• Employ a dedicated, minimally privileged user account on the remote host.

Resolution of Typical Connection Faults

Connection Refused Encountered

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

Remedy: Verify the specified host address and port number. Confirm that the upstream SSH daemon is actively servicing connections.

Credential Verification Failure

Error running MCP SSH client: Authentication failed

Remedy: Scrutinize the path specified for the private key file. Ensure the corresponding public key is correctly installed within the remote server's authorization directives.

Host Key Validation Failure

Error running MCP SSH client: Host key verification failed

Remedy: Manually append the host's signature to your known_hosts file, or alternatively, utilize --disable-host-key-checking (strictly for testing contexts).

Required Dependencies

• anyio (minimum version: 4.5.0)
• asyncssh (minimum version: 2.20.0)
• mcp (minimum version: 1.1.3)
• pydantic (minimum version: 2.0.0)

Development Workflow

Setting Up the Development Environment

bash 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 # On Windows: .venv\Scripts\activate uv pip install -e "。[dev]"

Code Compliance Checks

bash

Execute code style analysis

uv run ruff check .

Validate code formatting standards

uv run ruff format --check .

Perform static security analysis

uv run bandit -r src/

Debugging Procedures

You can employ the MCP inspector to trace the client's internal operations:

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

For deeper diagnostic analysis, adopt the following iterative methodology:

1. Launch the client with the directive --log-level DEBUG.
2. Carefully review the SSH session initialization sequence and the ensuing cryptographic handshake.
3. If custom credentials are in play, validate file locations and filesystem permissions.
4. As a preliminary step, confirm baseline connectivity using the native ssh -v utility.

Contributions

We actively solicit external contributions to enhance and expand the utility of m2m-mcp-server-ssh-client. Whether your input involves novel feature implementation, refinement of existing logic, or documentation improvement, your expertise is highly valued.

We encourage the submission of Pull Requests detailing new features, fixes, or enhancements.

Contribution Protocol

1. Fork the primary repository.
2. Establish a dedicated feature branch: git checkout -b feature-name.
3. Commit your modifications: git commit -am 'Implement feature X'.
4. Push the branch to the remote origin: git push origin feature-name.
5. Initiate a Pull Request for integration.

Licensing Information

MIT License - Refer to the LICENSE artifact for complete stipulations.

Principals

• Machine To Machine

WIKIPEDIA: Cloud computing is "a paradigm for enabling network access to a scalable and elastic pool of shareable physical or virtual resources with self-service provisioning and administration on-demand," according to ISO. It is commonly referred to as "the cloud".

== Characteristics == In 2011, the National Institute of Standards and Technology (NIST) identified five "essential characteristics" for cloud systems. Below are the exact definitions according to NIST:

On-demand self-service: "A consumer can unilaterally provision computing capabilities, such as server time and network storage, as needed automatically without requiring human interaction with each service provider." Broad network access: "Capabilities are available over the network and accessed through standard mechanisms that promote use by heterogeneous thin or thick client platforms (e.g., mobile phones, tablets, laptops, and workstations)." Resource pooling: " The provider's computing resources are pooled to serve multiple consumers using a multi-tenant model, with different physical and virtual resources dynamically assigned and reassigned according to consumer demand." Rapid elasticity: "Capabilities can be elastically provisioned and released, in some cases automatically, to scale rapidly outward and inward commensurate with demand. To the consumer, the capabilities available for provisioning often appear unlimited and can be appropriated in any quantity at any time." Measured service: "Cloud systems automatically control and optimize resource use by leveraging a metering capability at some level of abstraction appropriate to the type of service (e.g., storage, processing, bandwidth, and active user accounts). Resource usage can be monitored, controlled, and reported, providing transparency for both the provider and consumer of the utilized service. By 2023, the International Organization for Standardization (ISO) had expanded and refined the list.

== History ==

The history of cloud computing extends to the 1960s, with the initial concepts of time-sharing becoming popularized via remote job entry (RJE). The "data center" model, where users submitted jobs to operators to run on mainframes, was predominantly used during this era. This was a time of exploration and experimentation with ways to make large-scale computing power available to more users through time-sharing, optimizing the infrastructure, platform, and applications, and increasing efficiency for end users. The "cloud" metaphor for virtualized services dates to 1994, when it was used by General Magic for the universe of "places" that mobile agents in the Telescript environment could "go". The metaphor is credited to David Hoffman, a General Magic communications specialist, based on its long-standing use in networking and telecom. The expression cloud computing became more widely known in 1996 when Compaq Computer Corporation drew up a business plan for future computing and the Internet. The company's ambition was to superch