API Endpoints

Storm MCP Gateway provides a comprehensive RESTful API for programmatic access to all features. This reference documents all available endpoints, request formats, and response structures.

Base URL

All API requests should be made to:

https://api.stormmcp.ai/v1

For self-hosted installations:

https://your-domain.com/api/v1

Authentication

Include your API key in the Authorization header:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.stormmcp.ai/v1/endpoint

Or as a query parameter (less secure):

curl https://api.stormmcp.ai/v1/endpoint?api_key=YOUR_API_KEY

Response Format

All responses follow a consistent format:

Success Response

{
  "success": true,
  "data": {
    // Response data
  },
  "meta": {
    "timestamp": "2025-01-28T10:30:45Z",
    "request_id": "req_abc123"
  }
}

Error Response

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid gateway configuration",
    "details": {
      "field": "name",
      "issue": "Name is required"
    }
  },
  "meta": {
    "timestamp": "2025-01-28T10:30:45Z",
    "request_id": "req_abc123"
  }
}

Gateway Endpoints

List Gateways

Get all gateways for the authenticated user.

GET /gateways

Query Parameters:

Parameter	Type	Description
page	integer	Page number (default: 1)
limit	integer	Items per page (default: 20, max: 100)
sort	string	Sort field (name, created_at, updated_at)
order	string	Sort order (asc, desc)

Response:

{
  "data": {
    "gateways": [
      {
        "id": "gw_abc123",
        "name": "Development Gateway",
        "description": "Gateway for dev environment",
        "endpoint": "https://gateway.stormmcp.ai/g/gw_abc123",
        "servers": ["github", "slack", "mongodb"],
        "functions_count": 127,
        "created_at": "2025-01-15T10:30:45Z",
        "updated_at": "2025-01-20T14:22:10Z",
        "status": "active"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 45,
      "pages": 3
    }
  }
}

Get Gateway

Retrieve details of a specific gateway.

GET /gateways/{gateway_id}

Response:

{
  "data": {
    "id": "gw_abc123",
    "name": "Development Gateway",
    "description": "Gateway for dev environment",
    "endpoint": "https://gateway.stormmcp.ai/g/gw_abc123",
    "servers": [
      {
        "id": "github",
        "name": "GitHub",
        "status": "connected",
        "functions": ["repos_get", "issues_create"]
      }
    ],
    "allowed_tools": {
      "github": ["repos_get", "issues_create"],
      "slack": ["chat_postMessage"]
    },
    "configuration": {
      "rate_limit": 1000,
      "cache_ttl": 300
    },
    "metrics": {
      "requests_today": 1234,
      "errors_today": 5,
      "avg_response_time": 245
    }
  }
}

Create Gateway

Create a new gateway.

POST /gateways

Request Body:

{
  "name": "Production Gateway",
  "description": "Main production gateway",
  "servers": ["github", "slack", "stripe"],
  "allowed_tools": {
    "github": ["repos_get", "issues_create"],
    "slack": "*",
    "stripe": ["charges_create", "customers_get"]
  },
  "configuration": {
    "rate_limit": 5000,
    "cache_enabled": true
  }
}

Response:

{
  "data": {
    "id": "gw_def456",
    "name": "Production Gateway",
    "endpoint": "https://gateway.stormmcp.ai/g/gw_def456",
    "api_key": "gw_key_xyz789",
    "created_at": "2025-01-28T10:30:45Z"
  }
}

Update Gateway

Update an existing gateway.

PATCH /gateways/{gateway_id}

Request Body:

{
  "name": "Updated Gateway Name",
  "servers": ["github", "slack", "mongodb"],
  "allowed_tools": {
    "mongodb": ["find", "insert", "update"]
  }
}

Delete Gateway

Delete a gateway.

DELETE /gateways/{gateway_id}

Response:

{
  "success": true,
  "message": "Gateway deleted successfully"
}

App Endpoints

List Apps

Get all available MCP server apps.

GET /apps

Query Parameters:

Parameter	Type	Description
category	string	Filter by category
status	string	Filter by status (available, connected, beta)
search	string	Search by name or description

Response:

{
  "data": {
    "apps": [
      {
        "id": "github",
        "name": "GitHub",
        "description": "Version control and collaboration",
        "category": "developer_tools",
        "status": "available",
        "auth_types": ["oauth", "api_key"],
        "functions_count": 152,
        "icon": "FiGithub"
      }
    ]
  }
}

Get App Details

Get detailed information about a specific app.

GET /apps/{app_id}

Response:

{
  "data": {
    "id": "github",
    "name": "GitHub",
    "description": "Version control and collaboration platform",
    "long_description": "...",
    "category": "developer_tools",
    "status": "connected",
    "auth_types": ["oauth", "api_key"],
    "current_auth": "oauth",
    "functions": [
      {
        "name": "repos_get",
        "description": "Get repository details",
        "parameters": {
          "owner": "string",
          "repo": "string"
        }
      }
    ],
    "configuration": {
      "base_url": "https://api.github.com",
      "rate_limit": 5000
    }
  }
}

Connect App

Connect an app with authentication.

POST /apps/{app_id}/connect

Request Body (OAuth):

{
  "auth_type": "oauth",
  "redirect_uri": "https://app.stormmcp.ai/oauth/callback"
}

Request Body (API Key):

{
  "auth_type": "api_key",
  "credentials": {
    "api_key": "ghp_abc123...",
    "api_secret": "optional_secret"
  }
}

Response:

{
  "data": {
    "app_id": "github",
    "status": "connected",
    "connection_id": "conn_abc123"
  }
}

Disconnect App

Disconnect an app.

DELETE /apps/{app_id}/connection

Test App Connection

Test if an app is properly connected.

POST /apps/{app_id}/test

Response:

{
  "data": {
    "status": "success",
    "latency": 145,
    "message": "Connection successful"
  }
}

Session Endpoints

List Sessions

Get active sessions.

GET /sessions

Query Parameters:

Parameter	Type	Description
gateway_id	string	Filter by gateway
client_type	string	Filter by client (claude, cursor)
active	boolean	Only active sessions

Response:

{
  "data": {
    "sessions": [
      {
        "id": "sess_abc123",
        "gateway_id": "gw_abc123",
        "client": {
          "type": "claude_desktop",
          "version": "1.1.0",
          "ip": "203.0.113.45"
        },
        "started_at": "2025-01-28T08:15:30Z",
        "last_activity": "2025-01-28T10:28:15Z",
        "requests_count": 234,
        "status": "active"
      }
    ]
  }
}

Get Session Details

Get detailed information about a session.

GET /sessions/{session_id}

Terminate Session

End an active session.

DELETE /sessions/{session_id}

Logging Endpoints

Get Request Logs

Retrieve request logs with filtering.

GET /logs

Query Parameters:

Parameter	Type	Description
gateway_id	string	Filter by gateway
app_id	string	Filter by app
status	string	Filter by status (success, error)
start_date	ISO 8601	Start of time range
end_date	ISO 8601	End of time range
page	integer	Page number
limit	integer	Items per page (max: 100)

Response:

{
  "data": {
    "logs": [
      {
        "id": "log_xyz789",
        "timestamp": "2025-01-28T10:30:45.123Z",
        "gateway_id": "gw_abc123",
        "app": "github",
        "function": "repos_get",
        "duration": 145,
        "status": "success",
        "request": {
          "params": {
            "owner": "storm-mcp",
            "repo": "gateway"
          }
        },
        "response": {
          "status": 200,
          "data": {...}
        }
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 50,
      "total": 1234
    }
  }
}

Get Log Analytics

Get aggregated analytics from logs.

GET /logs/analytics

Query Parameters:

Parameter	Type	Description
gateway_id	string	Filter by gateway
period	string	Time period (1h, 24h, 7d, 30d)
group_by	string	Grouping (app, function, status)

Response:

{
  "data": {
    "summary": {
      "total_requests": 12345,
      "success_rate": 0.982,
      "avg_duration": 245,
      "error_count": 223
    },
    "time_series": [
      {
        "timestamp": "2025-01-28T10:00:00Z",
        "requests": 145,
        "errors": 2,
        "avg_duration": 230
      }
    ],
    "top_functions": [
      {
        "function": "github.repos_get",
        "count": 3456,
        "avg_duration": 180
      }
    ]
  }
}

Metrics Endpoints

Get Gateway Metrics

Get performance metrics for a gateway.

GET /metrics/gateway/{gateway_id}

Query Parameters:

Parameter	Type	Description
period	string	Time period (1h, 24h, 7d)
resolution	string	Data resolution (1m, 5m, 1h)

Response:

{
  "data": {
    "gateway_id": "gw_abc123",
    "period": "24h",
    "metrics": {
      "requests": 12345,
      "errors": 123,
      "avg_latency": 245,
      "p95_latency": 890,
      "p99_latency": 1234
    },
    "time_series": [
      {
        "timestamp": "2025-01-28T10:00:00Z",
        "requests": 234,
        "latency": 245,
        "errors": 2
      }
    ]
  }
}

Get App Metrics

Get metrics for a specific app.

GET /metrics/app/{app_id}

User & Team Endpoints

Get Current User

Get information about the authenticated user.

GET /user

Response:

{
  "data": {
    "id": "user_abc123",
    "email": "user@example.com",
    "name": "John Doe",
    "role": "admin",
    "organization": {
      "id": "org_xyz789",
      "name": "Acme Corp"
    },
    "created_at": "2025-01-01T00:00:00Z"
  }
}

Update User Profile

Update user information.

PATCH /user

Request Body:

{
  "name": "Jane Doe",
  "notification_preferences": {
    "email": true,
    "slack": false
  }
}

Webhook Endpoints

List Webhooks

Get configured webhooks.

GET /webhooks

Create Webhook

Create a new webhook.

POST /webhooks

Request Body:

{
  "url": "https://example.com/webhook",
  "events": ["gateway.created", "app.connected", "error.critical"],
  "secret": "webhook_secret_key"
}

Update Webhook

Update webhook configuration.

PATCH /webhooks/{webhook_id}

Delete Webhook

Remove a webhook.

DELETE /webhooks/{webhook_id}

Error Codes

Common error codes and their meanings:

Code	Description
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid or missing API key
403	Forbidden - Insufficient permissions
404	Not Found - Resource doesn't exist
409	Conflict - Resource already exists
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error
503	Service Unavailable

Rate Limiting

API requests are rate limited:

Default: 1000 requests per hour
Enterprise: 10000 requests per hour

Rate limit information is included in response headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

Pagination

List endpoints support pagination:

GET /gateways?page=2&limit=50

Pagination info is included in responses:

{
  "pagination": {
    "page": 2,
    "limit": 50,
    "total": 234,
    "pages": 5,
    "has_next": true,
    "has_prev": true
  }
}

Webhooks

Storm MCP can send webhooks for various events:

Event Types

gateway.created - New gateway created
gateway.updated - Gateway configuration changed
gateway.deleted - Gateway removed
app.connected - App successfully connected
app.disconnected - App disconnected
error.critical - Critical error occurred
usage.limit_warning - Approaching usage limit

Webhook Payload

{
  "event": "gateway.created",
  "timestamp": "2025-01-28T10:30:45Z",
  "data": {
    // Event-specific data
  },
  "signature": "sha256=abc123..."
}

Verifying Webhooks

Verify webhook signatures:

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const hash = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  
  return `sha256=${hash}` === signature;
}

SDK Support

Official SDKs are available:

JavaScript/TypeScript: npm install @storm-mcp/sdk
Python: pip install storm-mcp
Go: go get github.com/storm-mcp/go-sdk
Ruby: gem install storm-mcp

API Endpoints

Base URL

Authentication

Response Format

Success Response

Error Response

Gateway Endpoints

List Gateways

Get Gateway

Create Gateway

Update Gateway

Delete Gateway

App Endpoints

List Apps

Get App Details

Connect App

Disconnect App

Test App Connection

Session Endpoints

List Sessions

Get Session Details

Terminate Session

Logging Endpoints

Get Request Logs

Get Log Analytics

Metrics Endpoints

Get Gateway Metrics

Get App Metrics

User & Team Endpoints

Get Current User

Update User Profile

Webhook Endpoints

List Webhooks

Create Webhook

Update Webhook

Delete Webhook

Error Codes

Rate Limiting

Pagination

Webhooks

Event Types

Webhook Payload

Verifying Webhooks

SDK Support

Next Steps