MCP Connector Streamable HTTP API Key Stateless

MCP (Model Context Protocol) connector for streamable stateless HTTP MCP servers that use API key (x-api-key) authentication. This connector acts as a bridge between MCP clients (like Claude Desktop, Cursor, Windsurf) and HTTP-based MCP servers that use x-api-key header authentication.

🚀 Features

• HTTP API Key Authentication: Specifically designed for HTTP-based MCP servers using x-api-key header
• Simple Configuration: Only requires 2 environment variables (MCP_SERVER_URL and MCP_API_KEY)
• Full MCP Protocol Support: Supports all MCP resources:
  • ✅ Tools - Execute server-side functions
  • ✅ Prompts - Access server-side prompt templates
  • ✅ Resources - Access server-side data and files
  • ✅ Samples - Access example data
  • ✅ Elicitations - Access interactive prompts
• Robust Error Handling: Graceful error handling and retry mechanisms
• Session Management: Automatic session handling for stateful servers
• Debug Mode: Optional debug logging for troubleshooting

📦 Installation

Global Installation (Recommended)

npm install -g @qwst_desenvolvimento/mcp-connector-http-apikey

Local Installation

npm install @qwst_desenvolvimento/mcp-connector-http-apikey

Using NPX (No Installation Required)

npx @qwst_desenvolvimento/mcp-connector-http-apikey

🔧 Usage

1. Set Environment Variables

export MCP_SERVER_URL=http://localhost:3000/mcp
export MCP_API_KEY=your-api-key-here

2. Run the Connector

Using NPX (Recommended):

npx @qwst_desenvolvimento/mcp-connector-http-apikey

If installed globally:

mcp-connector-http-apikey

If installed locally:

npx @qwst_desenvolvimento/mcp-connector-http-apikey

🛠️ Configuration

Required Environment Variables

| Variable | Description | Example | | ---------------- | ------------------------------------ | --------------------------- | | MCP_SERVER_URL | Full URL to your MCP server endpoint | http://localhost:3000/mcp | | MCP_API_KEY | API key for authentication | your-secret-api-key |

Optional Environment Variables

| Variable | Description | Default | Example | | ---------------------- | ----------------------------------------- | ------- | ------- | | MCP_DEBUG | Enable debug logging | false | true | | MCP_SHUTDOWN_TIMEOUT | Graceful shutdown timeout in milliseconds | 10000 | 15000 |

📋 MCP Client Configuration

Claude Desktop

Add to your claude_desktop_config.json:

Option 1: Using NPX (Recommended)

{
	"mcpServers": {
		"your-mcp-server": {
			"command": "npx",
			"args": ["@qwst_desenvolvimento/mcp-connector-http-apikey"],
			"env": {
				"MCP_SERVER_URL": "http://localhost:3000/mcp",
				"MCP_API_KEY": "your-api-key-here",
				"MCP_DEBUG": "false"
			}
		}
	}
}

Option 2: Global Installation

First install globally:

npm install -g @qwst_desenvolvimento/mcp-connector-http-apikey

Then configure:

{
	"mcpServers": {
		"your-mcp-server": {
			"command": "mcp-connector-http-apikey",
			"env": {
				"MCP_SERVER_URL": "http://localhost:3000/mcp",
				"MCP_API_KEY": "your-api-key-here",
				"MCP_DEBUG": "false"
			}
		}
	}
}

Cursor

Add to your .cursor/mcp.json configuration:

Option 1: Using NPX (Recommended)

{
	"mcpServers": {
		"your-mcp-server": {
			"command": "npx",
			"args": ["@qwst_desenvolvimento/mcp-connector-http-apikey"],
			"env": {
				"MCP_SERVER_URL": "http://localhost:3000/mcp",
				"MCP_API_KEY": "your-api-key-here",
				"MCP_DEBUG": "false"
			}
		}
	}
}

Option 2: Global Installation

First install globally:

npm install -g @qwst_desenvolvimento/mcp-connector-http-apikey

Then configure:

{
	"mcpServers": {
		"your-mcp-server": {
			"command": "mcp-connector-http-apikey",
			"env": {
				"MCP_SERVER_URL": "http://localhost:3000/mcp",
				"MCP_API_KEY": "your-api-key-here",
				"MCP_DEBUG": "false"
			}
		}
	}
}

Note: Replace your-mcp-server with a descriptive name for your server, and update the URL and API key accordingly.

📚 Examples

Example 1: Basic Usage

# Set environment variables
export MCP_SERVER_URL=http://localhost:3000/mcp
export MCP_API_KEY=my-secret-key

# Run connector
npx @qwst_desenvolvimento/mcp-connector-http-apikey

Example 2: With Debug Mode

# Enable debug logging
export MCP_DEBUG=true
export MCP_SERVER_URL=http://localhost:3000/mcp
export MCP_API_KEY=my-secret-key

# Run connector
npx @qwst_desenvolvimento/mcp-connector-http-apikey

Example 3: Custom Shutdown Timeout

# Set custom graceful shutdown timeout (15 seconds)
export MCP_SHUTDOWN_TIMEOUT=15000
export MCP_SERVER_URL=http://localhost:3000/mcp
export MCP_API_KEY=my-secret-key

# Run connector
npx @qwst_desenvolvimento/mcp-connector-http-apikey

🔒 Security

• The connector uses the x-api-key header for authentication
• API keys are never logged (only first 8 characters for debugging)
• Supports both HTTP and HTTPS connections
• Session IDs are automatically managed for stateful servers

📝 Logging

Unique Log Files

Each connector instance creates its own unique log file based on the server URL to prevent log conflicts when running multiple instances:

• Local server (localhost:3002) → mcp-connector-localhost_3002.log
• Remote server (api.example.com) → mcp-connector-api.example.com.log

This ensures that multiple MCP configurations in the same client (like Cursor or Claude Desktop) don't interfere with each other's logs.

Debug Mode

When MCP_DEBUG=true is set:

• Detailed logs are written to the unique log file
• Console output includes all operations
• HTTP requests and responses are logged
• Session management details are shown

When MCP_DEBUG=false (default):

• No log files are created
• Minimal console output
• Production-ready behavior

🧪 Testing

You can test the connector with any MCP server. Here's a simple test:

# Test with curl (if your server supports direct HTTP calls)
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'

🐛 Troubleshooting

Common Issues

1. "MCP_SERVER_URL environment variable is required"

   • Solution: Make sure you've set the MCP_SERVER_URL environment variable

2. "MCP_API_KEY environment variable is required"

   • Solution: Make sure you've set the MCP_API_KEY environment variable

3. "HTTP 401: Unauthorized"

   • Solution: Check that your API key is correct and has proper permissions

4. "Connection timeout"

   • Solution: Check server availability and network connectivity

5. "No tools/prompts/resources found"

   • Solution: Verify your server implements the MCP protocol correctly

Debug Mode

Enable debug mode for detailed logging:

export MCP_DEBUG=true
npx @qwst_desenvolvimento/mcp-connector-http-apikey

This will create a unique log file (e.g., mcp-connector-localhost_3002.log) and show:

• All HTTP requests and responses
• Session management details
• Tool/prompt/resource registration process
• Error details
• Unique log file path being used

Note: Multiple connector instances will create separate log files, preventing conflicts.

📖 Protocol Support

This connector implements the MCP Protocol version 2025-03-26 and supports:

• JSON-RPC 2.0: Standard protocol for communication
• Tools: tools/list and tools/call methods
• Prompts: prompts/list and prompts/get methods
• Resources: resources/list and resources/read methods
• Session Management: Automatic session handling
• Error Handling: Proper error propagation and formatting

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

• Built with @modelcontextprotocol/sdk
• Inspired by the need for universal MCP connectivity
• Created by Gustavo Cerqueira for the community

Need help? Open an issue on GitHub or check the troubleshooting section above.