@nimbletools/mcp-http-bridge

MCP HTTP Bridge

Bridge the Model Context Protocol (MCP) stdio interface to HTTP-based MCP services. This allows MCP clients like Claude Code to seamlessly connect to remote MCP servers running over HTTP.

Requirements

• Node.js 24.0.0 or higher
• npm 10.0.0 or higher

Installation

npm install -g @nimbletools/mcp-http-bridge

Or use directly with npx:

npx @nimbletools/mcp-http-bridge --endpoint "https://..." --token "..."

Usage

Command Line

mcp-http-bridge \
  --endpoint "https://api.example.com/mcp" \
  --token "your-bearer-token" \
  --timeout 15000 \
  --retries 2

With Claude Code

Add to your Claude Code configuration:

{
  "mcpServers": {
    "my-remote-server": {
      "command": "npx",
      "args": [
        "@nimbletools/mcp-http-bridge",
        "--endpoint", "https://api.example.com/mcp",
        "--token", "your-bearer-token"
      ]
    }
  }
}

With Environment Variables

For better security, use environment variables:

{
  "mcpServers": {
    "my-remote-server": {
      "command": "mcp-http-bridge",
      "args": [
        "--endpoint", "https://api.example.com/mcp"
      ],
      "env": {
        "MCP_BEARER_TOKEN": "your-bearer-token"
      }
    }
  }
}

Options

Option	Alias	Default	Description
--endpoint	-e	required	HTTP endpoint for the MCP service
--token	-t	required	Bearer token for authentication
--timeout		30000	Request timeout in milliseconds
--retries		3	Number of retry attempts
--verbose	-v	false	Enable verbose logging

How It Works

The bridge acts as a protocol translator:

• Input: Accepts MCP JSON-RPC messages via stdin
• Translation: Forwards them as HTTP POST requests to your endpoint
• Output: Returns responses via stdout in MCP format

Claude Code ↔ stdio/JSON-RPC ↔ MCP HTTP Bridge ↔ HTTP/JSON ↔ Your MCP Service

Authentication

The bridge adds Bearer token authentication to all HTTP requests:

POST /mcp HTTP/1.1
Authorization: Bearer your-token-here
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "method": "tools/list",
  "id": 1
}

Error Handling

• 4xx Client Errors: Returned immediately (no retries)
• 5xx Server Errors: Retried with exponential backoff
• Network Errors: Retried with exponential backoff
• Timeouts: Configurable per request

Examples

Basic Usage

mcp-http-bridge \
  --endpoint "https://mcp.example.com/api" \
  --token "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

With Custom Timeout

mcp-http-bridge \
  --endpoint "https://slow-service.com/mcp" \
  --token "abc123" \
  --timeout 60000 \
  --retries 5

Testing Connectivity

echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | \
  mcp-http-bridge --endpoint "https://api.com/mcp" --token "token"

Development

# Clone the repository
git clone https://github.com/nimbletools/mcp-http-bridge.git
cd mcp-http-bridge

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run locally
npm run dev -- --endpoint "https://..." --token "..."

Contributing

• Fork the repository
• Create a feature branch
• Make your changes
• Add tests if applicable
• Submit a pull request

License

MIT License - see LICENSE file for details.

Support

• 🐛 Report Issues
• 📖 Documentation
• 💬 Discussions