@qwst_desenvolvimento/mcp-connector-http-apikey/README.md

MCP connector for HTTP servers with API key authentication. Bridges MCP clients to HTTP-based MCP servers using x-api-key header authentication.

# 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)

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

### Local Installation

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

### Using NPX (No Installation Required)

```bash
npx @qwst_desenvolvimento/mcp-connector-http-apikey
```

## 🔧 Usage

### 1. Set Environment Variables

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

### 2. Run the Connector

#### Using NPX (Recommended):

```bash
npx @qwst_desenvolvimento/mcp-connector-http-apikey
```

#### If installed globally:

```bash
mcp-connector-http-apikey
```

#### If installed locally:

```bash
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)

```json
{
	"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:

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

Then configure:

```json
{
	"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)

```json
{
	"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:

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

Then configure:

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

```bash
# 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

```bash
# 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

```bash
# 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:

```bash
# 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:

```bash
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](https://github.com/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](#-troubleshooting) above.