Skip to content

HTTP Server Mode

Documentation for running BNB-Chain-MCP as an HTTP server for web integrations and ChatGPT Developer Mode.

Overview

HTTP mode enables BNB-Chain-MCP to serve requests over HTTP, making it compatible with:

  • ChatGPT Developer Mode - OpenAI's custom tools
  • Web Applications - Direct API integration
  • Custom Agents - LangChain, AutoGen, CrewAI
  • REST Clients - Postman, curl, httpie

Quick Start

Start the Server

# Using npx (recommended)
npx @nirholas/bnb-chain-mcp@latest --http

# With environment variables
PRIVATE_KEY=0x... PORT=3001 npx @nirholas/bnb-chain-mcp@latest --http

# Local development
cd bnb-chain-mcp
bun run dev:http

Default Configuration

Setting Value
Port 3001
Host 0.0.0.0
Protocol HTTP
MCP Endpoint /mcp

ChatGPT Developer Mode Setup

Prerequisites

  1. ChatGPT Plus or Team subscription
  2. Developer Mode enabled in settings
  3. BNB-Chain-MCP running in HTTP mode

Step-by-Step Setup

1. Start the Server

npx @nirholas/bnb-chain-mcp@latest --http

Server starts at http://localhost:3001

2. Expose to Internet

For ChatGPT to reach your local server, use a tunnel:

ngrok http 3001
# Copy the https URL: https://abc123.ngrok.io

cloudflared tunnel --url http://localhost:3001
# Copy the https URL

npx localtunnel --port 3001
# Copy the https URL

3. Configure in ChatGPT

  1. Go to Settings → Apps → Developer Mode
  2. Click Create App
  3. Enter:
  4. Name: BNB-Chain-MCP
  5. URL: https://your-tunnel-url.ngrok.io/mcp
  6. Click Save

4. Use in Conversations

Start a new conversation and select your app from the Developer Mode menu. Then ask:

"What's the current price of Ethereum?"

ChatGPT will call your MCP server to get the answer.

API Endpoints

MCP Protocol Endpoint

POST /mcp
Content-Type: application/json

Handles MCP protocol messages including tool calls, resource requests, and prompts.

Health Check

GET /health

Returns server status:

{
  "status": "ok",
  "version": "1.0.0",
  "uptime": 3600,
  "tools": 120
}

Tool List

GET /tools

Returns available tools:

{
  "tools": [
    {
      "name": "network_get_info",
      "description": "Get network information",
      "inputSchema": {...}
    }
  ]
}

Request/Response Format

Tool Call Request

curl -X POST http://localhost:3001/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "market_get_coin_by_id",
      "arguments": {
        "coinId": "bitcoin"
      }
    }
  }'

Tool Call Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"id\":\"bitcoin\",\"name\":\"Bitcoin\",\"price\":43250.00,...}"
      }
    ]
  }
}

List Tools Request

curl -X POST http://localhost:3001/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }'

Configuration

Environment Variables

# Server configuration
PORT=3001                          # HTTP port
HOST=0.0.0.0                       # Listen address

# Wallet (for write operations)
PRIVATE_KEY=0x...                  # Wallet private key

# API Keys
COINGECKO_API_KEY=your_key
COINSTATS_API_KEY=your_key
LUNARCRUSH_API_KEY=your_key
CRYPTOPANIC_API_KEY=your_key

# Logging
LOG_LEVEL=INFO                     # DEBUG, INFO, WARN, ERROR

CORS Configuration

By default, CORS is enabled for all origins. For production, restrict:

CORS_ORIGINS=https://chat.openai.com,https://yourapp.com

Production Deployment

Docker

FROM oven/bun:1

WORKDIR /app
COPY package.json bun.lockb ./
RUN bun install --frozen-lockfile

COPY . .

EXPOSE 3001
ENV PORT=3001

CMD ["bun", "run", "start:http"]

docker build -t bnb-chain-mcp .
docker run -p 3001:3001 -e PRIVATE_KEY=0x... bnb-chain-mcp

Docker Compose

version: '3.8'
services:
  crypto-mcp:
    build: .
    ports:
      - "3001:3001"
    environment:
      - PORT=3001
      - PRIVATE_KEY=${PRIVATE_KEY}
      - COINGECKO_API_KEY=${COINGECKO_API_KEY}
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3001/health"]
      interval: 30s
      timeout: 10s
      retries: 3

Kubernetes

apiVersion: apps/v1
kind: Deployment
metadata:
  name: crypto-mcp
spec:
  replicas: 2
  selector:
    matchLabels:
      app: crypto-mcp
  template:
    metadata:
      labels:
        app: crypto-mcp
    spec:
      containers:
      - name: crypto-mcp
        image: your-registry/bnb-chain-mcp:latest
        ports:
        - containerPort: 3001
        env:
        - name: PORT
          value: "3001"
        - name: PRIVATE_KEY
          valueFrom:
            secretKeyRef:
              name: crypto-mcp-secrets
              key: private-key
        resources:
          requests:
            memory: "256Mi"
            cpu: "100m"
          limits:
            memory: "512Mi"
            cpu: "500m"
        livenessProbe:
          httpGet:
            path: /health
            port: 3001
          initialDelaySeconds: 10
          periodSeconds: 30
---
apiVersion: v1
kind: Service
metadata:
  name: crypto-mcp
spec:
  selector:
    app: crypto-mcp
  ports:
  - port: 80
    targetPort: 3001
  type: LoadBalancer

Load Balancing

Nginx Configuration

upstream crypto_mcp {
    least_conn;
    server 127.0.0.1:3001;
    server 127.0.0.1:3002;
    server 127.0.0.1:3003;
}

server {
    listen 80;
    server_name api.yourservice.com;

    location /mcp {
        proxy_pass http://crypto_mcp;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_cache_bypass $http_upgrade;

        # Timeouts for long-running operations
        proxy_read_timeout 300s;
        proxy_send_timeout 300s;
    }

    location /health {
        proxy_pass http://crypto_mcp;
    }
}

Security

TLS/HTTPS

For production, always use HTTPS:

# Using Let's Encrypt with nginx
certbot --nginx -d api.yourservice.com

API Key Authentication

Implement authentication middleware:

// Add to server configuration
const API_KEY = process.env.API_KEY;

app.use('/mcp', (req, res, next) => {
  const key = req.headers['x-api-key'];
  if (key !== API_KEY) {
    return res.status(401).json({ error: 'Unauthorized' });
  }
  next();
});

Rate Limiting

import rateLimit from 'express-rate-limit';

const limiter = rateLimit({
  windowMs: 60 * 1000, // 1 minute
  max: 100, // 100 requests per minute
  message: { error: 'Rate limit exceeded' }
});

app.use('/mcp', limiter);

Monitoring

Prometheus Metrics

import { collectDefaultMetrics, register } from 'prom-client';

collectDefaultMetrics();

app.get('/metrics', async (req, res) => {
  res.set('Content-Type', register.contentType);
  res.end(await register.metrics());
});

Logging

# Enable structured logging
LOG_FORMAT=json LOG_LEVEL=INFO npx @nirholas/bnb-chain-mcp --http

# Output
{"level":"info","timestamp":"2024-01-26T12:00:00Z","message":"Tool called","tool":"market_get_coin_by_id","duration":245}

Troubleshooting

Common Issues

Issue Solution
Port already in use Change PORT env or kill existing process
Connection refused Check firewall rules
CORS errors Configure CORS_ORIGINS
Timeout errors Increase proxy timeouts
502 Bad Gateway Check server is running

Debug Mode

LOG_LEVEL=DEBUG npx @nirholas/bnb-chain-mcp --http

Test Connection

# Health check
curl http://localhost:3001/health

# List tools
curl -X POST http://localhost:3001/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# Call tool
curl -X POST http://localhost:3001/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"network_get_info","arguments":{"network":"ethereum"}}}'

Next Steps