Skip to main content
Glama
Sign In
Rail Connector MCP

Rail Connector MCP

by SNComrade
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Local

Rail Connector MCP

Local MCP bridge for operating Claude Code Remote Control from Codex.

Same-OS contract: Codex, this MCP server, and Claude Code must run in the same operating-system context. Native Windows controls native Windows. A WSL installation controls Claude only when Codex and Claude both run inside that same WSL environment.

Rail Connector MCP combines Claude Code's local session logs and Remote Control CLI with a persistent Windows terminal broker or tmux on Linux and macOS. It lets Codex list, inspect, start, resume, continue, fork, prompt, wait for, capture, rename, archive, and stop local Claude Code conversations.

This project does not implement Anthropic's private cloud protocol. A local, authenticated Claude Code process remains required.

Rail Connector MCP is an independent open-source project. It is not affiliated with, sponsored by, or endorsed by Anthropic or OpenAI. Product names are used only to describe interoperability. See NOTICE.

Status

The current candidate is 1.0.0-beta.5. Treat the MCP tool schemas and response fields as prerelease interfaces until a stable release is published. See Compatibility.

The package is intentionally marked private and is not published to the npm registry. Git tags and GitHub Releases are the public release authority.

Related MCP server: codex-mcp-server

Capabilities

  • Local Claude conversation listing, search, inspection, resume, continue, and fork support

  • Model, effort, Ultracode, permission, safe-mode, tool, and workspace-trust launch controls

  • Persistent per-user ConPTY broker on Windows and validated tmux ownership on Linux/macOS

  • Chunked prompt submission and transcript-backed completion waiting

  • Integrity-checked result previews with exact Unicode-safe chunk retrieval

  • Session rename plus MCP-local archive metadata

  • Requested, resolved, observed, and audit-scoped launch-posture evidence

  • Bounded UltraCode entry/exit lifecycle evidence and opt-in debug-log provenance without returning debug contents

  • Repo-scoped Codex operator, debugger, and reviewer skills

Requirements

  • Windows, Linux, or macOS

  • Node.js 22, 24, or 26

  • npm and Git

  • Claude Code CLI installed and authenticated

  • Codex Desktop or Codex CLI with local MCP server support

  • tmux 3.2 or newer on Linux/macOS

  • Build prerequisites for node-pty when a matching prebuilt binary is not available; see Troubleshooting

Package installation scripts must be enabled because node-pty uses its install step to select a prebuild or compile. npm ci --ignore-scripts is unsupported.

Data And Trust Boundary

Rail Connector runs locally under the current user. It reads local Claude Code session logs and controls a local terminal process; MCP responses can include conversation text or Remote Control URLs when a caller requests those fields. The project has no telemetry service and does not upload session data. Claude Code itself still communicates with Anthropic under the user's Claude account.

Treat the Codex MCP client, the selected project directory, Claude hooks, and any enabled bypass policy as part of one local trust boundary. Use allowed roots when a registration should be limited to specific project trees.

Install

Install from the same OS environment that runs Codex and Claude Code.

For a published release, clone the immutable tag:

Linux:

git clone --branch v1.0.0-beta.5 --depth 1 https://github.com/SNComrade/Rail-Connector-MCP.git
cd Rail-Connector-MCP
./install.sh

macOS uses the same installer after the prerequisites in macOS Install are present.

Native Windows PowerShell for v1.0.0-beta.5, once published: complete the Windows upgrade preparation on an existing installation before replacing source or dependencies. Close affected MCP clients and use a separate PowerShell window for installation:

git clone --branch v1.0.0-beta.5 --depth 1 https://github.com/SNComrade/Rail-Connector-MCP.git
cd Rail-Connector-MCP
.\install-windows.ps1 -ClientsClosed

Historical v1.0.0-beta.4 installer exception: that tagged installer predates -ClientsClosed and does not define that parameter; do not pass it to beta.4. The beta.5 and current source installers require it. For an existing installation, preparation includes authorized session stops and old-broker shutdown through the old client before source or dependency replacement.

-ClientsClosed acknowledges that preparation; it performs none of those steps. Follow Windows Install for the guarded installer preflight.

To evaluate unreleased work, clone main without --branch; do not describe a mutable main checkout as a released version. The source-tree installers are not included in the runtime-only npm tarball produced for release inspection.

The default installer runs syntax and smoke verification before registration. Pass --run-tests on Linux/macOS or -RunTests on Windows to run the complete suite during installation. CI always runs the complete suite.

The registered MCP server name is rail-connector; Codex tools appear under mcp__rail_connector after a fresh Codex task loads the registration. Bundled skills are repo-scoped. Use Codex's native $skill-installer for the three directories under .agents/skills/ when they should be available from unrelated project repositories; skill installation is an explicit, separate choice from MCP registration.

Permission Policy

Bypass mode is disabled by default. On an intentionally authorized development host, install with the explicit local-host policy:

./install.sh --bypass-policy LocalHost --allowed-root "$HOME/projects"

The Windows command below applies to the guarded source installer. For the published beta.4 installer, omit -ClientsClosed as explained above.

.\install-windows.ps1 -BypassPolicy LocalHost -AllowedRoot "$HOME\Projects" -ClientsClosed

Each bypass launch must still include confirmBypassPermissions: true. Bypass mode removes Claude's approval prompts and can modify any host resource available to the Claude process. Read Security Model before enabling it.

LocalHost is an advanced single-user development policy, not a claim that the host is isolated. Disabled remains the default. Restricting allowed roots is strongly recommended when LocalHost is enabled.

Verify

npm ci
npm test

Start with the MCP get_claude_capabilities and status tools. On Windows, status should report the persistent native broker backend. Use the actual task project as cwd, not this repository unless this repository is the review target.

Privacy checks for examples

Use synthetic profile placeholders in contributed examples and run npm run check:privacy. POSIX paths under /home/ and /Users/ use lowercase you or <you> as exact username components; you-private is not a placeholder. Repeated POSIX separators use the same rule. The no-username root directories /home/ and /Users/ are allowed. Windows double quotes end the username token without matched-frame or source-unit checks. Windows apostrophe/backtick framing must match; quoted POSIX bare placeholders and roots need matching single quotes, double quotes or backticks. Backtick runs must close with equal lengths.

For contiguous source suffixes after Windows apostrophe/backtick frames or POSIX frames, use a complete supported source example: a simple one-line declaration, argument call, array/object initializer, conditional or property expression within a declaration. Windows double quotes remain delimiters. The shared grammar is limited to 4096 characters, ASCII identifiers and explicit semicolons. Unsupported syntax and raw suffix expressions are conservatively flagged. Put whitespace before comments or division operators:

const root = 'C:\\Users\\you'; // synthetic placeholder
const unixRoot = '/home/you';
const halfLength = root.length / 2;

The scanner uses text boundaries, not a complete source-language or filename parser. Whitespace and quotes can occur in POSIX filenames, and data can imitate source syntax. Matched framing and supported source syntax are text heuristics, not proof of privacy. Review its content as well.

Documentation

Project policies and maintainer references:

License

MIT. See LICENSE and Third-Party Notices.

Available Tools

14 tools
archive_claude_sessionA

Archive a Claude conversation in the MCP-local catalog. This never moves, edits, or deletes Claude's JSONL transcript.

Inputs: sessionId (required), cwd.

capture_remote_controlC

Capture visible terminal output from the managed native Rail Connector Control session.

Inputs: lines, tmuxSession, managedSession.

get_claude_capabilitiesA

Inspect the installed Claude CLI with bounded version/help probes without starting an interactive session. Reports advertised and experimental request paths; terminal capture cannot authenticate effective runtime posture.

Inputs: no named parameters.

get_claude_sessionB

Inspect a local native Claude Code session log by id. Returns recent user/assistant text and any Remote Control URL recorded in the log.

Inputs: sessionId (required), cwd, maxMessages.

list_claude_sessionsA

List local native Claude Code session logs for a project directory. Returns metadata by default; prompt/output snippets are optional.

Inputs: cwd, limit, query, scanLimit, +3 more.

rename_claude_sessionA

Rename the Claude conversation attached to a running managed session, then verify the title in Claude's local session log.

Inputs: title (required), tmuxSession, managedSession.

send_keyA

Send a single key name to the managed native Claude session, such as Enter, Escape, C-c, Up, Down.

Inputs: key (required), tmuxSession, managedSession.

send_textA

Send literal text to the managed native Claude session. Use submit=true to press Enter after sending. For multi-line prompts use submit_prompt; newlines sent here may submit early. This can affect a live Claude session.

Inputs: text (required), submit, tmuxSession, managedSession.

start_remote_controlA

Start or resume a native Claude Code session with Remote Control enabled. Windows sessions are owned by a persistent per-user broker so Codex tasks can reconnect after refresh; Linux/macOS sessions use tmux.

Inputs: cwd, bare, model, tools, +22 more.

statusB

Show terminal backend and Claude process status relevant to managed Remote Control sessions.

Inputs: includeAgentDetails.

stop_remote_controlC

Stop a managed native Rail Connector Control session.

Inputs: force, graceful, tmuxSession, managedSession.

submit_promptA

Paste and submit a complete prompt to Claude using safer chunked input. Returns a non-empty waitAfterCursor for an unambiguous wait_for_claude_turn call.

Inputs: text (required), force, lines, chunkSize, +6 more.

unarchive_claude_sessionA

Remove a Claude conversation from the MCP-local archive catalog so it appears in active listings again. The transcript is unchanged.

Inputs: sessionId (required), cwd.

wait_for_claude_turnA

Wait for Claude's current turn to finish using record-ordered local session-log completion and terminal state. Pass submit_prompt.waitAfterCursor verbatim.

Inputs: lines, afterCursor, tmuxSession, managedSession, +2 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    Claude Code, inside the Godot 4 editorFlockbay puts an AI agent in the real Godot 4 editor: it writes GDScript, runs your game and fixes what breaks. Free, or bring your own Claude Code or Codex.flockbay.comAd

    TDQS

    A3.6/5.0

    Scored across 14 tools

    Disambiguation4/5

    Most tools map to distinct resources/actions (sessions, remote control lifecycle, input methods). However, send_text and submit_prompt both send input to a session and could be confused, though their descriptions offer clear usage guidance.

    Naming Consistency4/5

    Tool names predominantly follow a verb_noun pattern (list_claude_sessions, start_remote_control). Minor deviations include wait_for_claude_turn (prepositional phrase) and status (noun-only), but overall the pattern is predictable.

    Tool Count5/5

    With 14 tools, the count is well within the ideal 3-15 range. Each tool addresses a distinct operational need for managing and interacting with Claude sessions, without apparent redundancy.

    Completeness4/5

    The set provides solid lifecycle coverage (start, stop, archive, unarchive, list, get, rename) and interaction primitives (send, submit, key, capture, wait). A minor gap is the lack of a dedicated tool to list archived sessions, though unarchive exists.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers