> ## Documentation Index
> Fetch the complete documentation index at: https://acm-aa28ebf6.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# List Servers

> Retrieve a list of all available MCP servers with optional filtering

## Endpoint

<Card>
  <code>GET [https://api.superbox.ai/api/v1/servers](https://api.superbox.ai/api/v1/servers)</code>
</Card>

## Authentication

This endpoint does not require authentication. All registered MCP servers are publicly discoverable.

## Query Parameters

<ParamField query="author" type="string">
  Filter servers by author/creator username
</ParamField>

## Response

<ResponseField name="status" type="string">
  `"success"` on success, `"error"` on failure
</ResponseField>

<ResponseField name="total" type="integer">
  Total number of servers returned
</ResponseField>

<ResponseField name="servers" type="array">
  Array of server objects

  <Expandable title="Server Object">
    <ResponseField name="name" type="string" required>
      Unique server identifier (lowercase with hyphens)
    </ResponseField>

    <ResponseField name="version" type="string" required>
      Semantic version (e.g., `"1.0.0"`)
    </ResponseField>

    <ResponseField name="description" type="string" required>
      Brief description of the server's functionality
    </ResponseField>

    <ResponseField name="author" type="string" required>
      Server creator/maintainer name
    </ResponseField>

    <ResponseField name="lang" type="string" required>
      Programming language
    </ResponseField>

    <ResponseField name="license" type="string" required>
      Software license (e.g., `"MIT"`, `"Apache-2.0"`)
    </ResponseField>

    <ResponseField name="entrypoint" type="string" required>
      Entry point file for server execution
    </ResponseField>

    <ResponseField name="repository" type="object" required>
      Repository information

      <Expandable title="properties">
        <ResponseField name="type" type="string">
          Repository type (e.g., `"git"`)
        </ResponseField>

        <ResponseField name="url" type="string">
          Repository URL
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="tools" type="object">
      Available tools information

      <Expandable title="properties">
        <ResponseField name="count" type="integer">
          Number of tools provided by the server
        </ResponseField>

        <ResponseField name="names" type="array">
          Array of tool names
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="pricing" type="object" required>
      Pricing information

      <Expandable title="properties">
        <ResponseField name="currency" type="string">
          Currency code (e.g., `"INR"`)
        </ResponseField>

        <ResponseField name="amount" type="number">
          Price amount (`0` for free servers)
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="security_report" type="object">
      Security scan summary

      <Expandable title="properties">
        <ResponseField name="summary.scan_passed" type="boolean">
          Whether the server passed security scans
        </ResponseField>

        <ResponseField name="summary.total_issues_all_scanners" type="integer">
          Total number of issues found across all scanners
        </ResponseField>

        <ResponseField name="summary.critical_issues" type="integer">
          Number of critical security issues
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

## Examples

<CodeGroup>
  ```bash cURL theme={null}
  # List all servers
  curl -X GET "https://api.superbox.ai/api/v1/servers"

  # Filter by author
  curl -X GET "https://api.superbox.ai/api/v1/servers?author=areeb"
  ```

  ```javascript JavaScript theme={null}
  // List all servers
  const response = await fetch('https://api.superbox.ai/api/v1/servers');
  const data = await response.json();

  console.log(`Found ${data.total} servers`);
  data.servers.forEach(server => {
    console.log(`${server.name} v${server.version} - ${server.description}`);
  });

  // Filter by author
  const authorResponse = await fetch(
    'https://api.superbox.ai/api/v1/servers?author=areeb'
  );
  const authorData = await authorResponse.json();
  ```

  ```python Python theme={null}
  import requests

  # List all servers
  response = requests.get('https://api.superbox.ai/api/v1/servers')
  data = response.json()

  print(f"Found {data['total']} servers")
  for server in data['servers']:
      print(f"{server['name']} v{server['version']} - {server['description']}")

  # Filter by author
  response = requests.get(
      'https://api.superbox.ai/api/v1/servers',
      params={'author': 'areeb'}
  )
  data = response.json()
  ```

  ```go Go theme={null}
  package main

  import (
  "encoding/json"
  "fmt"
  "net/http"
  )

  func main() {
  resp, err := http.Get("https://api.superbox.ai/api/v1/servers")
  if err != nil {
  panic(err)
  }
  defer resp.Body.Close()

  var result map[string]interface{}
  json.NewDecoder(resp.Body).Decode(&result)

  fmt.Printf("Found %v servers\n", result["total"])
  }
  ```
</CodeGroup>

## Response Examples

<ResponseExample>
  ```json 200 Success theme={null}
  {
    "status": "success",
    "total": 2,
    "servers": [
      {
        "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": "INR",
          "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": "INR",
          "amount": 499
        },
        "security_report": {
          "summary": {
            "scan_passed": true,
            "total_issues_all_scanners": 2,
            "critical_issues": 0
          }
        }
      }
    ]
  }
  ```

  ```json 500 Server Error theme={null}
  {
    "status": "error",
    "detail": "Internal server error"
  }
  ```
</ResponseExample>

## Use Cases

<AccordionGroup>
  <Accordion title="Browse All Servers" icon="list">
    ```javascript theme={null}
    const response = await fetch('https://api.superbox.ai/api/v1/servers');
    const { servers } = await response.json();

    servers.forEach(server => {
      displayServerCard(server);
    });
    ```
  </Accordion>

  <Accordion title="Show Servers by Author" icon="user">
    ```python theme={null}
    # Get all servers by a specific author
    response = requests.get(
        'https://api.superbox.ai/api/v1/servers',
        params={'author': 'areeb'}
    )
    author_servers = response.json()['servers']
    ```
  </Accordion>
</AccordionGroup>

## Best Practices

<CardGroup cols={2}>
  <Card title="Cache Results" icon="database">
    Cache server lists on the client side with an appropriate TTL (5-10 minutes)
  </Card>

  <Card title="Use Author Filter" icon="filter">
    Use the `author` query parameter to show a user's servers on profile pages
  </Card>
</CardGroup>

## Related Endpoints

<CardGroup cols={2}>
  <Card title="Get Server Details" icon="file" href="/api/servers/get">
    Retrieve detailed information about a specific server
  </Card>

  <Card title="Create Server" icon="plus" href="/api/servers/create">
    Deploy a new MCP server
  </Card>
</CardGroup>