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:

Verify the URL is correct and accessible
Check authentication headers are valid
Ensure firewall/proxy allows HTTPS traffic

Test with curl first:

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

Authentication Errors

Problem: 401 Unauthorized or 403 Forbidden

Solutions:

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

Timeout Issues

Problem: Connection times out

Solutions:

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

Invalid Headers

Problem: Server rejects custom headers

Solutions:

Check header names follow HTTP specification
Ensure header values are properly formatted
Some headers may be reserved or blocked by proxies
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

HTTPS Required: Always use HTTPS in production
Token Security: Store tokens securely (environment variables, secrets management)
Header Sanitization: Avoid logging sensitive headers
Network Security: Use VPNs or private networks for internal APIs
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:

Deploy your MCP server as an HTTP service
Implement authentication endpoint
Update client configuration to use HTTP transport
Add authentication headers

Resources

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

HTTP Transport for MCP Servers

Overview

Quick Start

GitHub Copilot Integration

Configuration File

Programmatic Usage

Authentication

Bearer Token Authentication

API Key Authentication

Custom Headers

OAuth 2.1 Authentication

Authentication Types

Transport Comparison

Configuration Options

Required Fields

Optional Fields

HTTP Options Configuration

Retry Configuration

Rate Limiting Configuration

Example: Complete Configuration

Use Cases

1. GitHub Copilot Integration

2. Enterprise API Gateway

3. Multi-Cloud MCP Services

Troubleshooting

Connection Failed

Authentication Errors

Timeout Issues

Invalid Headers

Technical Details

Implementation

Security Considerations

Migration Guide

From SSE to HTTP

From stdio to HTTP

Resources

Support

FilesExpand file tree

mcp-http-transport.md

Latest commit

History

mcp-http-transport.md

File metadata and controls

HTTP Transport for MCP Servers

Overview

Quick Start

GitHub Copilot Integration

Configuration File

Programmatic Usage

Authentication

Bearer Token Authentication

API Key Authentication

Custom Headers

OAuth 2.1 Authentication

Authentication Types

Transport Comparison

Configuration Options

Required Fields

Optional Fields

HTTP Options Configuration

Retry Configuration

Rate Limiting Configuration

Example: Complete Configuration

Use Cases

1. GitHub Copilot Integration

2. Enterprise API Gateway

3. Multi-Cloud MCP Services

Troubleshooting

Connection Failed

Authentication Errors

Timeout Issues

Invalid Headers

Technical Details

Implementation

Security Considerations

Migration Guide

From SSE to HTTP

From stdio to HTTP

Resources

Support