> ## 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.

# Create Server

> Deploy a new MCP server to the SuperBox registry

## Endpoint

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

## Authentication

<Tabs>
  <Tab title="Required">
    This endpoint requires authentication. Include your Firebase JWT token in
    the Authorization header.
    <Warning>You must be authenticated to create servers</Warning>
  </Tab>
</Tabs>

## Request Body

<ParamField body="name" type="string" required>
  Unique server identifier. **Rules:** lowercase letters, numbers, and hyphens only; must start with a letter; 3-50 characters. **Examples:** `weather-mcp`, `database-query-tool`
</ParamField>

<ParamField body="version" type="string" required>
  Semantic version number. **Format:** `MAJOR.MINOR.PATCH` (e.g., `1.0.0`, `2.3.1`)
</ParamField>

<ParamField body="description" type="string" required>
  Clear description of your server's functionality. **Length:** 20-500 characters
</ParamField>

<ParamField body="author" type="string" required>
  Your name or organization name
</ParamField>

<ParamField body="lang" type="string" required>
  Programming language. **Allowed values:** `python`, `javascript`, `typescript`, `go`, `rust`
</ParamField>

<ParamField body="license" type="string" required>
  Software license. **Common values:** `MIT`, `Apache-2.0`, `GPL-3.0`, `BSD-3-Clause`, `ISC`
</ParamField>

<ParamField body="entrypoint" type="string" required>
  Main file that starts your server. **Examples:** `main.py`, `index.js`, `server.ts`, `main.go`
</ParamField>

<ParamField body="repository" type="object" required>
  Git repository information

  <Expandable title="properties">
    <ParamField body="type" type="string" default="git">
      Repository type (usually `"git"`)
    </ParamField>

    <ParamField body="url" type="string" required>
      Public repository URL. Must be publicly accessible and contain MCP server code.
      **Example:** `https://github.com/username/repo-name`
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="pricing" type="object" required>
  Pricing configuration

  <Expandable title="properties">
    <ParamField body="currency" type="string" required>
      Three-letter currency code. **Examples:** `INR`, `USD`, `EUR`
    </ParamField>

    <ParamField body="amount" type="number" required>
      Price amount (use `0` for free servers). **Range:** 0 to 99999
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="metadata" type="object">
  Optional additional metadata

  <Expandable title="properties">
    <ParamField body="homepage" type="string">
      Project homepage URL. **Example:** `https://weather-mcp.dev`
    </ParamField>
  </Expandable>
</ParamField>

## Response

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

<ResponseField name="message" type="string">
  Human-readable confirmation message
</ResponseField>

<ResponseField name="server" type="object">
  The created server object (same structure as the [Get Server](/api/servers/get) response)
</ResponseField>

## Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.superbox.ai/api/v1/servers" \
    -H "Authorization: Bearer $SUPERBOX_API_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "weather-mcp",
      "version": "1.0.0",
      "description": "Get real-time weather information and forecasts for any location",
      "author": "Your Name",
      "lang": "python",
      "license": "MIT",
      "entrypoint": "main.py",
      "repository": {
        "type": "git",
        "url": "https://github.com/your-username/weather-mcp"
      },
      "pricing": {
        "currency": "INR",
        "amount": 0
      },
      "metadata": {
        "homepage": "https://weather-mcp.dev"
      }
    }'
  ```

  ```javascript JavaScript theme={null}
  const serverData = {
    name: "weather-mcp",
    version: "1.0.0",
    description: "Get real-time weather information and forecasts for any location",
    author: "Your Name",
    lang: "python",
    license: "MIT",
    entrypoint: "main.py",
    repository: {
      type: "git",
      url: "https://github.com/your-username/weather-mcp",
    },
    pricing: {
      currency: "INR",
      amount: 0,
    },
    metadata: {
      homepage: "https://weather-mcp.dev",
    },
  };

  const response = await fetch("https://api.superbox.ai/api/v1/servers", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.SUPERBOX_API_TOKEN}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(serverData),
  });

  const result = await response.json();

  if (result.status === "success") {
    console.log(`Server created: ${result.server.name}`);
  } else {
    console.error("Failed to create server:", result.detail);
  }
  ```

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

  server_data = {
      "name": "weather-mcp",
      "version": "1.0.0",
      "description": "Get real-time weather information and forecasts for any location",
      "author": "Your Name",
      "lang": "python",
      "license": "MIT",
      "entrypoint": "main.py",
      "repository": {
          "type": "git",
          "url": "https://github.com/your-username/weather-mcp"
      },
      "pricing": {
          "currency": "INR",
          "amount": 0
      },
      "metadata": {
          "homepage": "https://weather-mcp.dev"
      }
  }

  headers = {
      "Authorization": f"Bearer {os.getenv('SUPERBOX_API_TOKEN')}",
      "Content-Type": "application/json"
  }

  response = requests.post(
      "https://api.superbox.ai/api/v1/servers",
      headers=headers,
      json=server_data
  )

  result = response.json()

  if result['status'] == 'success':
      print(f"Server created: {result['server']['name']}")
  else:
      print(f"Failed to create server: {result['detail']}")
  ```

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

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

  type ServerRequest struct {
  Name        string     `json:"name"`
  Version     string     `json:"version"`
  Description string     `json:"description"`
  Author      string     `json:"author"`
  Lang        string     `json:"lang"`
  License     string     `json:"license"`
  Entrypoint  string     `json:"entrypoint"`
  Repository  Repository `json:"repository"`
  Pricing     Pricing    `json:"pricing"`
  Metadata    *Metadata  `json:"metadata,omitempty"`
  }

  type Repository struct {
  Type string `json:"type"`
  URL  string `json:"url"`
  }

  type Pricing struct {
  Currency string  `json:"currency"`
  Amount   float64 `json:"amount"`
  }

  type Metadata struct {
  Homepage string `json:"homepage"`
  }

  func main() {
  serverData := ServerRequest{
  Name:        "weather-mcp",
  Version:     "1.0.0",
  Description: "Get real-time weather information and forecasts",
  Author:      "Your Name",
  Lang:        "python",
  License:     "MIT",
  Entrypoint:  "main.py",
  Repository: Repository{
  Type: "git",
  URL:  "https://github.com/your-username/weather-mcp",
  },
  Pricing: Pricing{
  Currency: "INR",
  Amount:   0,
  },
  }

  jsonData, _ := json.Marshal(serverData)

  req, _ := http.NewRequest(
  "POST",
  "https://api.superbox.ai/api/v1/servers",
  bytes.NewBuffer(jsonData),
  )

  req.Header.Set("Authorization", "Bearer "+os.Getenv("SUPERBOX_API_TOKEN"))
  req.Header.Set("Content-Type", "application/json")

  client := &http.Client{}
  resp, err := client.Do(req)
  if err != nil {
  panic(err)
  }
  defer resp.Body.Close()

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

  if result["status"] == "success" {
  server := result["server"].(map[string]interface{})
  fmt.Printf("Server created: %s\n", server["name"])
  }
  }
  ```
</CodeGroup>

## Response Examples

<ResponseExample>
  ```json 201 Created theme={null}
  {
    "status": "success",
    "message": "Server 'weather-mcp' created successfully",
    "server": {
      "name": "weather-mcp",
      "version": "1.0.0",
      "description": "Get real-time weather information and forecasts for any location",
      "author": "Your Name",
      "lang": "python",
      "license": "MIT",
      "entrypoint": "main.py",
      "repository": {
        "type": "git",
        "url": "https://github.com/your-username/weather-mcp"
      },
      "pricing": {
        "currency": "INR",
        "amount": 0
      }
    }
  }
  ```

  ```json 400 Validation Error theme={null}
  {
    "status": "error",
    "detail": "Validation failed: name must be lowercase with hyphens only"
  }
  ```

  ```json 401 Unauthorized theme={null}
  {
    "status": "error",
    "detail": "Authentication token is required"
  }
  ```

  ```json 409 Conflict theme={null}
  {
    "status": "error",
    "detail": "Server with this name already exists"
  }
  ```

  ```json 422 Security Scan Failed theme={null}
  {
    "status": "error",
    "detail": "Security scan detected critical vulnerabilities"
  }
  ```
</ResponseExample>

## Deployment Process

After creating a server, SuperBox follows this workflow:

<Steps>
  <Step title="Repository Validation">
    Clone the repository, verify the structure and entrypoint, and check for required files.
  </Step>

  <Step title="Security Scanning">
    Run SonarCloud, tool discovery, Snyk, GitGuardian, and Bandit (for Python servers).
    <Warning>Servers with critical security issues will be rejected</Warning>
  </Step>

  <Step title="Registry Storage">
    Upload metadata to R2 registry, store repository URL and configuration, and generate the server manifest.
  </Step>

  <Step title="Ready">
    The server is immediately discoverable in the registry once the response is returned.
  </Step>
</Steps>

## Repository Requirements

<AccordionGroup>
  <Accordion title="Python Servers" icon="python">
    **Required files:**

    * `main.py` or specified entrypoint
    * `requirements.txt` or `pyproject.toml`
    * `README.md` (recommended)

    **Dependencies:** Must include the `mcp` package. All dependencies must be installable via pip.
  </Accordion>

  <Accordion title="JavaScript/TypeScript Servers" icon="node-js">
    **Required files:**

    * `index.js`/`index.ts` or specified entrypoint
    * `package.json`
    * `README.md` (recommended)

    **Dependencies:** Must include `@modelcontextprotocol/sdk`. All dependencies must be on the npm registry.
  </Accordion>

  <Accordion title="Go Servers" icon="golang">
    **Required files:**

    * `main.go` or specified entrypoint
    * `go.mod`
    * `README.md` (recommended)
  </Accordion>
</AccordionGroup>

## Best Practices

<CardGroup cols={2}>
  <Card title="Test Locally First" icon="check">
    Test your server thoroughly before submitting to the registry
  </Card>

  <Card title="Follow Semver" icon="tag">
    Use semantic versioning: MAJOR.MINOR.PATCH
  </Card>

  <Card title="Write Good Descriptions" icon="file-text">
    Clear descriptions help users understand your server's purpose
  </Card>

  <Card title="Security First" icon="shield">
    Never commit secrets or API keys to your repository
  </Card>

  <Card title="Document Well" icon="book">
    Include a comprehensive README with usage examples
  </Card>

  <Card title="Choose Appropriate License" icon="scale-balanced">
    Select a license that matches your intentions
  </Card>
</CardGroup>

## Common Errors

<AccordionGroup>
  <Accordion title="Invalid Server Name" icon="circle-xmark">
    **Error:** `name must be lowercase with hyphens only`

    Use only lowercase letters, numbers, and hyphens: `my-awesome-server` (valid), `MyAwesomeServer` (invalid)
  </Accordion>

  <Accordion title="Repository Not Found" icon="github">
    **Error:** `Unable to access Git repository`

    Ensure the repository is **public** and the URL is correct.
  </Accordion>

  <Accordion title="Missing Entrypoint" icon="file-slash">
    **Error:** `Entry point file not found in repository`

    Ensure the file specified in `entrypoint` exists in your repository root.
  </Accordion>

  <Accordion title="Security Scan Failed" icon="triangle-exclamation">
    **Error:** `Security scan detected critical vulnerabilities`

    Remove hardcoded secrets/API keys, fix code vulnerabilities, and update dependencies with known vulnerabilities.
  </Accordion>

  <Accordion title="Name Already Taken" icon="ban">
    **Error:** `Server with this name already exists`

    Choose a different, unique name or add your username as a prefix: `username-server-name`
  </Accordion>
</AccordionGroup>