Gateway Endpoints & MCP Protocol

This guide explains how to interact with your Storm MCP Gateway endpoints directly using the Model Context Protocol (MCP).

ℹ️ Info

Important: Gateway endpoints are different from the Storm MCP management API. This guide covers the gateway endpoints that execute MCP tools, not the API for managing gateways.

Gateway Endpoint Format

Once you create a gateway, it's accessible at:

https://stormmcp.ai/gateway/{gateway-id}/mcp

For development environment:

https://dev.stormmcp.ai/gateway/{gateway-id}/mcp

Authentication

⚠️ Warning

Critical: Gateway endpoints use X-API-Key header, NOT Authorization: Bearer

Correct Authentication

# ✅ CORRECT - Use X-API-Key header
curl -X POST https://stormmcp.ai/gateway/{gateway-id}/mcp \
  -H "X-API-Key: ag_YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json"

Common Mistake

# ❌ WRONG - This will return 401 Unauthorized
curl -X POST https://stormmcp.ai/gateway/{gateway-id}/mcp \
  -H "Authorization: Bearer ag_YOUR_API_KEY_HERE"  # Wrong header!

MCP Protocol Basics

The MCP protocol uses JSON-RPC 2.0 format and requires session initialization before calling tools.

Required Headers

All requests must include:

Content-Type: application/json
Accept: application/json
X-API-Key: your_api_key_here

JSON-RPC Request Format

{
  "jsonrpc": "2.0",
  "method": "method_name",
  "id": "unique_request_id",
  "params": {
    // Method-specific parameters
  }
}

Testing Gateway Connection

Step 1: Initialize Session

Before calling any tools, you must initialize a session:

curl -X POST https://stormmcp.ai/gateway/{gateway-id}/mcp \
  -H "X-API-Key: ag_YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "initialize",
    "id": "init-1",
    "params": {
      "protocolVersion": "0.1.0",
      "clientInfo": {
        "name": "curl-test",
        "version": "1.0.0"
      }
    }
  }'

Expected Response:

{
  "result": {
    "protocolVersion": "2025-06-18",
    "capabilities": {
      "logging": {},
      "tools": {}
    },
    "serverInfo": {
      "name": "Airia MCP Gateway",
      "version": "1.0.0"
    }
  },
  "id": "init-1",
  "jsonrpc": "2.0"
}

Step 2: List Available Tools

To see what tools are available in your gateway:

curl -X POST https://stormmcp.ai/gateway/{gateway-id}/mcp \
  -H "X-API-Key: ag_YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -c cookies.txt -b cookies.txt \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/list",
    "id": "list-1"
  }'

Step 3: Call a Tool

Example calling the DateTime tool:

curl -X POST https://stormmcp.ai/gateway/{gateway-id}/mcp \
  -H "X-API-Key: ag_YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -c cookies.txt -b cookies.txt \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "id": "call-1",
    "params": {
      "name": "current_time",
      "arguments": {
        "format": "YYYY-MM-DD HH:mm:ss"
      }
    }
  }'

Session Management

⚠️ Warning

Important: The MCP protocol requires maintaining session state. When using curl, use cookies (-c cookies.txt -b cookies.txt) to maintain session between requests.

Using Cookies with curl

# Initialize and save cookies
curl -X POST https://stormmcp.ai/gateway/{gateway-id}/mcp \
  -H "X-API-Key: ag_YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -c cookies.txt \
  -d '{"jsonrpc":"2.0","method":"initialize","id":"1","params":{"protocolVersion":"0.1.0","clientInfo":{"name":"test","version":"1.0.0"}}}'

# Use cookies for subsequent requests
curl -X POST https://stormmcp.ai/gateway/{gateway-id}/mcp \
  -H "X-API-Key: ag_YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -b cookies.txt -c cookies.txt \
  -d '{"jsonrpc":"2.0","method":"tools/call","id":"2","params":{"name":"current_time","arguments":{"format":"YYYY-MM-DD"}}}'

Complete Example

Here's a complete example that initializes a session and calls a tool:

#!/bin/bash

GATEWAY_URL="https://stormmcp.ai/gateway/YOUR_GATEWAY_ID/mcp"
API_KEY="ag_YOUR_API_KEY_HERE"

# Clean up old cookies
rm -f cookies.txt

echo "1. Initializing session..."
curl -s -X POST "$GATEWAY_URL" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -c cookies.txt \
  -d '{
    "jsonrpc": "2.0",
    "method": "initialize",
    "id": "init",
    "params": {
      "protocolVersion": "0.1.0",
      "clientInfo": {
        "name": "bash-script",
        "version": "1.0.0"
      }
    }
  }' | jq .

echo -e "\n2. Calling tool..."
curl -s -X POST "$GATEWAY_URL" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -b cookies.txt -c cookies.txt \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "id": "call-1",
    "params": {
      "name": "current_time",
      "arguments": {
        "format": "YYYY-MM-DD HH:mm:ss",
        "timezone": "America/New_York"
      }
    }
  }' | jq .

Common Tool Examples

GitHub - Get Repository

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "id": "github-1",
  "params": {
    "name": "get_repository",
    "arguments": {
      "owner": "storm-mcp",
      "repo": "gateway"
    }
  }
}

Slack - Send Message

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "id": "slack-1",
  "params": {
    "name": "send_message",
    "arguments": {
      "channel": "#general",
      "text": "Hello from Storm MCP Gateway!"
    }
  }
}

Google Drive - List Files

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "id": "drive-1",
  "params": {
    "name": "list_files",
    "arguments": {
      "pageSize": 10,
      "fields": "files(id, name, mimeType)"
    }
  }
}

Error Handling

Common Errors and Solutions

Error	Cause	Solution
401 Unauthorized	Wrong authentication header	Use `X-API-Key`, not `Authorization: Bearer`
"Session not initialized"	No session or session expired	Call initialize method first, use cookies
"Accept header must include..."	Missing Accept header	Add `-H "Accept: application/json"`
Invalid JSON-RPC	Wrong request format	Ensure proper JSON-RPC 2.0 structure
Tool not found	Tool name incorrect	Use `tools/list` to get exact tool names

Debugging Tips

Always check headers first - Most issues are authentication-related
Use verbose mode - Add -v to curl to see full request/response
Check API key format - Keys should start with ag_
Verify gateway ID - Ensure you're using the correct gateway ID
Test initialization first - Always start with the initialize method

Testing with Programming Languages

Python Example

import requests
import json

# Configuration
GATEWAY_URL = "https://stormmcp.ai/gateway/YOUR_GATEWAY_ID/mcp"
API_KEY = "ag_YOUR_API_KEY_HERE"

# Create session
session = requests.Session()
session.headers.update({
    "X-API-Key": API_KEY,
    "Content-Type": "application/json",
    "Accept": "application/json"
})

# Initialize
init_response = session.post(GATEWAY_URL, json={
    "jsonrpc": "2.0",
    "method": "initialize",
    "id": "init",
    "params": {
        "protocolVersion": "0.1.0",
        "clientInfo": {
            "name": "python-client",
            "version": "1.0.0"
        }
    }
})
print("Initialized:", init_response.json())

# Call tool
tool_response = session.post(GATEWAY_URL, json={
    "jsonrpc": "2.0",
    "method": "tools/call",
    "id": "call-1",
    "params": {
        "name": "current_time",
        "arguments": {
            "format": "YYYY-MM-DD HH:mm:ss"
        }
    }
})
print("Tool result:", tool_response.json())

Node.js Example

const axios = require("axios");

// Configuration
const GATEWAY_URL = "https://stormmcp.ai/gateway/YOUR_GATEWAY_ID/mcp";
const API_KEY = "ag_YOUR_API_KEY_HERE";

// Create client with session support
const client = axios.create({
  baseURL: GATEWAY_URL,
  headers: {
    "X-API-Key": API_KEY,
    "Content-Type": "application/json",
    Accept: "application/json",
  },
  withCredentials: true,
});

async function testGateway() {
  // Initialize
  const initResponse = await client.post("", {
    jsonrpc: "2.0",
    method: "initialize",
    id: "init",
    params: {
      protocolVersion: "0.1.0",
      clientInfo: {
        name: "node-client",
        version: "1.0.0",
      },
    },
  });
  console.log("Initialized:", initResponse.data);

  // Call tool
  const toolResponse = await client.post("", {
    jsonrpc: "2.0",
    method: "tools/call",
    id: "call-1",
    params: {
      name: "current_time",
      arguments: {
        format: "YYYY-MM-DD HH:mm:ss",
      },
    },
  });
  console.log("Tool result:", toolResponse.data);
}

testGateway().catch(console.error);

Best Practices

Always initialize first - Every new session must start with initialization
Handle session expiry - Re-initialize if you get session errors
Use meaningful IDs - The id field helps match requests with responses
Store API keys securely - Never commit keys to version control
Implement retry logic - Handle transient network errors gracefully
Monitor rate limits - Check response headers for rate limit information