BrainAPI is a knowledge graph–powered AI memory layer that transforms unstructured data into structured knowledge, enabling intelligent search, recommendations, and contextual memory for AI agents and applications.
MCP stdio ↔ Streamable HTTP bridge
A single Rust executable that Claude Desktop can spawn as an MCP server. It reads newline-delimited JSON-RPC from stdin, forwards each message to a remote MCP server over Streamable HTTP, and writes responses (and streamed events) as newline-delimited JSON to stdout. No Node or Python required.
Build
Install Rust (via rustup). This crate uses rust-toolchain.toml to require Rust 1.85.0 or newer (needed for current dependencies). From this directory, run cargo build; rustup will use or install the right toolchain automatically.
cargo build --release
The binary is target/release/mcp-stdio-http-bridge (or mcp_stdio_http_bridge on some platforms).
Universal macOS binary (x86_64 + aarch64)
cargo build --release --target x86_64-apple-darwin
cargo build --release --target aarch64-apple-darwin
lipo -create \
target/x86_64-apple-darwin/release/mcp-stdio-http-bridge \
target/aarch64-apple-darwin/release/mcp-stdio-http-bridge \
-output mcp-stdio-http-bridge-macos-universal
Install the targets if needed:
rustup target add x86_64-apple-darwin aarch64-apple-darwin
Run manually
export URI=<your-deployment-url>/mcp
export BEARER_TOKEN=your-token
export RUST_LOG=info
./target/release/mcp-stdio-http-bridge
Then type or pipe newline-delimited JSON-RPC lines to stdin; responses appear on stdout. Logs go to stderr.
Claude Desktop config
Point Claude Desktop’s MCP command at the bridge binary so it runs as a stdio MCP server:
{
"mcpServers": {
"<your-mcp-name>": {
"command": "/absolute/path/to/mcp-stdio-http-bridge",
"env": {
"URI": "<your-deployment-url>/mcp",
"BEARER_TOKEN": "your-token",
"MCP_NAME": "<your-mcp-name>",
"RUST_LOG": "info"
}
}
}
}
Optional env vars:
URI– remote MCP Streamable HTTP endpoint (default:<your-deployment-url>/mcp)BEARER_TOKEN– if set, sent asAuthorization: Bearer <token>MCP_NAME– used in logs onlyMCP_TIMEOUT_MS– request timeout in ms (default: 60000)MCP_MAX_QUEUE– max queued stdin messages (default: 10000)RUST_LOG– log level (e.g.info,debug,mcp_stdio_http_bridge=debug)
Tests
cargo test
Unit tests cover SSE parsing and behaviour (see src/remote_transport.rs). No integration tests (avoids extra dependencies that require newer Rust).
Design notes
Stdio ↔ Streamable HTTP mapping
- Stdio side: One JSON-RPC message per line (newline-delimited). No framing beyond that; request IDs and payloads are preserved and not reinterpreted.
- Remote side: Each line is sent as a single HTTP POST to the configured URI:
- Body: raw JSON-RPC (UTF-8),
Content-Type: application/json Accept: application/json, text/event-streamso the server may respond with either a single JSON body or an SSE stream.
- Body: raw JSON-RPC (UTF-8),
- Responses:
- 200 + application/json: Body is forwarded as one line to stdout.
- 200 + text/event-stream: Response is parsed as SSE; each event’s
data(or concatenateddatalines per event) is emitted as one newline-delimited JSON line to stdout. Event boundaries are blank lines. - 202 Accepted: Empty body; nothing is written to stdout.
- 4xx/5xx: Body (if any) is still forwarded as one line so the client sees the server’s error.
Streaming
Streaming is handled entirely in remote_transport: we read the response body and, when Content-Type is text/event-stream, parse SSE and collect one JSON message per event (or per concatenated data block). Those are returned as a Vec<String> and the bridge writes each element as a separate line to stdout. No reordering; message order is preserved.
Retry / backoff
- Only network-level failures are retried (connection, timeout, request errors). Invalid UTF-8 or I/O errors are not retried.
- Backoff is exponential: start 500 ms, double each time, capped at 30 s. The same message is retried until success or non-retryable error. Message order is preserved; we do not pull the next message until the current one is sent.
- While retrying, new stdin messages are queued in a bounded channel (
MCP_MAX_QUEUE, default 10k). When the channel is full, the stdin reader blocks (backpressure).
Assumptions about Streamable HTTP
- Single endpoint: POST one JSON-RPC message per request. No GET/session in this bridge (stateless).
- Response is either (a) one JSON body, or (b) SSE with one JSON-RPC message per event (
data:line or concatenateddata:lines per event). The format is implemented insrc/remote_transport.rs; changeparse_sse_to_json_linesand theContent-Typehandling there if your server differs (e.g. different SSE format or newline-delimited JSON instead of SSE).