MCP-Cloud

https://mcp-cloud.ai/docs
Admin
MCP-Cloud is a platform for easily deploying and managing Model Context Protocol (MCP) servers,...
Tokens:15,918
Snippets:82
Trust Score:5.3
Update:1 year ago
Show doc for...
Tokens:
Raw
### Consume SSE Stream with EventSource API (JavaScript)

Source: https://mcp-cloud.ai/docs/sse-protocol/introduction

This example illustrates how to use the native browser `EventSource` API for a simpler way to consume SSE streams. It notes that this approach typically requires the MCP server to support GET requests for completions or a proxy. It demonstrates setting up `onmessage` to process incoming tokens and `onerror` for error handling, along with a function to close the connection.

```JavaScript
// Note: This approach requires your MCP server to support GET requests for completions
// or you'll need a proxy that converts POST to GET
const evtSource = new EventSource(
  'https://your-mcp-server.mcp-cloud.ai/v1/stream?prompt=Explain+quantum+computing',
  { withCredentials: true } // Include if you need to send cookies for auth
);

evtSource.onmessage = function(event) {
  const token = JSON.parse(event.data).choices[0].delta.content;
  document.getElementById('response').innerText += token;
};

evtSource.onerror = function(error) {
  console.error('EventSource error:', error);
  evtSource.close();
};

// Close the connection when done
function closeConnection() {
  evtSource.close();
}
```

--------------------------------

### Example Chat Completion Request (JavaScript)

Source: https://mcp-cloud.ai/docs/authentication/api-tokens

Illustrates how to send a chat completion request to an MCP server using JavaScript's `fetch` API. The example shows how to set headers, stringify the body, and handle the response, recommending storing the API key in an environment variable.

```JavaScript
async function callMCPServer(apiKey, prompt) {
  const response = await fetch('https://your-mcp-server.mcp-cloud.ai/v1/chat/completions', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${apiKey}`
    },
    body: JSON.stringify({
      model: 'claude-3-5-sonnet',
      messages: [{ role: 'user', content: prompt }]
    })
  });

  return response.json();
}

// Usage
const apiKey = process.env.MCP_API_KEY; // Store in environment variable
const result = await callMCPServer(apiKey, 'What is the capital of France?');
console.log(result.choices[0].message.content);
```

--------------------------------

### Example Chat Completion Request (Python)

Source: https://mcp-cloud.ai/docs/authentication/api-tokens

Provides a Python example for making a chat completion request to an MCP server using the `requests` library. It demonstrates setting headers, passing JSON data, and handling potential HTTP errors, advising to store the API key as an environment variable.

```Python
import requests

def call_mcp_server(api_key, prompt):
    url = "https://your-mcp-server.mcp-cloud.ai/v1/chat/completions"
    headers = {
        "Content-Type": "application/json",
        "Authorization": f"Bearer {api_key}"
    }
    data = {
        "model": "claude-3-5-sonnet",
        "messages": [{"role": "user", "content": prompt}]
    }

    response = requests.post(url, headers=headers, json=data)
    response.raise_for_status()  # Raise exception for 4xx/5xx errors

    return response.json()

# Usage (store API key in environment variable)
import os
api_key = os.environ.get("MCP_API_KEY")
result = call_mcp_server(api_key, "What is the capital of France?")
print(result["choices"][0]["message"]["content"])
```

--------------------------------

### Example SSE Flow Diagram

Source: https://mcp-cloud.ai/docs/sse-protocol

This diagram illustrates the typical Server-Sent Events (SSE) communication flow between a client and an MCP Server. It shows the initial HTTP GET request, the server's 'text/event-stream' response, and subsequent pushes of different event types (metrics, log, status) over the persistent connection.

```text
Client                                                MCP Server
  │                                                      │
  │  1. HTTP GET /api/servers/{id}/events                │
  │ ─────────────────────────────────────────────────────>
  │                                                      │
  │  2. HTTP 200 OK                                      │
  │  Content-Type: text/event-stream                     │
  │ <─────────────────────────────────────────────────────
  │                                                      │
  │  3. event: metrics                                   │
  │     data: {"cpu": 23, "memory": 128, "requests": 45} │
  │ <─────────────────────────────────────────────────────
  │                                                      │
  │  4. event: log                                       │
  │     data: {"level": "info", "msg": "Request processed"} │
  │ <─────────────────────────────────────────────────────
  │                                                      │
  │                  ... Connection remains open ...     │
  │                                                      │
  │  5. event: status                                    │
  │     data: {"status": "scaling", "instances": 2}      │
  │ <─────────────────────────────────────────────────────
  │                                                      │
```

--------------------------------

### MCP Server Template Selection

Source: https://mcp-cloud.ai/docs/mcp-servers/configuration

This section describes the pre-built templates available on MCP-Cloud, designed to quickly set up servers for specific tasks. Each template offers distinct functionalities and is suitable for various use cases, from web search to database connections.

```APIDOC
Template: Brave Search
  What It Does: Web search capabilities
  Use Cases: Research assistants, fact-checking
Template: Google Drive
  What It Does: Access files from Google Drive
  Use Cases: Document management, content analysis
Template: GitHub
  What It Does: Interact with GitHub repositories
  Use Cases: Code assistance, repository management
Template: PostgreSQL
  What It Does: Connect to databases
  Use Cases: Data analysis, database exploration
Template: AWS KB Retrieval
  What It Does: Connect to AWS Knowledge Bases
  Use Cases: Enterprise knowledge access
Template: Playwright
  What It Does: Web automation and screenshots
  Use Cases: Website testing, report generation
```

--------------------------------

### Create Context for Conversational AI Workflow

Source: https://mcp-cloud.ai/docs/integrations/n8n

This API documentation shows a POST request to the `/v1/contexts` endpoint to create a new conversation context. It includes an example `messages` array to initialize the context with system, user, and assistant roles.

```json
{
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Hello, who are you?"},
    {"role": "assistant", "content": "I'm an AI assistant powered by Claude. How can I help you today?"}
  ]
}
```

--------------------------------

### Common MCP Server Environment Variables

Source: https://mcp-cloud.ai/docs/mcp-servers/configuration

These environment variables are fundamental settings that work across most MCP server templates. They control technical aspects of server operation and typically do not require user modification.

```APIDOC
Setting: NODE_ENV
  Description: Technical setting for how the server runs
  Do I Need to Change This?: No - leave as default
Setting: LOG_LEVEL
  Description: Controls how much detail goes in server logs
  Do I Need to Change This?: No - leave as default
Setting: PORT
  Description: What network port the server uses
  Do I Need to Change This?: No - leave as default
```

--------------------------------

### Request Streaming Completion from MCP Server (JavaScript)

Source: https://mcp-cloud.ai/docs/sse-protocol/introduction

This JavaScript example demonstrates how to make a POST request to an MCP server for a streaming AI completion using the `fetch` API. It shows how to manually read and decode the SSE stream, process individual `data:` messages, handle the `[DONE]` signal, and parse the JSON payload to extract and display AI tokens as they arrive.

```JavaScript
// Request a streaming completion from your MCP server
async function getStreamingCompletion(prompt) {
  // First, prepare the request to your MCP server
  const response = await fetch('https://your-mcp-server.mcp-cloud.ai/v1/chat/completions', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer your_api_key'
    },
    body: JSON.stringify({
      model: 'claude-3-5-sonnet',
      messages: [{ role: 'user', content: prompt }],
      stream: true  // Request streaming response
    })
  });

  // Create a new EventSource from the response
  const reader = response.body.getReader();
  const decoder = new TextDecoder('utf-8');
  let buffer = '';

  // Process the stream
  while (true) {
    const { done, value } = await reader.read();
    if (done) break;

    // Decode the chunk and add to buffer
    buffer += decoder.decode(value, { stream: true });

    // Process complete SSE messages in the buffer
    const lines = buffer.split('\n\n');
    buffer = lines.pop() || '';  // Keep the incomplete chunk in the buffer

    for (const line of lines) {
      if (line.startsWith('data: ')) {
        const data = line.substring(6);

        // Check for [DONE] message
        if (data === '[DONE]') {
          console.log('Stream complete');
          continue;
        }

        try {
          // Parse the JSON data
          const jsonData = JSON.parse(data);

          // Extract the token content
          const token = jsonData.choices[0]?.delta?.content || '';

          // Do something with the token
          displayToken(token);
        } catch (error) {
          console.error('Error parsing SSE data:', error);
        }
      }
    }
  }
}

// Call the function
getStreamingCompletion('Explain quantum computing');
```

--------------------------------

### Example Chat Completion Request (cURL)

Source: https://mcp-cloud.ai/docs/authentication/api-tokens

Demonstrates how to make a chat completion request to an MCP server using cURL. It includes setting the content type, authorization header with the API key, and the request body with model and messages.

```cURL
curl -X POST \
  https://your-mcp-server.mcp-cloud.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer mcp_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -d '{
    "model": "claude-3-5-sonnet",
    "messages": [
      {"role": "user", "content": "What is the capital of France?"}
    ]
  }'
```

--------------------------------

### Template-Specific MCP Server API Keys and Environment Variables

Source: https://mcp-cloud.ai/docs/mcp-servers/configuration

This section details the specific API keys and environment variables required for different MCP server templates to connect to external services. It's crucial to mark sensitive information like API keys as "Secret" for security.

```APIDOC
Template: Default
  OPENAI_API_KEY: Your OpenAI API key (required)
  MODEL_NAME: Which AI model to use (optional, defaults to GPT-3.5)
Template: Brave Search
  BRAVE_API_KEY: Your Brave Search API key (required)
  COUNT: Number of search results to return (optional)
Template: Google Drive
  GOOGLE_CLIENT_ID: From Google Cloud Console (required)
  GOOGLE_CLIENT_SECRET: From Google Cloud Console (required)
  REFRESH_TOKEN: For Google authentication (required)
Template: GitHub
  GITHUB_TOKEN: Your GitHub personal access token (required)
Template: PostgreSQL
  POSTGRES_CONNECTION_STRING: Database connection information (required)
```

--------------------------------

### Browser JavaScript EventSource SSE Client

Source: https://mcp-cloud.ai/docs/sse-protocol/implementation

This client-side JavaScript example uses the `EventSource` API to consume SSE streams from MCP servers. It demonstrates how to establish a connection with authentication headers, listen for specific event types (metrics, logs, status), parse incoming JSON data, and handle connection errors. It also shows how to explicitly close the connection when no longer needed.

```JavaScript
// Create an EventSource with authentication
const eventSource = new EventSource('https://api.mcp-cloud.ai/api/servers/123/events', {
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN'
  }
});

// Listen for specific event types
eventSource.addEventListener('metrics', (event) => {
  const metrics = JSON.parse(event.data);
  console.log('Server metrics:', metrics);
  updateDashboard(metrics);
});

eventSource.addEventListener('log', (event) => {
  const log = JSON.parse(event.data);
  console.log('Server log:', log);
  appendToLogViewer(log);
});

eventSource.addEventListener('status', (event) => {
  const status = JSON.parse(event.data);
  console.log('Server status:', status);
  updateStatusIndicator(status);
});

// Handle connection errors
eventSource.onerror = (error) => {
  console.error('SSE connection error:', error);
  // Implement reconnection strategy if needed
};

// Close the connection when no longer needed
function closeConnection() {
  eventSource.close();
}

```

--------------------------------

### Implement Request Signing for MCP API Calls (Python)

Source: https://mcp-cloud.ai/docs/authentication/api-tokens

Provides a Python example demonstrating how to create a signed request for enhanced security, using HMAC-SHA256 with a timestamp and payload.

```python
import hmac
import hashlib
import time

def create_signature(api_key, payload, timestamp):
    message = f"{timestamp}.{payload}"
    signature = hmac.new(
        api_key.encode('utf-8'),
        message.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()
    return signature

def call_mcp_server_with_signature(api_key, prompt):
    url = "https://your-mcp-server.mcp-cloud.ai/v1/chat/completions"
    payload = json.dumps({
        "model": "claude-3-5-sonnet",
        "messages": [{"role": "user", "content": prompt}]
    })
    timestamp = int(time.time())
    signature = create_signature(api_key, payload, timestamp)

    headers = {
        "Content-Type": "application/json",
        "Authorization": f"Bearer {api_key}",
        "X-MCP-Timestamp": str(timestamp),
        "X-MCP-Signature": signature
    }

    response = requests.post(url, headers=headers, data=payload)
    return response.json()
```

--------------------------------

### API Key Authentication Header Example

Source: https://mcp-cloud.ai/docs/authentication/overview

This snippet demonstrates the format for an Authorization header when using API key authentication with an MCP server. It uses a Bearer token scheme where 'mcp_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' represents your actual API key.

```HTTP
Authorization: Bearer mcp_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

--------------------------------

### Register Event Listeners in JavaScript

Source: https://mcp-cloud.ai/docs/sse-protocol/best-practices

This function demonstrates how to register various event listeners on an `eventSource` object, including specific event types like 'deployment:started' and 'server:online', as well as a generic 'onmessage' handler for uncategorized events. It parses incoming event data as JSON.

```javascript
function registerEventHandlers(eventSource) {
  // Listen for specific events
  eventSource.addEventListener('deployment:started', handleDeploymentStarted);
  eventSource.addEventListener('server:online', handleServerOnline);
  eventSource.addEventListener('metrics:cpu', handleCpuMetrics);

  // Generic message handler for uncategorized events
  eventSource.onmessage = (event) => {
    const data = JSON.parse(event.data);
    console.log('Received uncategorized event:', data);
  };
}
```

--------------------------------

### Example API Key Error Response

Source: https://mcp-cloud.ai/docs/authentication/api-tokens

Shows a typical JSON error response structure received when an API key-related issue occurs, such as an invalid or revoked key.

```json
{
  "error": {
    "code": "invalid_api_key",
    "message": "The API key provided is invalid or has been revoked",
    "type": "authentication_error"
  }
}
```

--------------------------------

### Make Authenticated API Request with cURL and API Key

Source: https://mcp-cloud.ai/docs/authentication/client-auth

An example cURL command demonstrating how to send a POST request to an MCP server's chat completions endpoint. It includes the API key in the Authorization header and a JSON payload, illustrating a typical authenticated API call.

```bash
curl -X POST \
  https://your-mcp-server.mcp-cloud.ai/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer mcp_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
  -d '{
    "model": "claude-3-5-sonnet",
    "messages": [{"role": "user", "content": "Hello, how are you?"}]
  }'
```

--------------------------------

### MCP Server Memory Resource Configuration

Source: https://mcp-cloud.ai/docs/mcp-servers/configuration

Memory settings determine how much information your MCP server can process concurrently. Choose an option based on the complexity and volume of operations your server will handle.

```APIDOC
Memory: 512 MB
  When to Choose: Basic use, limited needs
Memory: 1024 MB
  When to Choose: Standard option - good for most users
Memory: 2048 MB
  When to Choose: Heavy usage or complex operations
Memory: 4096 MB
  When to Choose: Professional/enterprise needs
```

--------------------------------

### Subscribe to Event Types via SSE Connection URL

Source: https://mcp-cloud.ai/docs/sse-protocol/event-types

Clients can subscribe to specific event types by specifying query parameters in the SSE connection URL. This example demonstrates how to use exact match (`metrics:cpu`), wildcard category (`metrics:*`), and wildcard all (`*`) patterns for event subscription.

```HTTP
GET /api/servers/:id/events?types=metrics:cpu,metrics:memory,alert:*
```

--------------------------------

### Make Authenticated API Request with JWT Token

Source: https://mcp-cloud.ai/docs/authentication/client-auth

Examples demonstrating how to send an HTTP request to an MCP server, including the JWT token in the Authorization header, using both cURL for command-line interactions and JavaScript Fetch for client-side applications.

```bash
curl -H "Authorization: Bearer YOUR_JWT_TOKEN" https://your-server-url.run.app/sse
```

```javascript
fetch('https://your-server-url.run.app/sse', {
  headers: {
    'Authorization': 'Bearer YOUR_JWT_TOKEN'
  }
})
```

--------------------------------

### Node.js Express.js SSE Server Implementation

Source: https://mcp-cloud.ai/docs/sse-protocol/implementation

A simplified Node.js Express.js example demonstrating an MCP server-side SSE endpoint. It sets necessary HTTP headers, sends an initial comment to initialize the connection, and continuously streams metrics and logs to connected clients using `setInterval` and an event emitter. It also includes logic to handle client disconnection gracefully.

```Node.js
// Express.js route handler for SSE
app.get('/api/servers/:id/events', authenticate, async (req, res) => {
  const serverId = req.params.id;

  // Set headers for SSE
  res.writeHead(200, {
    'Content-Type': 'text/event-stream',
    'Cache-Control': 'no-cache',
    'Connection': 'keep-alive',
    'X-Accel-Buffering': 'no'
  });

  // Send a comment to initialize the connection
  res.write(':\n\n');

  // Function to send events
  const sendEvent = (eventType, data, id = Date.now()) => {
    res.write(`event: ${eventType}\n`);
    res.write(`id: ${id}\n`);
    res.write(`data: ${JSON.stringify(data)}\n\n`);
  };

  // Send initial status event
  const server = await getServerStatus(serverId);
  sendEvent('status', server);

  // Set up event listeners for this server
  const metricsInterval = setInterval(async () => {
    const metrics = await getServerMetrics(serverId);
    sendEvent('metrics', metrics);
  }, 5000);

  // Log event listener
  const logListener = (log) => {
    if (log.serverId === serverId) {
      sendEvent('log', log);
    }
  };

  // Register log listener with the event emitter
  eventEmitter.on('serverLog', logListener);

  // Handle client disconnect
  req.on('close', () => {
    clearInterval(metricsInterval);
    eventEmitter.off('serverLog', logListener);
    console.log('SSE connection closed');
  });
});

```

--------------------------------

### Call MCP Cloud AI Chat Completions API

Source: https://mcp-cloud.ai/docs/authentication/client-auth

Provides examples in Python and Node.js for interacting with the MCP Cloud AI chat completions API. Both snippets show how to construct a POST request with the necessary headers (Content-Type, Authorization) and body (model, messages) to send a prompt and receive a response.

```python
import requests

def call_mcp_server(api_key, prompt):
    url = "https://your-mcp-server.mcp-cloud.ai/v1/chat/completions"
    headers = {
        "Content-Type": "application/json",
        "Authorization": f"Bearer {api_key}"
    }
    data = {
        "model": "claude-3-5-sonnet",
        "messages": [{"role": "user", "content": prompt}]
    }

    response = requests.post(url, headers=headers, json=data)
    response.raise_for_status()  # Raise exception for 4xx/5xx errors

    return response.json()

# Usage
api_key = "mcp_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"  # Better to use environment variables
result = call_mcp_server(api_key, "What is the capital of France?")
print(result['choices'][0]['message']['content'])
```

```javascript
const axios = require('axios');

async function callMCPServer(apiKey, prompt) {
  try {
    const response = await axios.post(
      'https://your-mcp-server.mcp-cloud.ai/v1/chat/completions',
      {
        model: "claude-3-5-sonnet",
        messages: [{ role: "user", content: prompt }]
      },
      {
        headers: {
          'Content-Type': 'application/json',
          'Authorization': `Bearer ${apiKey}`
        }
      }
    );

    return response.data;
  } catch (error) {
    if (error.response) {
      console.error('Error response:', error.response.status, error.response.data);
    }
    throw error;
  }
}

// Usage
const apiKey = process.env.MCP_API_KEY;
callMCPServer(apiKey, "What is the capital of France?")
  .then(result => console.log(result.choices[0].message.content))
  .catch(error => console.error('Error:', error));
```

--------------------------------

### Test MCP Server Connectivity and API Access with cURL

Source: https://mcp-cloud.ai/docs/mcp-servers/troubleshooting

This snippet demonstrates how to test network connectivity to an MCP server and verify authenticated API access using `curl`. It includes examples for a basic health check and an API call to the models endpoint, which are useful for diagnosing network and authentication issues.

```Shell
# Test basic connectivity
curl -I https://your-server-url.mcp-cloud.ai/health

# Test with authentication
curl -I -H "Authorization: Bearer YOUR_API_KEY" \
  https://your-server-url.mcp-cloud.ai/v1/models
```

--------------------------------

### Implement Error Handling in n8n Workflows

Source: https://mcp-cloud.ai/docs/integrations/n8n

This JavaScript snippet, designed for an n8n Error Catcher node, illustrates how to check for and handle errors from previous nodes. It provides a basic example of logging or taking alternative actions based on the error message.

```javascript
// Error Catcher node
if ($node['MCP Server Request'].error) {
  // Log error or take alternate action
  return [{ error: $node['MCP Server Request'].error.message }];
}
```

--------------------------------

### MCP Server CPU Resource Configuration

Source: https://mcp-cloud.ai/docs/mcp-servers/configuration

CPU core settings impact the processing speed of your MCP server. More cores enable faster execution of tasks, suitable for high-demand scenarios.

```APIDOC
CPU Cores: 1
  When to Choose: Standard for most uses
CPU Cores: 2
  When to Choose: When faster response is needed
CPU Cores: 4+
  When to Choose: High-volume professional use
```

--------------------------------

### MCP-Cloud Prometheus Metrics Export API Reference

Source: https://mcp-cloud.ai/docs/mcp-servers/monitoring

Documents the API endpoint for exporting MCP server metrics in a Prometheus-compatible format. It details the GET endpoint, the basic authentication requirements (username 'prometheus' and an API token), and notes that the metrics are exposed in the standard Prometheus exposition format.

```APIDOC
Endpoint: GET https://{your-server-id}.metrics.mcp-cloud.ai/metrics
Authentication: Basic Auth (username: 'prometheus', password: 'YOUR_API_TOKEN')
Metrics Format: Prometheus exposition format
```

--------------------------------

### Handle SSE Reconnection with Exponential Backoff in JavaScript

Source: https://mcp-cloud.ai/docs/sse-protocol/best-practices

This function sets up an EventSource connection with robust automatic reconnection logic. It implements exponential backoff for retries, starting at 1 second and doubling up to a maximum of 30 seconds, with a limit of 5 reconnection attempts. It logs connection status and errors.

```javascript
function setupEventSourceWithReconnection(serverId, token) {
  let reconnectAttempts = 0;
  const maxReconnectAttempts = 5;
  let reconnectTimeout = 1000; // Start with 1 second

  function connect() {
    const eventSource = connectToEventSource(serverId, token);

    eventSource.onopen = () => {
      reconnectAttempts = 0;
      reconnectTimeout = 1000;
      console.log('Connected to event stream');
    };

    eventSource.onerror = (error) => {
      eventSource.close();

      if (reconnectAttempts < maxReconnectAttempts) {
        reconnectAttempts++;
        console.log(`Connection error, reconnecting (${reconnectAttempts}/${maxReconnectAttempts})...`);
        setTimeout(connect, reconnectTimeout);
        reconnectTimeout = Math.min(reconnectTimeout * 2, 30000); // Exponential backoff, max 30 seconds
      } else {
        console.error('Maximum reconnection attempts reached');
        // Notify user or trigger manual reconnect
      }
    };

    return eventSource;
  }

  return connect();
}
```

--------------------------------

### MCP-Cloud SSE Metrics Stream API Reference

Source: https://mcp-cloud.ai/docs/mcp-servers/monitoring

Defines the Server-Sent Events (SSE) API endpoint for real-time streaming of MCP server performance metrics. It specifies the GET endpoint, required Bearer token authentication, the 'metrics' event type, and the structure of the JSON data payload for each event.

```APIDOC
Endpoint: GET https://api.mcp-cloud.ai/api/servers/{server_id}/metrics/stream
Authentication: Bearer Token in 'Authorization' header
Event Type: 'metrics'
Event Data (JSON):
  cpu: number (Current CPU usage percentage)
  memory: number (Current memory usage in MB)
  requestRate: number (Requests in last minute)
```

--------------------------------

### Node.js SSE Client with Custom Reconnection Logic

Source: https://mcp-cloud.ai/docs/sse-protocol/implementation

This snippet provides an example of implementing custom reconnection logic for a Node.js SSE client. It uses an exponential backoff strategy to manage reconnection attempts after a connection error, preventing overwhelming the server and ensuring resilient event stream consumption.

```JavaScript
let reconnectAttempts = 0;
const maxReconnectAttempts = 5;
const baseReconnectDelay = 1000; // 1 second

function connectSSE() {
  const eventSource = new EventSource('https://api.mcp-cloud.ai/api/servers/123/events', {
    headers: { 'Authorization': 'Bearer YOUR_API_TOKEN' }
  });

  eventSource.onopen = () => {
    console.log('SSE connection established');
    reconnectAttempts = 0;
  };

  eventSource.onerror = (error) => {
    console.error('SSE connection error:', error);
    eventSource.close();

    if (reconnectAttempts < maxReconnectAttempts) {
      reconnectAttempts++;
      const delay = baseReconnectDelay * Math.pow(2, reconnectAttempts - 1);
      console.log(`Reconnecting in ${delay}ms (attempt ${reconnectAttempts})`);

      setTimeout(connectSSE, delay);
    } else {
      console.error('Maximum reconnection attempts reached');
    }
  };

  return eventSource;
}

const eventSource = connectSSE();
```

--------------------------------

### Optimize Prompt Construction for Token Usage

Source: https://mcp-cloud.ai/docs/integrations/n8n

This JavaScript snippet shows a best practice for optimizing token usage by constructing concise and effective prompts. It demonstrates embedding input text directly into a clear instruction for summarization.

```javascript
// More efficient prompt construction
const prompt = `Summarize the following text in 3 bullet points:
${$node['Input Text'].json.text}`;
```

--------------------------------

### Establish SSE Connection in JavaScript

Source: https://mcp-cloud.ai/docs/sse-protocol/best-practices

This function establishes a new Server-Sent Events connection to a specified server ID. It constructs the URL using the server ID and includes an authentication token as a query parameter.

```javascript
function connectToEventSource(serverId, token) {
  const url = `/api/servers/${serverId}/events`;
  const eventSource = new EventSource(`${url}?auth=${token}`);
  return eventSource;
}
```

--------------------------------

### Node.js SSE Client Basic Implementation

Source: https://mcp-cloud.ai/docs/sse-protocol/implementation

This snippet demonstrates how to set up a basic Server-Sent Events (SSE) client in Node.js using the `eventsource` package. It covers creating an EventSource instance with authentication headers, listening for general messages, specific event types like 'metrics', and handling connection errors. It also shows how to close the connection.

```JavaScript
const EventSource = require('eventsource');

// Create options with headers for authentication
const options = {
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN'
  }
};

// Create EventSource instance
const eventSource = new EventSource('https://api.mcp-cloud.ai/api/servers/123/events', options);

// Listen for events
eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log(`Received data: ${data}`);
};

// Listen for specific event types
eventSource.addEventListener('metrics', (event) => {
  const metrics = JSON.parse(event.data);
  console.log('Server metrics:', metrics);
});

// Handle errors
eventSource.onerror = (error) => {
  console.error('SSE Error:', error);
  eventSource.close();
};

// Close the connection when done
function cleanup() {
  eventSource.close();
}
```

--------------------------------

### MCP Server Request Timeout Configuration

Source: https://mcp-cloud.ai/docs/mcp-servers/configuration

The request timeout setting defines how long your MCP server will wait for an operation to complete. Adjust this based on the expected duration of tasks, especially for complex or lengthy operations.

```APIDOC
Timeout: 30 sec
  When to Choose: Quick operations
Timeout: 60 sec
  When to Choose: Standard setting for most uses
Timeout: 120+ sec
  When to Choose: For lengthy operations like complex web searches
```

--------------------------------

### React Component for Real-time Server Monitoring with SSE

Source: https://mcp-cloud.ai/docs/sse-protocol/best-practices

This React component demonstrates how to establish and manage a Server-Sent Events (SSE) connection to monitor server status, metrics (CPU, memory, network), and application logs in real-time. It uses `useState` and `useEffect` hooks to manage component state and lifecycle, `EventSource` for SSE, and includes event listeners for different data types. It also handles connection cleanup on unmount.

```JavaScript
import { useState, useEffect, useRef } from 'react';

function ServerMonitor({ serverId, authToken }) {
  const [serverStatus, setServerStatus] = useState('unknown');
  const [metrics, setMetrics] = useState({ cpu: 0, memory: 0, network: 0 });
  const [logs, setLogs] = useState([]);
  const eventSourceRef = useRef(null);

  useEffect(() => {
    // Set up event source
    const url = `/api/servers/${serverId}/events?types=server:*,metrics:*,logs:*`;
    const eventSource = new EventSource(`${url}?auth=${authToken}`);
    eventSourceRef.current = eventSource;

    // Server status events
    eventSource.addEventListener('server:online', (event) => {
      const data = JSON.parse(event.data);
      setServerStatus('online');
    });

    eventSource.addEventListener('server:offline', (event) => {
      const data = JSON.parse(event.data);
      setServerStatus('offline');
    });

    // Metrics events (throttled to max 1 update per second)
    let metricsUpdateTimeout = null;
    const handleMetricsEvent = (event) => {
      const data = JSON.parse(event.data);

      setMetrics(prevMetrics => {
        // Update just the specific metric that changed
        return { ...prevMetrics, [data.type]: data.value };
      });
    };

    eventSource.addEventListener('metrics:cpu', handleMetricsEvent);
    eventSource.addEventListener('metrics:memory', handleMetricsEvent);
    eventSource.addEventListener('metrics:network', handleMetricsEvent);

    // Log events
    eventSource.addEventListener('logs:app', (event) => {
      const data = JSON.parse(event.data);
      setLogs(prevLogs => [...prevLogs.slice(-99), data].sort((a, b) =>
        new Date(b.timestamp) - new Date(a.timestamp)
      ));
    });

    // Generic error handler
    eventSource.onerror = (error) => {
      console.error('EventSource error:', error);
      // Implement reconnection logic here
    };

    // Clean up on unmount
    return () => {
      if (eventSourceRef.current) {
        eventSourceRef.current.close();
        eventSourceRef.current = null;
      }
    };
  }, [serverId, authToken]);

  return (
    <div className="server-monitor">
      <h2>Server Status: {serverStatus}</h2>

      <div className="metrics">
        <div className="metric">
          <h3>CPU Usage</h3>
          <div className="meter">
            <div className="meter-fill" style={{ width: `${metrics.cpu}%` }}></div>
          </div>
          <span>{metrics.cpu}%</span>
        </div>
        {/* Similar components for memory and network */}
      </div>

      <div className="logs">
        <h3>Recent Logs</h3>
        <ul>
          {logs.map((log, i) => (
            <li key={i} className={`log-level-${log.level}`}>
              <span className="timestamp">{new Date(log.timestamp).toLocaleTimeString()}</span>
              <span className="message">{log.message}</span>
            </li>
          ))}
        </ul>
      </div>
    </div>
  );
}
```

--------------------------------

### Python SSE Client Basic Implementation

Source: https://mcp-cloud.ai/docs/sse-protocol/implementation

This snippet illustrates how to create a Server-Sent Events (SSE) client in Python using the `sseclient` and `requests` libraries. It shows how to establish a session with authentication, connect to the SSE endpoint, and iterate through received events, processing different event types like 'metrics', 'log', and 'status'.

```Python
import json
import sseclient
import requests

# Create a session with authentication
session = requests.Session()
session.headers.update({
    'Authorization': 'Bearer YOUR_API_TOKEN'
})

# Connect to SSE endpoint
response = session.get('https://api.mcp-cloud.ai/api/servers/123/events', stream=True)
client = sseclient.SSEClient(response);

# Process events
for event in client:
    if event.event == 'metrics':
        metrics = json.loads(event.data)
        print(f"Server metrics: {metrics}")
    elif event.event == 'log':
        log = json.loads(event.data)
        print(f"Server log: {log}")
    elif event.event == 'status':
        status = json.loads(event.data)
        print(f"Server status: {status}")
```

--------------------------------

### OAuth 2.0 Authorization Flow Diagram

Source: https://mcp-cloud.ai/docs/authentication/overview

A visual representation of the OAuth 2.0 authorization process, outlining 15 distinct steps from user interaction to API access, involving the User, Your App, and the MCP Server.

```Diagram
┌─────────────┐       ┌─────────────┐       ┌─────────────┐
│             │       │             │       │             │
│    User     │       │  Your App   │       │ MCP Server  │
│             │       │             │       │             │
└──────┬──────┘       └──────┬──────┘       └──────┬──────┘
       │                     │                     │
       │                     │  1. Register App    │
       │                     │ ──────────────────► │
       │                     │                     │
       │                     │  2. Client ID/Secret│
       │                     │ ◄─────────────────  │
       │                     │                     │
       │  3. Access App      │                     │
       │ ──────────────────► │                     │
       │                     │                     │
       │  4. Redirect to OAuth                     │
       │ ◄────────────────── │                     │
       │                     │                     │
       │  5. Auth Request    │                     │
       │ ─────────────────────────────────────────►│
       │                     │                     │
       │  6. Auth Consent    │                     │
       │ ◄─────────────────────────────────────────│
       │                     │                     │
       │  7. Approve         │                     │
       │ ─────────────────────────────────────────►│
       │                     │                     │
       │  8. Redirect with Code                    │
       │ ◄─────────────────────────────────────────│
       │                     │                     │
       │  9. Code            │                     │
       │ ──────────────────► │                     │
       │                     │                     │
       │                     │  10. Exchange Code  │
       │                     │ ──────────────────► │
       │                     │                     │
       │                     │  11. Access Token   │
       │                     │ ◄─────────────────  │
       │                     │                     │
       │  12. API Access     │                     │
       │ ──────────────────► │                     │
       │                     │                     │
       │                     │  13. API Request    │
       │                     │ ──────────────────► │
       │                     │                     │
       │                     │  14. Response       │
       │                     │ ◄─────────────────  │
       │                     │                     │
       │  15. Results        │                     │
       │ ◄────────────────── │                     │
       │                     │                     │
```

--------------------------------

### n8n Function Node: Prepare Input for MCP Server

Source: https://mcp-cloud.ai/docs/integrations/n8n

This JavaScript code for an n8n Function node transforms input data into a structured prompt suitable for the MCP server. It dynamically constructs a prompt string using variables from other n8n nodes (Topic Input, Style Input, Format Input).

```javascript
// Transform the input for the MCP server
return [
  {
    prompt: `Generate a blog post about ${$node['Topic Input'].json.topic}.
                Use a ${$node['Style Input'].json.tone} tone and include
                ${$node['Format Input'].json.sections} sections.`
  }
];
```

--------------------------------

### Implementing EventSource Polyfill for Browser Compatibility

Source: https://mcp-cloud.ai/docs/sse-protocol/best-practices

This snippet shows how to conditionally use an `eventsource-polyfill` to ensure Server-Sent Events (SSE) functionality in older browsers that lack native `EventSource` support. It checks for `window.EventSource` and falls back to the polyfill if necessary, providing broader compatibility.

```JavaScript
import EventSourcePolyfill from 'eventsource-polyfill';

// Use the polyfill if needed
const EventSourceImpl = window.EventSource || EventSourcePolyfill;

const eventSource = new EventSourceImpl(url, options);
```

--------------------------------

### Consume SSE Chat Completions with Python

Source: https://mcp-cloud.ai/docs/sse-protocol/introduction

This Python function demonstrates how to make a streaming request to an MCP server's chat completions endpoint using the `requests` library. It processes the Server-Sent Events (SSE) response, extracts content tokens, and handles the stream's end, including basic JSON parsing and error handling for malformed data.

```Python
import requests
import json

def stream_completion(prompt):
    # Set up the request to your MCP server
    url = "https://your-mcp-server.mcp-cloud.ai/v1/chat/completions"
    headers = {
        "Content-Type": "application/json",
        "Authorization": "Bearer your_api_key"
    }
    data = {
        "model": "claude-3-5-sonnet",
        "messages": [{"role": "user", "content": prompt}],
        "stream": True
    }

    # Make the request and process the streaming response
    response = requests.post(url, headers=headers, json=data, stream=True)

    # Ensure the request was successful
    response.raise_for_status()

    # Process the streaming response
    for line in response.iter_lines():
        if line:
            # Lines start with "data: "
            line = line.decode('utf-8')
            if line.startswith('data: '):
                data_str = line[6:]  # Remove 'data: ' prefix

                # Check for stream end
                if data_str == '[DONE]':
                    break

                try:
                    # Parse the JSON data
                    data = json.loads(data_str)

                    # Extract token content
                    token = data['choices'][0]['delta'].get('content', '')

                    # Do something with the token
                    print(token, end='', flush=True)
                except json.JSONDecodeError:
                    print(f"Error parsing JSON: {data_str}")

# Use the function
stream_completion("Explain quantum computing")
```

--------------------------------

### Session-Based Authentication Flow Diagram

Source: https://mcp-cloud.ai/docs/authentication/overview

This diagram details a multi-step session-based authentication process involving a user, an intermediary application, and the MCP Server. It covers user login, application-level authentication, session creation with the MCP Server, token exchange, and subsequent requests using the obtained session token.

```APIDOC
┌─────────────┐       ┌─────────────┐       ┌─────────────┐
│             │       │             │       │             │
│    User     │       │  Your App   │       │ MCP Server  │
│             │       │             │       │             │
└──────┬──────┘       └──────┬──────┘       └──────┬──────┘
       │                     │                     │
       │  1. Login           │                     │
       │ ──────────────────► │                     │
       │                     │                     │
       │  2. App auth        │                     │
       │ ◄────────────────── │                     │
       │                     │                     │
       │                     │  3. Create Session  │
       │                     │ ──────────────────► │
       │                     │                     │
       │                     │  4. Session Token   │
       │                     │ ◄─────────────────  │
       │                     │                     │
       │  5. Session Token   │                     │
       │ ◄────────────────── │                     │
       │                     │                     │
       │                     │                     │
       │  6. Request with Session Token            │
       │ ─────────────────────────────────────────►│
       │                     │                     │
       │  7. Response        │                     │
       │ ◄─────────────────────────────────────────│
       │                     │                     │
```

--------------------------------

### Test Server-Sent Events (SSE) Connection with cURL

Source: https://mcp-cloud.ai/docs/sse-protocol/implementation

This cURL command demonstrates how to establish and test a Server-Sent Events (SSE) connection to a specified API endpoint. The -N flag disables output buffering, ensuring events are received as they occur. An Authorization header with a bearer token is included for authentication. Remember to replace 'YOUR_API_TOKEN' with your actual API key.

```Shell
curl -N -H "Authorization: Bearer YOUR_API_TOKEN" https://api.mcp-cloud.ai/api/servers/123/events
```

--------------------------------

### Send User Message to MCP Server with Context

Source: https://mcp-cloud.ai/docs/integrations/n8n

This API documentation illustrates a POST request to the `/v1/chat/completions` endpoint, demonstrating how to send a user message to the MCP server while referencing an existing `context_id`. It specifies the model and includes the user's message.

```json
{
  "model": "claude-3-5-sonnet",
  "context_id": "{{$node['Create Context'].json.context_id}}",
  "messages": [
    {"role": "user", "content": "{{$node['User Input'].json.message}}"}
  ]
}
```

--------------------------------

### Call MCP Server with OAuth Access Token (JavaScript)

Source: https://mcp-cloud.ai/docs/authentication/client-auth

Demonstrates how to use an obtained OAuth access token to authenticate API requests to the MCP server, such as calling the chat completions endpoint.

```JavaScript
async function callMCPServerWithOAuth(accessToken, prompt) {
  const response = await fetch('https://your-mcp-server.mcp-cloud.ai/v1/chat/completions', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${accessToken}`
    },
    body: JSON.stringify({
      model: "claude-3-5-sonnet",
      messages: [{ role: "user", content: prompt }]
    })
  });

  return response.json();
}
```

--------------------------------

### Java Client for MCP Cloud AI Chat Completions

Source: https://mcp-cloud.ai/docs/authentication/client-auth

This Java class provides a client to interact with the MCP Cloud AI server's chat completion API. It handles API key authentication, constructs HTTP requests with a specified model (e.g., claude-3-5-sonnet), and processes responses, including basic error handling. It demonstrates how to send a prompt and retrieve the completion.

```Java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class MCPServerClient {
    private final String apiKey;
    private final String serverUrl;
    private final HttpClient httpClient;

    public MCPServerClient(String apiKey, String serverUrl) {
        this.apiKey = apiKey;
        this.serverUrl = serverUrl;
        this.httpClient = HttpClient.newHttpClient();
    }

    public String callCompletion(String prompt) throws Exception {
        String requestBody = String.format("""
            {
                "model": "claude-3-5-sonnet",
                "messages": [{"role": "user", "content": "%s"}]
            }
            """, prompt);

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(serverUrl + "/v1/chat/completions"))
            .header("Content-Type", "application/json")
            .header("Authorization", "Bearer " + apiKey)
            .POST(HttpRequest.BodyPublishers.ofString(requestBody))
            .build();

        HttpResponse<String> response = httpClient.send(request,
            HttpResponse.BodyHandlers.ofString());

        if (response.statusCode() >= 400) {
            throw new RuntimeException("API error: " + response.statusCode() +
                " " + response.body());
        }

        return response.body();
    }

    public static void main(String[] args) {
        try {
            String apiKey = System.getenv("MCP_API_KEY");
            MCPServerClient client = new MCPServerClient(
                apiKey,
                "https://your-mcp-server.mcp-cloud.ai"
            );

            String result = client.callCompletion("What is the capital of France?");
            System.out.println(result);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}
```

--------------------------------

### Set and Access API Key via Environment Variable in Shell

Source: https://mcp-cloud.ai/docs/authentication/client-auth

Shows how to set an API key as an environment variable in a shell session and how an application (e.g., Node.js) would typically access it. This method is crucial for secure API key management in development and production environments.

```bash
# Set environment variable
export MCP_API_KEY=mcp_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Use in application
node app.js
```

--------------------------------

### Call MCP Server with Session Token (JavaScript)

Source: https://mcp-cloud.ai/docs/authentication/client-auth

Illustrates how to use a previously obtained session token to authenticate client-side requests to the MCP server's API, such as chat completions.

```JavaScript
async function callMCPServerWithSession(sessionToken, prompt) {
  const response = await fetch('https://your-mcp-server.mcp-cloud.ai/v1/chat/completions', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer ' + sessionToken
    },
    body: JSON.stringify({
      model: "claude-3-5-sonnet",
      messages: [{ role: "user", content: prompt }]
    })
  });

  return response.json();
}
```
Tokens:
Raw