{"id":49757102,"url":"https://github.com/vchaindz/go-mcp-proxy","last_synced_at":"2026-05-10T23:01:05.418Z","repository":{"id":356486418,"uuid":"1185485815","full_name":"vchaindz/go-mcp-proxy","owner":"vchaindz","description":"A stdio-to-HTTP proxy for MCP (Model Context Protocol) servers. It lets stdio-based MCP clients like Claude Code connect to remote MCP servers over HTTP or SSE, with support for custom headers, TLS options, and authentication.","archived":false,"fork":false,"pushed_at":"2026-05-08T08:26:04.000Z","size":56,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-08T10:31:00.646Z","etag":null,"topics":["mcp","proxy","standalone","stdio","stdio-mcp"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vchaindz.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-18T16:24:47.000Z","updated_at":"2026-05-08T08:26:07.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/vchaindz/go-mcp-proxy","commit_stats":null,"previous_names":["vchaindz/go-mcp-proxy"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/vchaindz/go-mcp-proxy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vchaindz%2Fgo-mcp-proxy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vchaindz%2Fgo-mcp-proxy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vchaindz%2Fgo-mcp-proxy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vchaindz%2Fgo-mcp-proxy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vchaindz","download_url":"https://codeload.github.com/vchaindz/go-mcp-proxy/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vchaindz%2Fgo-mcp-proxy/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32874701,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-10T13:40:02.631Z","status":"ssl_error","status_checked_at":"2026-05-10T13:40:02.145Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["mcp","proxy","standalone","stdio","stdio-mcp"],"created_at":"2026-05-10T23:00:28.406Z","updated_at":"2026-05-10T23:01:05.412Z","avatar_url":"https://github.com/vchaindz.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# go-mcp-proxy\n\nA stdio-to-HTTP proxy for MCP (Model Context Protocol) servers. It lets stdio-based MCP clients like Claude Code connect to remote MCP servers over HTTP or SSE, with support for custom headers, TLS options, and authentication.\n\n## Build\n\nRequires Go 1.23+.\n\n```bash\ngo build -o go-mcp-proxy ./cmd/go-mcp-proxy/\n```\n\n## Usage\n\n```\ngo-mcp-proxy [flags] [server-url]\n\nFlags:\n  -config string    path to JSON config file\n  -server string    server name from config (default: first/only server)\n  -insecure         skip TLS certificate verification\n  -type string      transport: http, sse, auto (default \"auto\")\n  -header value     custom header key=value (repeatable)\n```\n\n### Basic\n\n```bash\n./go-mcp-proxy https://mcp.example.com/mcp\n```\n\n### With authentication and custom headers\n\n```bash\n./go-mcp-proxy \\\n  -header \"Authorization=Bearer my-token\" \\\n  -header \"X-Api-Key=abc123\" \\\n  https://mcp.example.com/mcp\n```\n\n### Self-signed / mismatched TLS certificates\n\n```bash\n./go-mcp-proxy -insecure https://10.0.0.5:8443/mcp\n```\n\n### Calling tools (subcommand mode)\n\n```bash\n# Linux/macOS — single quotes are fine\n./go-mcp-proxy call https://mcp.example.com/mcp prtg_get_sensors '{\"limit\":1}'\n\n# Windows PowerShell — single quotes preserve the JSON literally (same as Unix)\n.\\mcp-sse-proxy.exe call https://mcp.example.com/mcp prtg_get_sensors '{\"limit\":1}'\n\n# Windows cmd.exe — single quotes are literal; escape inner double quotes\nmcp-sse-proxy.exe call https://mcp.example.com/mcp prtg_get_sensors \"{\\\"limit\\\":1}\"\n\n# Any shell — read JSON from a file (no quoting headaches)\n./go-mcp-proxy call https://mcp.example.com/mcp prtg_get_sensors @args.json\n```\n\n\u003e **Why this matters on Windows:** PowerShell and `cmd.exe` both strip bare\n\u003e double quotes from arguments before the program sees them, so passing\n\u003e `{\"sensor_id\":65635}` ends up as `{sensor_id:65635}` (invalid JSON). The\n\u003e proxy detects this case and prints a \"did you mean\" suggestion, but the\n\u003e simplest fix is to wrap the whole payload in single quotes (PowerShell)\n\u003e or use `@file` form.\n\nThe `@file` form also works inside the `debug` REPL (`call prtg_get_sensors @args.json`).\n\n### Using a config file\n\nCreate a JSON config:\n\n```json\n{\n  \"mcpServers\": {\n    \"my-server\": {\n      \"url\": \"https://mcp.example.com/mcp\",\n      \"headers\": {\n        \"Authorization\": \"Bearer my-token\"\n      },\n      \"insecure\": false,\n      \"type\": \"auto\"\n    }\n  }\n}\n```\n\n```bash\n./go-mcp-proxy -config servers.json -server my-server\n```\n\n## Environment Variables\n\nEnvironment variables are the lowest priority — CLI flags and config file values take precedence.\n\n| Variable | Description |\n|---|---|\n| `MCP_SERVER_URL` | Server URL (also accepts legacy `MCP_SSE_URL`) |\n| `MCP_AUTH_TOKEN` | Sets `Authorization: Bearer \u003ctoken\u003e` header |\n| `MCP_HEADERS` | Comma-separated headers: `Key1=Value1,Key2=Value2` |\n| `MCP_INSECURE` | Skip TLS verification (`true` or `1`) |\n| `MCP_TRANSPORT` | Transport type: `http` or `sse` |\n\nExamples:\n\n```bash\n# URL + bearer token via env\nexport MCP_SERVER_URL=https://mcp.example.com/mcp\nexport MCP_AUTH_TOKEN=my-secret-token\n./go-mcp-proxy\n\n# Multiple headers via env\nexport MCP_HEADERS=\"Authorization=Bearer tok123,X-Api-Key=key456\"\n./go-mcp-proxy https://mcp.example.com/mcp\n\n# Skip TLS via env\nMCP_INSECURE=true ./go-mcp-proxy https://10.0.0.5:8443/mcp\n```\n\n## Configuration Priority\n\nSettings are resolved in this order (first wins):\n\n1. CLI flags (`-header`, `-insecure`, positional URL, `-type`)\n2. Config file (`-config`)\n3. Environment variables (`MCP_SERVER_URL`, `MCP_AUTH_TOKEN`, etc.)\n\n## Transport Modes\n\nThe proxy supports two MCP transport protocols:\n\n- **Streamable HTTP** — current MCP standard. Uses `POST` for messages, optional `GET` SSE for server-initiated notifications, session management via `Mcp-Session-Id`.\n- **Legacy SSE** — older protocol. Opens a persistent `GET` SSE connection for receiving, `POST` for sending.\n\nBy default (`-type auto`), the proxy tries Streamable HTTP first and falls back to Legacy SSE if the server doesn't support it.\n\n## Claude Code Integration\n\nAdd the proxy to `.mcp.json` in your project directory or globally at `~/.claude/.mcp.json`.\n\n### Simple — direct URL\n\n```json\n{\n  \"mcpServers\": {\n    \"my-server\": {\n      \"command\": \"/path/to/go-mcp-proxy\",\n      \"args\": [\"https://mcp.example.com/sse\"]\n    }\n  }\n}\n```\n\n### With authentication\n\n```json\n{\n  \"mcpServers\": {\n    \"my-server\": {\n      \"command\": \"/path/to/go-mcp-proxy\",\n      \"args\": [\n        \"-header\", \"Authorization=Bearer my-token\",\n        \"https://mcp.example.com/mcp\"\n      ]\n    }\n  }\n}\n```\n\n### With env variables (keeps secrets out of config)\n\n```json\n{\n  \"mcpServers\": {\n    \"my-server\": {\n      \"command\": \"/path/to/go-mcp-proxy\",\n      \"args\": [\"https://mcp.example.com/mcp\"],\n      \"env\": {\n        \"MCP_AUTH_TOKEN\": \"my-secret-token\"\n      }\n    }\n  }\n}\n```\n\n### Self-signed TLS + auth header\n\n```json\n{\n  \"mcpServers\": {\n    \"internal-server\": {\n      \"command\": \"/path/to/go-mcp-proxy\",\n      \"args\": [\n        \"-insecure\",\n        \"-header\", \"Authorization=whm root:YOUR_API_TOKEN\",\n        \"https://10.0.0.5:2087/mcp\"\n      ]\n    }\n  }\n}\n```\n\n### Using a config file\n\n```json\n{\n  \"mcpServers\": {\n    \"my-server\": {\n      \"command\": \"/path/to/go-mcp-proxy\",\n      \"args\": [\n        \"-config\", \"/path/to/servers.json\",\n        \"-server\", \"my-server\"\n      ]\n    }\n  }\n}\n```\n\n### Multiple headers via env\n\n```json\n{\n  \"mcpServers\": {\n    \"my-server\": {\n      \"command\": \"/path/to/go-mcp-proxy\",\n      \"args\": [],\n      \"env\": {\n        \"MCP_SERVER_URL\": \"https://mcp.example.com/mcp\",\n        \"MCP_HEADERS\": \"Authorization=Bearer tok123,X-Tenant-Id=acme\",\n        \"MCP_INSECURE\": \"true\"\n      }\n    }\n  }\n}\n```\n\n### Windows\n\n```json\n{\n  \"mcpServers\": {\n    \"my-server\": {\n      \"command\": \"C:\\\\tools\\\\go-mcp-proxy.exe\",\n      \"args\": [\"https://mcp.example.com/sse\"]\n    }\n  }\n}\n```\n\n## How It Works\n\n```\nMCP Client (e.g. Claude Code)\n    │ stdin (JSON-RPC 2.0)\n    ▼\n┌──────────────┐\n│ go-mcp-proxy │  ← flags / config / env vars\n└──────────────┘\n    │ HTTPS POST + custom headers\n    ▼\nRemote MCP Server\n    │ JSON response or SSE stream\n    ▼\n┌──────────────┐\n│ go-mcp-proxy │\n└──────────────┘\n    │ stdout (JSON-RPC 2.0)\n    ▼\nMCP Client\n```\n\nThe proxy reads JSON-RPC messages from stdin, forwards them as HTTP POST requests to the remote server, and writes responses back to stdout. All logging goes to stderr so it doesn't interfere with the protocol.\n\n## Project Structure\n\n```\ncmd/go-mcp-proxy/main.go    CLI entrypoint\ninternal/proxy/              Proxy library\n  config.go                  Config file + header flag parsing\n  jsonrpc.go                 JSON-RPC types and stdin/stdout I/O\n  transport.go               HTTP client and header helpers\n  sse.go                     SSE parser and URL resolution\n  legacy_sse.go              Legacy SSE transport\n  streamable.go              Streamable HTTP transport\n```\n\n## License\n\nSee [LICENSE](LICENSE) file.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvchaindz%2Fgo-mcp-proxy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvchaindz%2Fgo-mcp-proxy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvchaindz%2Fgo-mcp-proxy/lists"}