NimbleTools - 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.

For more information about MCP and related tools, visit www.nimbletools.ai.

Requirements

• Node.js 20.0.0 or higher
• npm 9.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 "..."

Updating

To update to the latest version:

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

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:

1. Input: Accepts MCP JSON-RPC messages via stdin
2. Translation: Forwards them as HTTP POST requests to your endpoint
3. Session Management: Automatically captures and manages mcp-session-id headers
4. Output: Returns responses via stdout in MCP format

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

Features

• ✅ Session ID Management: Automatically captures and includes mcp-session-id headers
• ✅ Server-Sent Events: Supports both JSON and SSE response formats
• ✅ Content Type Negotiation: Accepts application/json and text/event-stream
• ✅ Error Handling: Robust retry logic with exponential backoff
• ✅ Authentication: Bearer token support

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

Local Development with Claude Code

For testing during development, you can configure Claude Code to use either your local build or the published package:

Using local build:

{
  "mcpServers": {
    "national-parks": {
      "command": "node",
      "args": [
        "/path/to/your/mcp-http-bridge/dist/cli.js",
        "--endpoint",
        "https://mcp.nimbletools.dev/v1/workspaces/your-workspace-id/servers/nationalparks-mcp/mcp",
        "--token",
        "your-auth-token-here",
        "--insecure"
      ],
      "auth": null,
      "oauth": false
    }
  }
}

Using published package with npx:

{
  "mcpServers": {
    "national-parks": {
      "command": "npx",
      "args": [
        "@nimbletools/mcp-http-bridge",
        "--endpoint",
        "https://mcp.nimbletools.dev/v1/workspaces/your-workspace-id/servers/nationalparks-mcp/mcp",
        "--token",
        "your-auth-token-here",
        "--insecure"
      ],
      "auth": null,
      "oauth": false
    }
  }
}

Replace the workspace ID and token with your actual credentials. The --insecure flag is useful for development against local or test endpoints.

Contributing

We welcome contributions! If you're interested in contributing, please read our Contributing Guide for details on our development process, how to propose bugfixes and improvements, and how to build and test your changes.

License

MIT License - see LICENSE file for details.

Support

• 🐛 Report Issues
• 📖 Documentation
• 💬 Discussions
• 💬 Join our Slack Community