List Servers

Retrieve a list of all available MCP servers with optional filtering and pagination

GET /servers

List Servers

cURL

curl --request GET \
  --url https://api.example.com/servers

200 Success

{
  "success": true,
  "data": [
    {
      "name": "weather-mcp",
      "version": "1.2.3",
      "description": "Get weather information for any location using OpenWeatherMap API",
      "author": "areeb",
      "lang": "python",
      "license": "MIT",
      "entrypoint": "main.py",
      "repository": {
        "type": "git",
        "url": "https://github.com/areeb/weather-mcp"
      },
      "tools": {
        "count": 3,
        "names": ["get_weather", "get_forecast", "search_location"]
      },
      "pricing": {
        "currency": "USD",
        "amount": 0
      },
      "security_report": {
        "summary": {
          "scan_passed": true,
          "total_issues_all_scanners": 0,
          "critical_issues": 0
        }
      }
    },
    {
      "name": "database-query-mcp",
      "version": "2.0.1",
      "description": "Query databases with natural language using AI",
      "author": "janedoe",
      "lang": "typescript",
      "license": "Apache-2.0",
      "entrypoint": "index.ts",
      "repository": {
        "type": "git",
        "url": "https://github.com/janedoe/database-query-mcp"
      },
      "tools": {
        "count": 5,
        "names": ["query", "schema", "execute", "explain", "optimize"]
      },
      "pricing": {
        "currency": "USD",
        "amount": 9.99
      },
      "security_report": {
        "summary": {
          "scan_passed": true,
          "total_issues_all_scanners": 2,
          "critical_issues": 0
        }
      }
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 247,
      "totalPages": 13,
      "hasNext": true,
      "hasPrev": false
    },
    "timestamp": "2025-12-09T10:30:00Z",
    "version": "v1"
  }
}

Endpoint

GET https://api.superbox.ai/api/v1/servers

Authentication

Optional

This endpoint works with or without authentication.

Authenticated requests have higher rate limits (1000/hour vs 100/hour)

Query Parameters

page · integer · default: "1"

Page number for pagination (1-indexed)

limit · integer · default: "20"

Number of servers per page (max: 100)

lang · string

Filter by programming language Allowed values: python, javascript, typescript, go, rust

author · string

Filter by server author/creator

pricing · string

Filter by pricing model Allowed values: free, paid

search · string

Search servers by name or description

sort · string · default: "created_at"

Sort field and order Examples: - name - Sort by name (A-Z) - -name - Sort by name (Z-A) - -downloads - Most downloads first - -created_at - Newest first - pricing.amount - Lowest price first

security_passed · boolean

Filter by security scan status Values: - true - Only servers that passed security scans - false - Servers with security issues

Response

success · boolean

Indicates if the request was successful

data · array

Array of server objects

Show Server Object

name · string · required

Unique server identifier (lowercase with hyphens)

version · string · required

Semantic version (e.g., “1.0.0”)

description · string · required

Brief description of the server’s functionality

author · string · required

Server creator/maintainer name

lang · string · required

Programming language

license · string · required

Software license (e.g., “MIT”, “Apache-2.0”)

entrypoint · string · required

Entry point file for server execution

repository · object · required

Repository information

Show properties

type · string

Repository type (e.g., “git”)

url · string

Repository URL

tools · object

Available tools information

Show properties

count · integer

Number of tools provided by the server

names · array

Array of tool names

pricing · object · required

Pricing information

Show properties

currency · string

Currency code (e.g., “USD”)

amount · number

Price amount (0 for free servers)

security_report · object

Security scan summary

Show properties

summary.scan_passed · boolean

Whether the server passed security scans

summary.total_issues_all_scanners · integer

Total number of issues found

summary.critical_issues · integer

Number of critical security issues

meta · object

Response metadata

Show properties

pagination · object

Pagination information

Show properties

page · integer

Current page number

limit · integer

Items per page

total · integer

Total number of servers

totalPages · integer

Total number of pages

hasNext · boolean

Whether there’s a next page

hasPrev · boolean

Whether there’s a previous page

timestamp · string

ISO 8601 timestamp

Examples

cURL
# List all servers (default pagination)
curl -X GET "https://api.superbox.ai/api/v1/servers" \
  -H "Content-Type: application/json"

# List Python servers only

curl -X GET "https://api.superbox.ai/api/v1/servers?lang=python" \
 -H "Content-Type: application/json"

# List free servers with security passed

curl -X GET "https://api.superbox.ai/api/v1/servers?pricing=free&security_passed=true" \
 -H "Content-Type: application/json"

# Search and sort

curl -X GET "https://api.superbox.ai/api/v1/servers?search=weather&sort=-downloads" \
 -H "Content-Type: application/json"

# With authentication

curl -X GET "https://api.superbox.ai/api/v1/servers?page=2&limit=50" \
 -H "Authorization: Bearer $SUPERBOX_API_TOKEN" \
 -H "Content-Type: application/json"

Response Examples

200 Success

{
  "success": true,
  "data": [
    {
      "name": "weather-mcp",
      "version": "1.2.3",
      "description": "Get weather information for any location using OpenWeatherMap API",
      "author": "areeb",
      "lang": "python",
      "license": "MIT",
      "entrypoint": "main.py",
      "repository": {
        "type": "git",
        "url": "https://github.com/areeb/weather-mcp"
      },
      "tools": {
        "count": 3,
        "names": ["get_weather", "get_forecast", "search_location"]
      },
      "pricing": {
        "currency": "USD",
        "amount": 0
      },
      "security_report": {
        "summary": {
          "scan_passed": true,
          "total_issues_all_scanners": 0,
          "critical_issues": 0
        }
      }
    },
    {
      "name": "database-query-mcp",
      "version": "2.0.1",
      "description": "Query databases with natural language using AI",
      "author": "janedoe",
      "lang": "typescript",
      "license": "Apache-2.0",
      "entrypoint": "index.ts",
      "repository": {
        "type": "git",
        "url": "https://github.com/janedoe/database-query-mcp"
      },
      "tools": {
        "count": 5,
        "names": ["query", "schema", "execute", "explain", "optimize"]
      },
      "pricing": {
        "currency": "USD",
        "amount": 9.99
      },
      "security_report": {
        "summary": {
          "scan_passed": true,
          "total_issues_all_scanners": 2,
          "critical_issues": 0
        }
      }
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 247,
      "totalPages": 13,
      "hasNext": true,
      "hasPrev": false
    },
    "timestamp": "2025-12-09T10:30:00Z",
    "version": "v1"
  }
}

Use Cases

Browse All Servers

const response = await fetch('https://api.superbox.ai/api/v1/servers');
const { data: servers } = await response.json();

// Display servers in UI
servers.forEach(server => {
  displayServerCard(server);
});

Filter by Language

# Get all Python servers
response = requests.get(
    'https://api.superbox.ai/api/v1/servers',
    params={'lang': 'python'}
)
python_servers = response.json()['data']

Search Functionality

async function searchServers(query) {
  const response = await fetch(
    `https://api.superbox.ai/api/v1/servers?search=${encodeURIComponent(query)}`
  );
  return response.json();
}

const results = await searchServers('weather');

Pagination Implementation

def get_all_servers():
    all_servers = []
    page = 1
    
    while True:
        response = requests.get(
            'https://api.superbox.ai/api/v1/servers',
            params={'page': page, 'limit': 100}
        )
        data = response.json()
        
        all_servers.extend(data['data'])
        
        if not data['meta']['pagination']['hasNext']:
            break
        
        page += 1
    
    return all_servers

Security-Focused Discovery

// Only show secure, free servers
const response = await fetch(
  'https://api.superbox.ai/api/v1/servers?pricing=free&security_passed=true'
);
const secureServers = await response.json();

Best Practices

Use Pagination

Always implement pagination for large result sets to improve performance

Cache Results

Cache server lists on the client side with appropriate TTL (5-10 minutes)

Filter Server-Side

Use query parameters instead of filtering on the client to reduce data transfer

Handle Rate Limits

Implement exponential backoff when rate limits are hit

For better performance, use authenticated requests which have higher rate limits and may return cached results faster.

Related Endpoints

Get Server Details

Retrieve detailed information about a specific server

Create Server

Deploy a new MCP server