Transport Layer

The Model Context Protocol (MCP) supports different transport mechanisms for communication between hosts and clients. Kambrium implements HTTP transport with comprehensive security features and multi-tenant support.

​

HTTP Transport

Kambrium’s HTTP transport implementation provides:

• POST endpoints for standard JSON-RPC messages
• GET endpoints for Server-Sent Events (SSE) streaming
• Multi-tenant routing with /{tenant}/mcp paths
• Session management via Mcp-Session-Id headers
• Security compliance with CORS, rate limiting, and input validation

​

Endpoint Structure

/{tenant}/mcp

Where {tenant} is the path prefix identifying the specific MCP server instance.

​

HTTP Methods

​

POST - Standard Requests

Used for most MCP communication:

POST /{tenant}/mcp
Content-Type: application/json
Authorization: Bearer {token}

{
  "jsonrpc": "2.0",
  "method": "tools/list",
  "id": "req-1"
}

​

GET - Server-Sent Events

Used for streaming and long-lived connections:

GET /{tenant}/mcp
Accept: text/event-stream
Authorization: Bearer {token}

​

Headers

​

Required Headers

​

Optional Headers

​

Authentication

All HTTP requests require authentication:

​

OAuth 2.1 Bearer Tokens

Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

​

Personal Access Tokens (PAT)

Authorization: Bearer pat_development_user123_abcd1234...

​

Session Management

Sessions are managed via the Mcp-Session-Id header:

1. Initial Request: No session header required
2. Server Response: Returns Mcp-Session-Id header
3. Subsequent Requests: Include the session ID

# First request
POST /pipedrive/mcp
Authorization: Bearer {token}

# Server response includes
Mcp-Session-Id: sess_abc123

# Subsequent requests
POST /pipedrive/mcp
Authorization: Bearer {token}
Mcp-Session-Id: sess_abc123

​

Rate Limiting

HTTP transport includes advanced rate limiting:

• Per-endpoint limits: Different limits for MCP POST, GET, and health endpoints
• Burst control: Allows quick succession up to burst size
• Client identification: OAuth-aware rate limiting
• MCP-compliant errors: Proper JSON-RPC error responses

Rate limit headers in responses:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1609459200

​

CORS Support

The server includes comprehensive CORS support:

• Preflight handling: OPTIONS requests supported
• Origin validation: Configurable allowed origins
• Credential support: Access-Control-Allow-Credentials

​

Server-Sent Events (SSE)

For real-time communication and streaming:

const eventSource = new EventSource("/pipedrive/mcp", {
  headers: {
    Authorization: "Bearer " + token,
  },
});

eventSource.onmessage = function (event) {
  const data = JSON.parse(event.data);
  console.log("Received:", data);
};

​

Error Handling

HTTP transport provides proper error responses:

​

Authentication Errors

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32600,
    "message": "Invalid Request",
    "data": "Authentication required"
  },
  "id": null
}

​

Rate Limit Errors

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32000,
    "message": "Rate limit exceeded"
  },
  "id": "req-1"
}

​

Security Features

​

DNS Rebinding Protection

• Origin validation: Strict origin checking for browser requests
• Host header validation: Prevents DNS rebinding attacks
• Secure headers: Comprehensive security header configuration

​

Input Validation

• JSON schema validation: All requests validated against schemas
• Parameter sanitization: Input sanitization for security
• Size limits: Request size limits to prevent abuse

​

Connection Security

• TLS enforcement: HTTPS recommended for production
• Token validation: OAuth/PAT token verification
• Session isolation: Multi-tenant session separation

​

Usage Examples

​

Basic HTTP Client

import httpx
import asyncio

async def mcp_request():
    async with httpx.AsyncClient() as client:
        response = await client.post(
            "https://api.kambrium.com/pipedrive/mcp",
            headers={
                "Authorization": "Bearer your_token",
                "Content-Type": "application/json"
            },
            json={
                "jsonrpc": "2.0",
                "method": "tools/list",
                "id": "req-1"
            }
        )
        return response.json()

​

Session Management

async def mcp_session():
    headers = {
        "Authorization": "Bearer your_token",
        "Content-Type": "application/json"
    }

    # First request
    response = await client.post(url, headers=headers, json=request)
    session_id = response.headers.get("Mcp-Session-Id")

    # Subsequent requests with session
    if session_id:
        headers["Mcp-Session-Id"] = session_id

    response = await client.post(url, headers=headers, json=next_request)

​

Batch Requests

batch_request = [
    {"jsonrpc": "2.0", "method": "tools/list", "id": "1"},
    {"jsonrpc": "2.0", "method": "resources/list", "id": "2"},
    {"jsonrpc": "2.0", "method": "prompts/list", "id": "3"}
]

response = await client.post(url, headers=headers, json=batch_request)

​

Configuration

​

Environment Variables

# HTTP Transport Configuration
MCP_HOST=0.0.0.0
MCP_PORT=8000
MCP_ALLOWED_ORIGINS=["https://app.kambrium.com"]

# Rate Limiting
ENABLE_RATE_LIMITING=true
RATE_LIMIT_MCP_POST=60
RATE_LIMIT_MCP_GET=30
RATE_LIMIT_BURST_SIZE=10

# Security
SECRET_KEY=your-secret-key
JWT_SECRET_KEY=your-jwt-secret

​

Multi-Tenant Setup

Configure tenant routing in your database:

INSERT INTO mcp_servers (path_prefix, api_provider_id, config)
VALUES ('pipedrive', 1, '{"oauth_enabled": true}');

This creates a tenant accessible at /{path_prefix}/mcp.

​

Best Practices

1. Always use HTTPS in production environments
2. Implement proper authentication with OAuth or PAT tokens
3. Handle rate limits gracefully with exponential backoff
4. Use session management for multi-request workflows
5. Validate all inputs before sending requests
6. Monitor connection health with ping utilities

For detailed implementation examples, see the MCP Methods documentation.