HTTP Transport for MCP Servers

Overview

NeuroLink now supports HTTP/Streamable HTTP transport for Model Context Protocol (MCP) servers, enabling integration with remote MCP services like GitHub Copilot MCP API and custom HTTP-based MCP endpoints.

The HTTP transport implements the MCP Streamable HTTP specification, providing:

• ✅ Remote MCP server connectivity
• ✅ Custom header support for authentication
• ✅ Session management and automatic reconnection
• ✅ Firewall and proxy compatibility
• ✅ Both streaming (SSE) and batch JSON responses

Quick Start

GitHub Copilot Integration

# Add GitHub Copilot MCP endpoint
npx neurolink mcp add github-copilot "https://api.githubcopilot.com/mcp" \
  --transport http \
  --url "https://api.githubcopilot.com/mcp" \
  --headers '{"Authorization": "Bearer YOUR_GITHUB_COPILOT_TOKEN"}'

Configuration File

Add to .mcp-config.json:

{
  "mcpServers": {
    "github-copilot": {
      "name": "github-copilot",
      "command": "https://api.githubcopilot.com/mcp",
      "transport": "http",
      "url": "https://api.githubcopilot.com/mcp",
      "headers": {
        "Authorization": "Bearer ghp_xxxxxxxxxxxxxxxxxxxx"
      },
      "description": "GitHub Copilot MCP API"
    }
  }
}

Programmatic Usage

import { NeuroLink } from "@juspay/neurolink";

const neurolink = new NeuroLink();

// Add HTTP MCP server
await neurolink.addInMemoryMCPServer("github-copilot", {
  server: {
    title: "GitHub Copilot MCP",
    description: "GitHub Copilot API integration",
    tools: {},
  },
  config: {
    id: "github-copilot",
    name: "github-copilot",
    description: "GitHub Copilot MCP API",
    command: "https://api.githubcopilot.com/mcp",
    transport: "http",
    url: "https://api.githubcopilot.com/mcp",
    headers: {
      Authorization: "Bearer YOUR_TOKEN",
    },
    tools: [],
    status: "initializing",
  },
});

// Use the MCP server
const result = await neurolink.generate({
  input: { text: "Use GitHub Copilot to help me write code" },
  provider: "openai",
  disableTools: false,
});

Authentication

HTTP transport supports custom headers for authentication:

Bearer Token Authentication

{
  "headers": {
    "Authorization": "Bearer YOUR_TOKEN"
  }
}

API Key Authentication

{
  "headers": {
    "X-API-Key": "your-api-key-here"
  }
}

Custom Headers

{
  "headers": {
    "Authorization": "Bearer YOUR_TOKEN",
    "X-Custom-Header": "custom-value",
    "X-Request-ID": "unique-request-id"
  }
}

OAuth 2.1 Authentication

For enterprise integrations requiring OAuth 2.1 with PKCE:

{
  "mcpServers": {
    "enterprise-api": {
      "transport": "http",
      "url": "https://api.enterprise.com/mcp",
      "auth": {
        "type": "oauth2",
        "oauth": {
          "clientId": "your-client-id",
          "clientSecret": "your-client-secret",
          "authorizationUrl": "https://auth.enterprise.com/oauth/authorize",
          "tokenUrl": "https://auth.enterprise.com/oauth/token",
          "redirectUrl": "http://localhost:8080/callback",
          "scope": "mcp:read mcp:write",
          "usePKCE": true
        }
      }
    }
  }
}

OAuth Configuration Options:

Option	Type	Required	Description
clientId	string	Yes	OAuth client identifier
clientSecret	string	No	OAuth client secret (optional with PKCE)
authorizationUrl	string	Yes	Authorization endpoint URL
tokenUrl	string	Yes	Token endpoint URL
redirectUrl	string	Yes	OAuth callback URL
scope	string	No	Space-separated OAuth scopes
usePKCE	boolean	No	Enable PKCE (recommended, default: true)

Authentication Types

The auth configuration supports three authentication types:

1. OAuth 2.1 (recommended for enterprise)

{
  "auth": {
    "type": "oauth2",
    "oauth": { ... }
  }
}

2. Bearer Token

{
  "auth": {
    "type": "bearer",
    "token": "your-access-token"
  }
}

3. API Key

{
  "auth": {
    "type": "api-key",
    "apiKey": "your-api-key",
    "apiKeyHeader": "X-API-Key"
  }
}

Transport Comparison

Feature	stdio	SSE	WebSocket	HTTP
Local servers	✅	❌	❌	❌
Remote servers	❌	✅	✅	✅
Authentication	Env vars	Headers	Headers	Headers
Streaming	✅	✅	✅	✅
Firewall friendly	✅	✅	⚠️	✅
Session management	❌	⚠️	⚠️	✅
Reconnection	❌	⚠️	⚠️	✅
Specification	MCP Core	MCP Core	MCP Core	MCP 2025

Configuration Options

Required Fields

• transport: Must be set to "http"
• url: The HTTP endpoint URL (e.g., https://api.example.com/mcp)
• command: Usually same as URL for HTTP transport

Optional Fields

• headers: Object with HTTP headers for authentication and configuration
• httpOptions: Fine-grained HTTP connection settings (see below)
• retryConfig: Automatic retry configuration with exponential backoff
• rateLimiting: Rate limiting to prevent API throttling
• auth: Authentication configuration (OAuth 2.1, Bearer, API Key)
• timeout: Connection timeout in milliseconds (default: 10000)
• retries: Maximum retry attempts (default: 3)
• autoRestart: Whether to automatically restart on failure (default: true)
• healthCheckInterval: Health check interval in milliseconds (default: 30000)

HTTP Options Configuration

Fine-tune HTTP connection behavior:

{
  httpOptions: {
    connectionTimeout: 30000,  // Connection timeout (ms), default: 30000
    requestTimeout: 60000,     // Request timeout (ms), default: 60000
    idleTimeout: 120000,       // Idle connection timeout (ms), default: 120000
    keepAliveTimeout: 30000    // Keep-alive timeout (ms), default: 30000
  }
}

Option	Type	Default	Description
connectionTimeout	number	30000	Maximum time to establish connection
requestTimeout	number	60000	Maximum time for request completion
idleTimeout	number	120000	Time before closing idle connections
keepAliveTimeout	number	30000	Keep-alive connection timeout

Retry Configuration

Automatic retry with exponential backoff:

{
  retryConfig: {
    maxAttempts: 3,           // Maximum retry attempts, default: 3
    initialDelay: 1000,       // Initial delay (ms), default: 1000
    maxDelay: 30000,          // Maximum delay (ms), default: 30000
    backoffMultiplier: 2      // Backoff multiplier, default: 2
  }
}

Option	Type	Default	Description
maxAttempts	number	3	Maximum number of retry attempts
initialDelay	number	1000	Initial delay before first retry
maxDelay	number	30000	Maximum delay between retries
backoffMultiplier	number	2	Multiplier for exponential backoff

Rate Limiting Configuration

Prevent API throttling with token bucket rate limiting:

{
  rateLimiting: {
    requestsPerMinute: 60,    // Max requests per minute, default: 60
    requestsPerHour: 1000,    // Max requests per hour (optional)
    maxBurst: 10,             // Max burst size, default: 10
    useTokenBucket: true      // Use token bucket algorithm, default: true
  }
}

Option	Type	Default	Description
requestsPerMinute	number	60	Maximum requests allowed per minute
requestsPerHour	number	-	Maximum requests allowed per hour
maxBurst	number	10	Maximum burst size for token bucket
useTokenBucket	boolean	true	Use token bucket algorithm

Example: Complete Configuration

{
  "mcpServers": {
    "custom-api": {
      "name": "custom-api",
      "command": "https://your-api.example.com/mcp",
      "transport": "http",
      "url": "https://your-api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_TOKEN",
        "X-Custom-Header": "value"
      },
      "httpOptions": {
        "connectionTimeout": 30000,
        "requestTimeout": 60000,
        "idleTimeout": 120000,
        "keepAliveTimeout": 30000
      },
      "retryConfig": {
        "maxAttempts": 5,
        "initialDelay": 1000,
        "maxDelay": 30000,
        "backoffMultiplier": 2
      },
      "rateLimiting": {
        "requestsPerMinute": 100,
        "maxBurst": 20,
        "useTokenBucket": true
      },
      "timeout": 15000,
      "autoRestart": true,
      "healthCheckInterval": 60000,
      "description": "Custom MCP API endpoint"
    }
  }
}

Use Cases

1. GitHub Copilot Integration

Access GitHub Copilot's AI capabilities through MCP:

const neurolink = new NeuroLink();

await neurolink.addInMemoryMCPServer("copilot", {
  server: { title: "GitHub Copilot", tools: {} },
  config: {
    id: "copilot",
    name: "copilot",
    description: "GitHub Copilot MCP",
    transport: "http",
    url: "https://api.githubcopilot.com/mcp",
    headers: { Authorization: "Bearer YOUR_TOKEN" },
    tools: [],
    status: "initializing",
  },
});

2. Enterprise API Gateway

Connect to internal MCP services behind API gateways:

{
  "internal-tools": {
    "transport": "http",
    "url": "https://internal-gateway.company.com/mcp",
    "headers": {
      "Authorization": "Bearer INTERNAL_TOKEN",
      "X-Tenant-ID": "tenant-123"
    }
  }
}

3. Multi-Cloud MCP Services

Connect to MCP services across different cloud providers:

{
  "aws-mcp": {
    "transport": "http",
    "url": "https://mcp.us-east-1.amazonaws.com/api",
    "headers": {
      "X-API-Key": "AWS_API_KEY"
    }
  },
  "azure-mcp": {
    "transport": "http",
    "url": "https://mcp.azure.com/api/v1",
    "headers": {
      "Ocp-Apim-Subscription-Key": "AZURE_KEY"
    }
  }
}

Troubleshooting

Connection Failed

Problem: Unable to connect to HTTP MCP server

Solutions:

1. Verify the URL is correct and accessible
2. Check authentication headers are valid
3. Ensure firewall/proxy allows HTTPS traffic
4. Test with curl first:

   curl -H "Authorization: Bearer TOKEN" https://api.example.com/mcp

Authentication Errors

Problem: 401 Unauthorized or 403 Forbidden

Solutions:

1. Verify token is valid and not expired
2. Check token has required permissions
3. Ensure header format matches API requirements
4. Try regenerating the authentication token

Timeout Issues

Problem: Connection times out

Solutions:

1. Increase timeout value in configuration
2. Check network connectivity
3. Verify the server is running and responsive
4. Test with a simple HTTP client first

Invalid Headers

Problem: Server rejects custom headers

Solutions:

1. Check header names follow HTTP specification
2. Ensure header values are properly formatted
3. Some headers may be reserved or blocked by proxies
4. Try different header names (e.g., X-API-Key instead of Api-Key)

Technical Details

Implementation

HTTP transport uses the StreamableHTTPClientTransport from the @modelcontextprotocol/sdk package, which implements:

• JSON-RPC 2.0 for message protocol
• Server-Sent Events (SSE) for streaming responses
• HTTP POST for sending requests
• Session management via Mcp-Session-Id header
• Automatic reconnection with exponential backoff

Security Considerations

1. HTTPS Required: Always use HTTPS in production
2. Token Security: Store tokens securely (environment variables, secrets management)
3. Header Sanitization: Avoid logging sensitive headers
4. Network Security: Use VPNs or private networks for internal APIs
5. Rate Limiting: Implement client-side rate limiting for public APIs

Migration Guide

From SSE to HTTP

If you're currently using SSE transport, migration is straightforward:

Before (SSE):

{
  "transport": "sse",
  "url": "http://localhost:8080/sse"
}

After (HTTP):

{
  "transport": "http",
  "url": "https://api.example.com/mcp",
  "headers": {
    "Authorization": "Bearer TOKEN"
  }
}

From stdio to HTTP

Migrating from local stdio servers to remote HTTP requires server changes:

1. Deploy your MCP server as an HTTP service
2. Implement authentication endpoint
3. Update client configuration to use HTTP transport
4. Add authentication headers

Resources

• MCP Specification - Transports
• GitHub Copilot MCP API Documentation
• NeuroLink MCP Integration Guide
• Example HTTP Transport Configurations:

{
  "mcpServers": {
    "github-copilot": {
      "name": "github-copilot",
      "transport": "http",
      "url": "https://api.githubcopilot.com/mcp",
      "headers": {
        "Authorization": "Bearer ${GITHUB_COPILOT_TOKEN}"
      },
      "httpOptions": {
        "connectionTimeout": 30000,
        "requestTimeout": 60000
      },
      "retryConfig": {
        "maxAttempts": 3,
        "initialDelay": 1000,
        "maxDelay": 30000
      },
      "rateLimiting": {
        "requestsPerMinute": 60,
        "maxBurst": 10
      },
      "description": "GitHub Copilot MCP API with full configuration"
    },
    "simple-http-server": {
      "name": "simple-http-server",
      "transport": "http",
      "url": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${API_TOKEN}"
      },
      "description": "Minimal HTTP transport configuration"
    },
    "enterprise-oauth-server": {
      "name": "enterprise-oauth-server",
      "transport": "http",
      "url": "https://api.enterprise.com/mcp",
      "auth": {
        "type": "oauth2",
        "oauth": {
          "clientId": "${OAUTH_CLIENT_ID}",
          "clientSecret": "${OAUTH_CLIENT_SECRET}",
          "authorizationUrl": "https://auth.enterprise.com/authorize",
          "tokenUrl": "https://auth.enterprise.com/token",
          "redirectUrl": "http://localhost:8080/callback",
          "scope": "mcp:read mcp:write tools:execute",
          "usePKCE": true
        }
      },
      "description": "Enterprise MCP server with OAuth 2.1 + PKCE"
    }
  }
}

Support

For issues or questions:

• GitHub Issues: juspay/neurolink/issues
• Documentation: NeuroLink Docs
• Examples: Basic Usage Examples