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:

Connects to the MCP server with appropriate transport detection
Sends tools/list request to discover available tools
Sends resources/list request to discover available resources
Sends prompts/list request to discover available prompts
Establishes session management with Mcp-Session-Id (HTTP) or sessionId query param (SSE)
Listens for change notifications:
- notifications/tools/list_changed
- notifications/resources/list_changed
- notifications/prompts/list_changed
- notifications/resources/updated
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:

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)
Message Handling:
- JSON-RPC 2.0 compliant message processing
- Request/response correlation with unique IDs
- Error handling with standard JSON-RPC error codes
Capability Management:
- Automatic discovery of tools, resources, and prompts
- Real-time updates via change notifications
- Efficient caching with timestamp tracking
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

Connection Refused
```
Error: HTTP request failed: connection refused
```
- Check if MCP server is running
- Verify URL is correct
- Check network connectivity
Authentication Failed
```
Error: HTTP 401: Unauthorized
```
- Verify API tokens are correct
- Check header format: "Authorization: Bearer TOKEN"
- Ensure environment variables are set
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

Name		Name	Last commit message	Last commit date
Latest commit History 5 Commits
internal		internal
pkg/types		pkg/types
test		test
.gitignore		.gitignore
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
go.mod		go.mod
vikstra-bridge.go		vikstra-bridge.go

License

unarii/vikstra-bridge

Folders and files

Latest commit

History

Repository files navigation

Vikstra MCP Bridge

Overview

Features

MCP Specification Compliance

Supported MCP Methods

Advanced Features

Installation

From Source (Recommended)

Development Mode

Usage

Basic Syntax

Command Line Options

Examples

Basic MCP Connection

With Authentication Headers

Force SSE Transport

Debug Mode

Environment Variable Support

Claude Desktop Integration

How It Works

1. MCP Protocol Flow

2. Transport Types

HTTP Streaming (Default)

Server-Sent Events (SSE)

3. Complete MCP 2025-03-26 Discovery Process

4. Transport Features

Streamable HTTP (2025-06-18 Spec)

Server-Sent Events (2024-11-05 Spec)

Logging

Finding the Log File

What Gets Logged

Log Format

Project Structure

Architecture

MCP 2025-03-26 Compliance Features

Error Handling

MCP Specification Details

Supported MCP Methods

Supported Notifications

Session Management

Troubleshooting

Common Issues

Debug Mode

Development

Building from Source

Testing

Contributing

Development Setup

Code Style

License

Acknowledgments

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Languages

Packages