vikstra-bridge

The Vikstra MCP Bridge is a stdio-capable bridge that connects Claude Desktop to remote MCP servers over HTTP/HTTPS, implementing the MCP Protocol Revision 2025-06-18. It supports a full suite of MCP capabilities including discovery (tools/list, resources/list, prompts/list, roots/list, resources/templates/list), action methods (tools/call, resources/read, prompts/get), completion (completion/complete), sampling (sampling/createMessage), elicitation (elicit), logging (logging/setLevel), and real-time notifications (notifications/tools/list_changed, notifications/resources/list_changed, notifications/prompts/list_changed, notifications/resources/updated). It handles both streamable HTTP transport and legacy SSE transport, with automatic header expansion for environment variables and canonical HTTP header formatting. To use the bridge, point it at the MCP server URL and Claude Desktop will communicate via stdio, with the bridge performing protocol translation and session management as needed. The bridge also supports dynamic discovery of tools, resources, prompts, and resource templates so Claude can present up-to-date capabilities to users.

Typical usage involves running the bridge as a transport layer between Claude Desktop and your MCP server. From Claude Desktop, configure an MCP server entry that points to the bridge's endpoint (via the appropriate transport) and supply any required headers or environment variables. The bridge will negotiate a session, advertise capabilities, and then relay tool calls, resource reads, prompts, and completions between Claude and the MCP server. If you need to force a specific transport, you can pass the -transport flag (e.g., -transport http or -transport sse) when launching the bridge.

Prerequisites:

• Docker (recommended for the official image) or a Go toolchain if building from source
• Access to the MCP server(s) you plan to bridge

Option A: Run via Docker (recommended)

1. Pull or build the Vikstra Bridge Docker image:
   • If you have a prebuilt image: docker pull vikstra-bridge:latest
   • If building locally: docker build -t vikstra-bridge:latest .
2. Run the bridge, pointing it to your MCP server URL as needed by your setup: docker run -i vikstra-bridge:latest

Option B: Build from source (Go)

1. Prerequisites:
   • Go 1.19+ installed
   • Git installed
2. Clone the repository and build: git clone <repository-url> && cd vikstra-bridge go build -o vikstra-bridge
3. Run the binary: ./vikstra-bridge <MCP_SERVER_URL> [OPTIONS]
   • Example: ./vikstra-bridge https://api.example.com/mcp

Option C: Development workflow (Makefile targets)

1. Ensure Go is installed
2. Use Makefile targets to build and test: make build # Build the binary make test # Run tests make clean # Clean built files make help # Show targets

Environment variables in headers are expanded, e.g., -header "Authorization: Bearer ${API_TOKEN}". Ensure your MCP server URL uses https when possible to secure transport. If you encounter SSL issues in development, verify your certificate and ensure the bridge has network access to the MCP server. The bridge logs to the OS temp directory; check logs for troubleshooting. When using Claude Desktop integration, ensure your claude_desktop_config.json entry matches the bridge's command and arguments, and provide any necessary environment variables in the env block. If you rely on event subscriptions, ensure the MCP server supports change notifications per the MCP 2025-06-18 specification and that the bridge is configured to handle both streaming and SSE transports as needed.