MCPulse
Pricing Dashboard

API Reference

Complete reference for all MCPulse API endpoints. All requests must include authentication.

Base URL:

https://stacks.polsia.app

Authentication

MCPulse uses JWT tokens for dashboard API access and API keys for monitoring endpoints.

Dashboard API (JWT)

Login to get a JWT token. Include it in Authorization header.

curl -X POST https://stacks.polsia.app/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@example.com",
    "password": "your-password"
  }'

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": 123,
    "email": "you@example.com"
  }
}

Use token in requests:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Public API (V1) — API Keys

For programmatic access to reliability scores. Get your API key from Dashboard → API Keys.

curl https://stacks.polsia.app/api/v1/scores/my-server-id \
  -H "X-API-Key: mcpulse_sk_abc123xyz..."

⚡ Rate Limit: 1000 requests/hour per API key

Health Reporting

Used by mcpulse-monitor to report server health and metrics.

POST /api/mcpulse/health

Report server health metrics and heartbeat. Called automatically by mcpulse-monitor.

Request Body:

{
  "serverId": "my-server-id",
  "apiKey": "mcpulse_sk_abc123xyz...",
  "status": "healthy",
  "metrics": {
    "totalRequests": 1250,
    "successfulRequests": 1245,
    "failedRequests": 5,
    "avgResponseTime": 124,
    "errorsByType": { "TimeoutError": 3 },
    "requestsByTool": { "getTool": 450 }
  }
}

Response (200):

{
  "success": true,
  "serverId": "my-server-id",
  "timestamp": "2026-02-12T04:30:00.000Z"
}

Server Management

GET /api/mcpulse/servers

Get all your registered MCP servers.

Headers:

Authorization: Bearer {jwt_token}

Response (200):

{
  "servers": [
    {
      "id": "weather-mcp-prod",
      "name": "Weather MCP (Production)",
      "created_at": "2026-02-01T12:00:00.000Z",
      "last_health_check": "2026-02-12T04:29:30.000Z",
      "uptime_24h": 99.8,
      "reliability_score": 95
    }
  ]
}
GET /api/mcpulse/servers/:id

Get detailed information about a specific server.

Response (200):

{
  "server": {
    "id": "weather-mcp-prod",
    "name": "Weather MCP (Production)",
    "uptime_24h": 99.8,
    "uptime_7d": 99.5,
    "uptime_30d": 98.9,
    "avg_response_time": 124,
    "error_rate": 0.4,
    "reliability_score": 95,
    "total_requests_24h": 1250
  }
}
POST /api/mcpulse/servers

Register a new MCP server and get an API key.

Request Body:

{
  "name": "My Weather Server",
  "description": "Production weather MCP server"
}

Response (201):

{
  "server": {
    "id": "weather-mcp-prod",
    "name": "My Weather Server",
    "api_key": "mcpulse_sk_abc123xyz..."
  }
}

Reliability Scores (Public API V1)

Query reliability scores for any MCP server. Requires API key authentication.

GET /api/v1/scores/:serverId

Get the reliability score for a specific server.

Headers:

X-API-Key: mcpulse_sk_abc123xyz...

Response (200):

{
  "serverId": "weather-mcp-prod",
  "score": 95,
  "grade": "A+",
  "uptime_24h": 99.8,
  "avg_response_time": 124,
  "error_rate": 0.4,
  "timestamp": "2026-02-12T04:30:00.000Z"
}
GET /api/v1/scores/search

Search for servers by name or description.

Query Parameters:

  • • q — Search query (required)
  • • limit — Results per page (default: 10, max: 50)
GET /api/v1/scores/search?q=weather&limit=5

Response (200):

{
  "results": [
    {
      "serverId": "weather-mcp-prod",
      "name": "Weather MCP",
      "score": 95,
      "grade": "A+",
      "uptime_24h": 99.8
    }
  ],
  "count": 1
}
GET /api/v1/scores/compare

Compare reliability scores across multiple servers.

Query Parameters:

  • • servers — Comma-separated server IDs (required)
GET /api/v1/scores/compare?servers=server-a,server-b,server-c
GET /api/v1/scores/top

Get the top-rated servers by reliability score.

Query Parameters:

  • • limit — Results per page (default: 10, max: 50)

Badges

Public badge endpoints for embedding reliability scores in README files.

GET /api/badge/:serverId

Get an SVG badge showing reliability score. No authentication required.

Query Parameters:

  • • type — Badge type: reliability (default), uptime, response_time, combined
GET /api/badge/my-server-id?type=reliability

Embed in Markdown:

![MCPulse](https://stacks.polsia.app/api/badge/my-server-id?type=combined)

Badge colors automatically adjust based on score (green = A+, yellow = B, red = C/D).

API Keys Management

GET /api/keys

List all your API keys.

Response (200):

{
  "keys": [
    {
      "id": "key_123",
      "name": "Production Key",
      "key_prefix": "mcpulse_sk_abc...",
      "created_at": "2026-02-01T12:00:00.000Z",
      "last_used_at": "2026-02-12T04:00:00.000Z",
      "requests_count": 5432
    }
  ]
}
POST /api/keys

Create a new API key.

Request Body:

{
  "name": "Production Key"
}

Response (201):

{
  "key": {
    "id": "key_123",
    "name": "Production Key",
    "api_key": "mcpulse_sk_abc123xyz..."
  }
}
DELETE /api/keys/:keyId

Delete an API key. This action is permanent.

Response (200):

{
  "success": true,
  "message": "API key deleted"
}

Error Codes

400 Bad Request Invalid request parameters 
{ "error": "Missing required field: serverId" }
401 Unauthorized Missing or invalid authentication 
{ "error": "Access token required" }
403 Forbidden Invalid or expired token 
{ "error": "Invalid or expired token" }
404 Not Found Resource not found 
{ "error": "Server not found" }
429 Too Many Requests Rate limit exceeded 
{ "error": "Rate limit exceeded. Try again in 3600 seconds" }
500 Internal Server Error Server error 
{ "error": "Internal server error" }

⚡ Rate Limits

Dashboard API (JWT): Unlimited
Public API V1 (API Keys): 1000 req/hour
Health Reporting: Unlimited

Need Help with the API?

Questions about authentication, endpoints, or rate limits?

Email Support Report Issue