Documentation
¶
Overview ¶
Bridge mode (--connect): a stdio ↔ Streamable-HTTP proxy.
The process runs as a local stdio MCP server — what Claude Desktop and similar clients launch — and forwards every tool call to a remote bintrail Streamable-HTTP MCP endpoint (a `bintrail-mcp --http` server or a console `/mcp` endpoint). The tool set is a dynamic passthrough: tools are listed from the remote at startup and re-exposed verbatim (names, descriptions, schemas, annotations), and re-synced when the remote emits a tools/list_changed notification — the bridge never carries its own tool declarations, so it cannot drift from the server it fronts.
bintrail-mcp is an MCP (Model Context Protocol) server that exposes read-only Bintrail operations as tools: query, recover, recover_cascade, reconstruct, status, and list_schema_changes.
By default it communicates over stdio (for use as a subprocess by Claude Code, Cursor, etc.). Pass --http <addr> to start an HTTP server instead, allowing any MCP client on the network to connect without a local binary.
bintrail-mcp # stdio (default) bintrail-mcp --http :8080 # HTTP on all interfaces, port 8080
Bridge mode (stdio ↔ Streamable HTTP): serve MCP over stdio locally and proxy every request to a remote bintrail MCP endpoint. This is what the released .mcpb bundle runs under Claude Desktop:
bintrail-mcp --connect http://host:8090/mcp --token <token>
Multi-tenant mode (one backend serving several indexes, behind a proxy that authenticates callers and tags them):
bintrail-mcp --http :8080 --tenant-dsns tenant-dsns.json
The fronting proxy sends an X-Bintrail-Tenant header; the server resolves that tenant's index DSN from the provided JSON map file.
Configuration:
Set BINTRAIL_INDEX_DSN to the MySQL DSN for the index database, or pass index_dsn as a parameter on each tool call. The reconstruct tool additionally needs a baseline snapshot location: BINTRAIL_BASELINE_DIR (a local directory) or BINTRAIL_BASELINE_S3 (an s3://bucket/prefix), or the per-call baseline_dir / baseline_s3 parameters.
The tool implementations live in internal/mcptools, shared with the console's /mcp endpoint; this binary binds them to the standalone posture (per-call DSN resolution, fresh connection per call, env-var archive discovery, per-call profile parameter).
Source Files