Protocol Utilities: Core MCP utilities for enhanced functionality

MCP provides several protocol utilities that enhance the core functionality with connection health monitoring, progress tracking, and request cancellation capabilities.

​
Available Utilities

Kambrium implements the following MCP protocol utilities:

  • Ping: Connection health monitoring and keep-alive functionality
  • Progress: Progress tracking for long-running operations
  • Cancellation: Request cancellation mechanism for async operations

​
Ping Utility

The ping utility provides connection health monitoring and keep-alive functionality.

​
Method: ping

Send a ping to check server connectivity and response time.

Request:

{
  "jsonrpc": "2.0",
  "method": "ping",
  "id": "ping-1"
}

Response:

{
  "jsonrpc": "2.0",
  "result": {
    "timestamp": "2024-01-15T10:30:00Z",
    "server_time": 1642248600,
    "response_time_ms": 12
  },
  "id": "ping-1"
}

​
Features

  • Rate Limiting: Maximum 10 pings per minute per client
  • Statistics: Response time tracking and connection statistics
  • Keep-Alive: Maintains connection health for long-lived sessions

​
Usage Example

# Send ping request
ping_request = {
    "jsonrpc": "2.0",
    "method": "ping",
    "id": "ping-1"
}

response = await client.post("/pipedrive/mcp", json=ping_request)
print(f"Server response time: {response['result']['response_time_ms']}ms")

​
Progress Tracking

The progress utility enables tracking of long-running operations with real-time updates.

​
Progress Notifications

For operations that take time to complete, the server can send progress notifications.

Progress Notification:

{
  "jsonrpc": "2.0",
  "method": "notifications/progress",
  "params": {
    "progress_token": "op-123",
    "progress": 0.5,
    "message": "Processing records: 500/1000"
  }
}

​
Parameters

ParameterTypeDescription
progress_tokenstringUnique identifier for the operation
progressnumberProgress value between 0.0 and 1.0
messagestringHuman-readable progress description

​
Features

  • Rate Limiting: Maximum 60 progress notifications per minute
  • Auto-Completion: Automatic cleanup when operations complete
  • Validation: Progress values validated between 0.0 and 1.0

​
Usage Example

# Long-running operation that sends progress
async def long_operation():
    total_items = 1000
    for i in range(total_items):
        # Process item
        await process_item(i)

        # Send progress notification
        if i % 100 == 0:  # Every 100 items
            progress = i / total_items
            await send_progress_notification(
                token="op-123",
                progress=progress,
                message=f"Processed {i}/{total_items} items"
            )

​
Request Cancellation

The cancellation utility allows clients to cancel long-running requests.

​
Method: notifications/cancelled

Send a cancellation notification for a pending request.

Notification:

{
  "jsonrpc": "2.0",
  "method": "notifications/cancelled",
  "params": {
    "request_id": "long-running-123"
  }
}

​
Parameters

ParameterTypeDescription
request_idstringID of the request to cancel

​
Features

  • Request Tracking: Tracks up to 1000 concurrent requests
  • Race Condition Handling: Prevents race conditions between completion and cancellation
  • Cleanup: Automatic cleanup of cancelled request data

​
Usage Example

# Start a long-running operation
operation_request = {
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
        "name": "long_running_tool",
        "arguments": {"data": "large_dataset"}
    },
    "id": "long-running-123"
}

# Send the request (non-blocking)
await client.post("/pipedrive/mcp", json=operation_request)

# Later, cancel if needed
cancel_notification = {
    "jsonrpc": "2.0",
    "method": "notifications/cancelled",
    "params": {
        "request_id": "long-running-123"
    }
}

await client.post("/pipedrive/mcp", json=cancel_notification)

​
Error Handling

​
Ping Errors

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32000,
    "message": "Ping rate limit exceeded"
  },
  "id": "ping-1"
}

​
Progress Errors

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32602,
    "message": "Invalid progress value: must be between 0.0 and 1.0"
  },
  "id": null
}

​
Cancellation Errors

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32601,
    "message": "Request not found for cancellation"
  },
  "id": null
}

​
Configuration

​
Environment Variables

# Ping Configuration
PING_ENABLED=true
PING_MAX_RATE=10  # pings per minute
PING_LOG_REQUESTS=false

# Progress Configuration
PROGRESS_ENABLED=true
PROGRESS_MAX_TRACKED_OPERATIONS=500
PROGRESS_MAX_NOTIFICATIONS_PER_MINUTE=60

# Cancellation Configuration
CANCELLATION_ENABLED=true
CANCELLATION_MAX_TRACKED_REQUESTS=1000

​
Usage Statistics

The utilities provide statistics for monitoring:

# Get utility statistics
stats = await get_utility_statistics()
print(stats)

# Example output:
{
  "ping": {
    "total_pings": 1250,
    "average_response_time_ms": 15,
    "rate_limited_requests": 5
  },
  "progress": {
    "active_operations": 3,
    "total_notifications_sent": 2400,
    "completed_operations": 127
  },
  "cancellation": {
    "tracked_requests": 15,
    "cancelled_requests": 2,
    "successful_cancellations": 2
  }
}

​
Best Practices

  1. Use ping sparingly - Implement exponential backoff for health checks
  2. Progress granularity - Send progress updates at reasonable intervals (not every item)
  3. Cancellation timeouts - Set reasonable timeouts for long-running operations
  4. Error handling - Always handle utility-specific error responses
  5. Resource cleanup - Utilities automatically clean up expired data

For more advanced protocol features, see the Error Handling documentation.