Vikstra MCP Bridge

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)

git clone <repository-url>
cd vikstra-bridge
go build -o vikstra-bridge

Development Mode

# Run directly without building
go run ./vikstra-bridge.go <MCP_SERVER_URL> [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

./vikstra-bridge <MCP_SERVER_URL> [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

./vikstra-bridge https://api.example.com/mcp

With Authentication Headers

./vikstra-bridge https://api.example.com/mcp \
  -header "Authorization: Bearer ${API_TOKEN}" \
  -header "X-API-Key: ${API_KEY}"

Force SSE Transport

./vikstra-bridge https://api.example.com/sse -transport sse

Debug Mode

./vikstra-bridge https://api.example.com/mcp -debug

Environment Variable Support

Headers support environment variable expansion using ${VARIABLE_NAME} syntax:

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:

{
  "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

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:

# 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 handling (header vs query parameter)

Troubleshooting

Common Issues

1. Connection Refused

   Error: HTTP request failed: connection refused
   

   • Check if MCP server is running
   • Verify URL is correct
   • Check network connectivity

2. Authentication Failed

   Error: HTTP 401: Unauthorized
   

   • Verify API tokens are correct
   • Check header format: "Authorization: Bearer TOKEN"
   • Ensure environment variables are set

3. No Tools/Resources Found

   Listed 0 tools:
   Listed 0 resources:
   

   • Normal if server doesn't expose tools/resources
   • Check server logs for MCP implementation details

Debug Mode

Enable debug mode to see detailed operation logs:

./vikstra-bridge https://api.example.com/mcp -debug

This will show:

• All HTTP headers being sent
• Request/response details
• MCP discovery process
• Change notification handling

Development

Building from Source

go mod init vikstra.ai/bridge
go build -o vikstra-bridge

Testing

# Test with a mock MCP server
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"clientInfo":{"name":"test","version":"1.0"}}}' | \
  ./vikstra-bridge https://httpbin.org/post -debug

Contributing

We welcome contributions! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Development Setup

# Clone the repository
git clone <repository-url>
cd vikstra-bridge

# Build the project
make build

# Run tests
make test

# Clean build artifacts
make clean

Code Style

• Follow standard Go formatting with go fmt
• Write tests for new functionality
• Update documentation for user-facing changes
• Ensure all tests pass before submitting PR

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Built for the Model Context Protocol specification
• Designed to work seamlessly with Claude Desktop