# Vikstra Bridge > An another mcp-bridge for connecting stdio clients to http streamable and http sse MCP Servers - **Type:** MCP server - **Install:** `agentstack add mcp-unarii-vikstra-bridge` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [unarii](https://agentstack.voostack.com/s/unarii) - **Installs:** 0 - **Category:** [Integrations](https://agentstack.voostack.com/c/integrations) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [unarii](https://github.com/unarii) - **Source:** https://github.com/unarii/vikstra-bridge - **Website:** https://vikstra.ai/bridge ## Install ```sh agentstack add mcp-unarii-vikstra-bridge ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # Vikstra MCP Bridge [](https://opensource.org/licenses/MIT) [](https://golang.org/) [](https://modelcontextprotocol.io/) A Model Context Protocol (MCP) compliant stdio bridge that connects Claude Desktop to remote MCP servers over HTTP/HTTPS with full specification compliance. ## Overview This MCP bridge serves as a bridge between Claude Desktop (which communicates via stdio) and remote MCP servers that expose HTTP/HTTPS endpoints. It implements the MCP Protocol Revision 2025-06-18 with complete support for tools, resources, prompts, resource templates, sampling, elicitation, and real-time change notifications. ## Features ### MCP Specification Compliance - **Protocol Revision**: 2025-06-18 (latest specification) - **Streamable HTTP Transport**: Primary transport with `Mcp-Session-Id` header support - **Legacy SSE Transport**: Backward compatibility with 2024-11-05 specification - **Auto Transport Detection**: Intelligent detection based on URL patterns - **Full Capability Discovery**: Automatic discovery of `tools`, `resources`, `prompts`, and `resource templates` - **Real-time Notifications**: Handles all change notifications per MCP spec - **Environment Variables**: Automatic expansion of `${VAR_NAME}` in headers - **Canonical HTTP Headers**: Proper header formatting using Go's textproto package ### Supported MCP Methods - **Core Methods**: `initialize`, `ping` - **Discovery Methods**: `tools/list`, `resources/list`, `resources/templates/list`, `prompts/list`, `roots/list` - **Action Methods**: `tools/call`, `resources/read`, `prompts/get` - **Subscription Methods**: `resources/subscribe`, `resources/unsubscribe` - **Completion Methods**: `completion/complete` - **Sampling Methods**: `sampling/createMessage` *(MCP 2025-06-18)* - **Logging Methods**: `logging/setLevel` *(MCP 2025-06-18)* - **Elicitation Methods**: `elicit` *(MCP 2025-06-18)* - **Notifications**: `notifications/tools/list_changed`, `notifications/resources/list_changed`, `notifications/prompts/list_changed`, `notifications/resources/updated` - **Transport Agnostic**: All methods work with both Streamable HTTP and SSE transports ### Advanced Features - **Comprehensive Logging**: All operations logged to OS-specific temp directory - **Header Management**: Support for multiple custom HTTP headers with canonical casing - **Environment Logging**: Complete environment variable capture for debugging - **Session Management**: MCP session handling for both HTTP and SSE transports - **URL Validation**: Strict HTTP/HTTPS URL validation using Go's standard library ## Installation ### From Source (Recommended) ```bash git clone cd vikstra-bridge go build -o vikstra-bridge ``` ### Development Mode ```bash # Run directly without building go run ./vikstra-bridge.go [OPTIONS] # Using Makefile make build # Build the binary make test # Run all tests make clean # Clean built files make help # Show all available targets ``` ## Usage ### Basic Syntax ```bash ./vikstra-bridge [OPTIONS] ``` ### Command Line Options | Flag | Type | Description | Default | |------|------|-------------|---------| | `MCP_SERVER_URL` | string | **Required**. URL of the remote MCP server (first parameter) | - | | `-header` | string | HTTP header (can be used multiple times) | - | | `-transport` | string | MCP transport type: `auto`, `sse`, or `http` | `auto` | | `-verbose` | boolean | Enable verbose logging to stderr | `false` | | `-debug` | boolean | Enable debug logging (includes all headers) | `false` | ### Examples #### Basic MCP Connection ```bash ./vikstra-bridge https://api.example.com/mcp ``` #### With Authentication Headers ```bash ./vikstra-bridge https://api.example.com/mcp \ -header "Authorization: Bearer ${API_TOKEN}" \ -header "X-API-Key: ${API_KEY}" ``` #### Force SSE Transport ```bash ./vikstra-bridge https://api.example.com/sse -transport sse ``` #### Debug Mode ```bash ./vikstra-bridge https://api.example.com/mcp -debug ``` ## Environment Variable Support Headers support environment variable expansion using `${VARIABLE_NAME}` syntax: ```bash export API_TOKEN="your-secret-token" export API_KEY="your-api-key" ./vikstra-bridge https://api.example.com/mcp \ -header "Authorization: Bearer ${API_TOKEN}" \ -header "X-API-Key: ${API_KEY}" ``` ## Claude Desktop Integration Add to your `claude_desktop_config.json`: ```json { "mcpServers": { "my-mcp-server": { "command": "/path/to/vikstra-bridge", "args": [ "https://api.example.com/mcp", "-header", "Authorization: Bearer ${MCP_TOKEN}", "-transport", "auto" ], "env": { "MCP_TOKEN": "your-api-token" } } } } ``` ## How It Works ### 1. MCP Protocol Flow ```mermaid sequenceDiagram participant Claude as Claude Desktop participant Bridge as Vikstra Bridge participant Server as MCP Server Note over Claude,Server: Initialization Claude->>Bridge: initialize Bridge->>Server: initialize (HTTP/HTTPS) Server->>Bridge: capabilities + session Bridge->>Claude: capabilities Note over Bridge,Server: Capability Discovery (MCP 2025-06-18) Bridge->>Server: tools/list Server->>Bridge: Available tools Bridge->>Server: resources/list Server->>Bridge: Available resources Bridge->>Server: prompts/list Server->>Bridge: Available prompts Bridge->>Server: resources/templates/list Server->>Bridge: Available resource templates Note over Claude,Server: Tool Execution Claude->>Bridge: tools/call Bridge->>Server: tools/call (HTTP/HTTPS) Server->>Bridge: Tool execution result Bridge->>Claude: Tool result Note over Claude,Server: Resource Access Claude->>Bridge: resources/read Bridge->>Server: resources/read (HTTP/HTTPS) Server->>Bridge: Resource content Bridge->>Claude: Resource data Note over Claude,Server: Prompt Operations Claude->>Bridge: prompts/get Bridge->>Server: prompts/get (HTTP/HTTPS) Server->>Bridge: Prompt messages Bridge->>Claude: Prompt content Note over Bridge,Server: Completion Support Claude->>Bridge: completion/complete Bridge->>Server: completion/complete (HTTP/HTTPS) Server->>Bridge: Completion suggestions Bridge->>Claude: Completions Note over Bridge,Server: Real-time Change Notifications Server->>Bridge: notifications/tools/list_changed Bridge->>Server: tools/list (refresh) Server->>Bridge: notifications/resources/list_changed Bridge->>Server: resources/list (refresh) Server->>Bridge: notifications/prompts/list_changed Bridge->>Server: prompts/list (refresh) Server->>Bridge: notifications/resources/updated Note over Bridge: Updates resource cache Note over Bridge,Server: Resource Subscriptions Bridge->>Server: resources/subscribe Server->>Bridge: Subscription confirmed Bridge->>Server: resources/unsubscribe Server->>Bridge: Unsubscription confirmed Note over Claude,Server: MCP 2025-06-18 Features Claude->>Bridge: sampling/createMessage Bridge->>Server: sampling/createMessage (HTTP/HTTPS) Server->>Bridge: Generated message Bridge->>Claude: Sampled content Server->>Bridge: elicit (request user input) Bridge->>Claude: Elicitation prompt Claude->>Bridge: User response Bridge->>Server: Elicit result Bridge->>Server: logging/setLevel Server->>Bridge: Logging level updated Bridge->>Server: roots/list Server->>Bridge: Access boundaries ``` ### 2. Transport Types #### HTTP Streaming (Default) - Single endpoint for all requests - Streamable response format - Session management via `Mcp-Session-Id` header #### Server-Sent Events (SSE) - `/messages` endpoint for POST requests - Event-stream responses - Session management via query parameters ### 3. Complete MCP 2025-03-26 Discovery Process On startup, the bridge automatically: 1. Connects to the MCP server with appropriate transport detection 2. Sends `tools/list` request to discover available tools 3. Sends `resources/list` request to discover available resources 4. Sends `prompts/list` request to discover available prompts 5. Establishes session management with `Mcp-Session-Id` (HTTP) or sessionId query param (SSE) 6. Listens for change notifications: - `notifications/tools/list_changed` - `notifications/resources/list_changed` - `notifications/prompts/list_changed` - `notifications/resources/updated` 7. Automatically refreshes capabilities when notifications are received ### 4. Transport Features #### Streamable HTTP (2025-06-18 Spec) - **Endpoint**: Single endpoint (`/mcp` or server base URL) - **Session Management**: `Mcp-Session-Id` header - **Bidirectional**: Request/response and streaming notifications - **Efficiency**: Optimized for serverless deployments #### Server-Sent Events (2024-11-05 Spec) - **Endpoints**: `/sse` for connection, `/messages` for requests - **Session Management**: `sessionId` query parameter - **Compatibility**: Legacy support for older MCP servers ## Logging ### Finding the Log File The vikstra-bridge creates its log file in an OS-specific temp directory: - **macOS**: `/var/folders/.../T/vikstra-bridge/vikstra-bridge.log` - **Linux**: `/tmp/vikstra-bridge/vikstra-bridge.log` - **Windows**: `%TEMP%\vikstra-bridge\vikstra-bridge.log` To find your exact log file location: ```bash # On macOS/Linux echo "$TMPDIR/vikstra-bridge/vikstra-bridge.log" # macOS echo "/tmp/vikstra-bridge/vikstra-bridge.log" # Linux # On Windows (PowerShell) echo "$env:TEMP\vikstra-bridge\vikstra-bridge.log" # Or simply check the startup output when running with -verbose flag ./vikstra-bridge https://api.example.com/mcp -verbose ``` ### What Gets Logged All operations are logged including: - **Startup Information**: CLI arguments, environment variables, parsed headers - **MCP Operations**: Tools/resources discovery, change notifications - **HTTP Requests**: Complete request details including all headers - **Sensitive Data**: Headers like Authorization are logged to file but redacted from stdout ### Log Format ``` [VIKSTRA] 2025/08/25 12:00:00.000000 === MCP Bridge Started === [VIKSTRA] 2025/08/25 12:00:00.000001 MCP Server URL: https://api.example.com/mcp [VIKSTRA] 2025/08/25 12:00:00.000002 Transport: Streamable HTTP [VIKSTRA] 2025/08/25 12:00:00.000003 Environment variables: [VIKSTRA] 2025/08/25 12:00:00.000004 API_TOKEN=secret-value [VIKSTRA] 2025/08/25 12:00:00.000005 Parsed headers (1 total): [VIKSTRA] 2025/08/25 12:00:00.000006 Authorization: Bearer secret-value [VIKSTRA] 2025/08/25 12:00:01.000000 Listing available tools... [VIKSTRA] 2025/08/25 12:00:01.000100 Updated tools capabilities: 5 tools available [VIKSTRA] 2025/08/25 12:00:01.000101 Tool: get_weather (Get current weather information) [VIKSTRA] 2025/08/25 12:00:01.000102 Listing available resources... [VIKSTRA] 2025/08/25 12:00:01.000200 Updated resources capabilities: 3 resources available [VIKSTRA] 2025/08/25 12:00:01.000201 - config.json (file:///config.json): Application configuration [VIKSTRA] 2025/08/25 12:00:01.000202 Listing available prompts... [VIKSTRA] 2025/08/25 12:00:01.000300 Updated prompts capabilities: 2 prompts available [VIKSTRA] 2025/08/25 12:00:01.000301 Prompt: code_review (Generate code review comments) [VIKSTRA] 2025/08/25 12:00:01.000400 MCP capabilities initialization completed ``` ## Project Structure ``` vikstra-bridge/ ├── internal/ # Private application packages │ ├── app/ # Main application logic │ │ ├── app.go # Core application runner │ │ └── cli.go # Command-line interface handling │ ├── bridge/ # Core bridge functionality │ │ ├── bridge.go # Main bridge implementation │ │ └── capabilities.go # MCP capability management │ ├── config/ # Configuration parsing │ │ ├── config.go # Config structures and validation │ │ └── config_test.go # Configuration tests │ └── mcp/ # MCP protocol implementation │ ├── protocol.go # Protocol handler │ └── protocol_test.go # Protocol tests ├── pkg/types/ # Public type definitions │ ├── mcp.go # MCP type definitions │ └── mcp_test.go # Type marshaling tests ├── test/ # Testing infrastructure │ ├── integration/ # Integration tests │ └── fixtures/ # Test fixtures and data ├── vikstra-bridge.go # Main application entrypoint ├── Makefile # Build automation ├── go.mod # Go module definition ├── LICENSE # MIT License └── README.md # This file ``` ## Architecture ### MCP 2025-03-26 Compliance Features The bridge implements the complete MCP specification with: 1. **Transport Layer**: - Primary: Streamable HTTP with `Mcp-Session-Id` header - Fallback: SSE transport with session query parameters - Auto-detection based on URL patterns (`/sse` → SSE, others → HTTP) 2. **Message Handling**: - JSON-RPC 2.0 compliant message processing - Request/response correlation with unique IDs - Error handling with standard JSON-RPC error codes 3. **Capability Management**: - Automatic discovery of tools, resources, and prompts - Real-time updates via change notifications - Efficient caching with timestamp tracking 4. **Security**: - Strict HTTPS/HTTP URL validation - Environment variable expansion in headers - Canonical HTTP header formatting - Sensitive data logging to secure file location ## Error Handling The bridge provides clear error messages for common issues: - Missing MCP server URL - Invalid URL format (must start with http:// or https://) - Invalid transport type - HTTP connection failures - JSON-RPC parsing errors ## MCP Specification Details ### Supported MCP Methods - **Discovery Methods**: - `tools/list` - Tool discovery with pagination support - `resources/list` - Resource discovery with pagination support - `resources/templates/list` - Resource template discovery *(MCP 2025-06-18)* - `prompts/list` - Prompt discovery with pagination support - `roots/list` - Access boundary discovery *(MCP 2025-06-18)* - **Action Methods**: - `tools/call` - Tool execution with argument validation - `resources/read` - Resource content access with MIME type support - `prompts/get` - Prompt template retrieval with argument substitution - **Subscription Methods**: - `resources/subscribe` - Subscribe to resource change notifications - `resources/unsubscribe` - Unsubscribe from resource notifications - **Completion Methods**: - `completion/complete` - Auto-completion for prompts and resources - **Sampling Methods** *(MCP 2025-06-18)*: - `sampling/createMessage` - LLM message generation with temperature control - **Logging Methods** *(MCP 2025-06-18)*: - `logging/setLevel` - Dynamic log level configuration - **Elicitation Methods** *(MCP 2025-06-18)*: - `elicit` - Request structured user input with JSON schema validation - **Core Methods**: - `initialize` - Protocol handshake and capability negotiation - `ping` - Connection health check - **Transparent Proxy**: All other JSON-RPC 2.0 methods forwarded directly ### Supported Notifications - `notifications/tools/list_changed` - Tool list updates trigger automatic refresh - `notifications/resources/list_changed` - Resource list updates trigger automatic refresh - `notifications/prompts/list_changed` - Prompt list updates trigger automatic refresh - `notifications/resources/updated` - Individual resource change notifications ### Session Management - Automatic session extraction from initialize responses - Session persistence across requests - Transport-specific session han … ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [unarii](https://github.com/unarii) - **Source:** [unarii/vikstra-bridge](https://github.com/unarii/vikstra-bridge) - **License:** MIT - **Homepage:** https://vikstra.ai/bridge Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-unarii-vikstra-bridge - Seller: https://agentstack.voostack.com/s/unarii - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.