Create Server

curl --request POST \
  --url https://api.example.com/servers \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "version": "<string>",
  "description": "<string>",
  "author": "<string>",
  "lang": "<string>",
  "license": "<string>",
  "entrypoint": "<string>",
  "repository": {
    "type": "<string>",
    "url": "<string>"
  },
  "pricing": {
    "currency": "<string>",
    "amount": 123
  },
  "metadata": {
    "homepage": "<string>"
  }
}
'

import requests

url = "https://api.example.com/servers"

payload = {
    "name": "<string>",
    "version": "<string>",
    "description": "<string>",
    "author": "<string>",
    "lang": "<string>",
    "license": "<string>",
    "entrypoint": "<string>",
    "repository": {
        "type": "<string>",
        "url": "<string>"
    },
    "pricing": {
        "currency": "<string>",
        "amount": 123
    },
    "metadata": { "homepage": "<string>" }
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: '<string>',
    version: '<string>',
    description: '<string>',
    author: '<string>',
    lang: '<string>',
    license: '<string>',
    entrypoint: '<string>',
    repository: {type: '<string>', url: '<string>'},
    pricing: {currency: '<string>', amount: 123},
    metadata: {homepage: '<string>'}
  })
};

fetch('https://api.example.com/servers', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/servers",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => '<string>',
    'version' => '<string>',
    'description' => '<string>',
    'author' => '<string>',
    'lang' => '<string>',
    'license' => '<string>',
    'entrypoint' => '<string>',
    'repository' => [
        'type' => '<string>',
        'url' => '<string>'
    ],
    'pricing' => [
        'currency' => '<string>',
        'amount' => 123
    ],
    'metadata' => [
        'homepage' => '<string>'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/servers"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"version\": \"<string>\",\n  \"description\": \"<string>\",\n  \"author\": \"<string>\",\n  \"lang\": \"<string>\",\n  \"license\": \"<string>\",\n  \"entrypoint\": \"<string>\",\n  \"repository\": {\n    \"type\": \"<string>\",\n    \"url\": \"<string>\"\n  },\n  \"pricing\": {\n    \"currency\": \"<string>\",\n    \"amount\": 123\n  },\n  \"metadata\": {\n    \"homepage\": \"<string>\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/servers")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"version\": \"<string>\",\n  \"description\": \"<string>\",\n  \"author\": \"<string>\",\n  \"lang\": \"<string>\",\n  \"license\": \"<string>\",\n  \"entrypoint\": \"<string>\",\n  \"repository\": {\n    \"type\": \"<string>\",\n    \"url\": \"<string>\"\n  },\n  \"pricing\": {\n    \"currency\": \"<string>\",\n    \"amount\": 123\n  },\n  \"metadata\": {\n    \"homepage\": \"<string>\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/servers")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"<string>\",\n  \"version\": \"<string>\",\n  \"description\": \"<string>\",\n  \"author\": \"<string>\",\n  \"lang\": \"<string>\",\n  \"license\": \"<string>\",\n  \"entrypoint\": \"<string>\",\n  \"repository\": {\n    \"type\": \"<string>\",\n    \"url\": \"<string>\"\n  },\n  \"pricing\": {\n    \"currency\": \"<string>\",\n    \"amount\": 123\n  },\n  \"metadata\": {\n    \"homepage\": \"<string>\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "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
    }
  }
}

{
  "status": "error",
  "detail": "Validation failed: name must be lowercase with hyphens only"
}

{
  "status": "error",
  "detail": "Authentication token is required"
}

{
  "status": "error",
  "detail": "Server with this name already exists"
}

{
  "status": "error",
  "detail": "Security scan detected critical vulnerabilities"
}

POST

servers

Create Server

curl --request POST \
  --url https://api.example.com/servers \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "version": "<string>",
  "description": "<string>",
  "author": "<string>",
  "lang": "<string>",
  "license": "<string>",
  "entrypoint": "<string>",
  "repository": {
    "type": "<string>",
    "url": "<string>"
  },
  "pricing": {
    "currency": "<string>",
    "amount": 123
  },
  "metadata": {
    "homepage": "<string>"
  }
}
'

import requests

url = "https://api.example.com/servers"

payload = {
    "name": "<string>",
    "version": "<string>",
    "description": "<string>",
    "author": "<string>",
    "lang": "<string>",
    "license": "<string>",
    "entrypoint": "<string>",
    "repository": {
        "type": "<string>",
        "url": "<string>"
    },
    "pricing": {
        "currency": "<string>",
        "amount": 123
    },
    "metadata": { "homepage": "<string>" }
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: '<string>',
    version: '<string>',
    description: '<string>',
    author: '<string>',
    lang: '<string>',
    license: '<string>',
    entrypoint: '<string>',
    repository: {type: '<string>', url: '<string>'},
    pricing: {currency: '<string>', amount: 123},
    metadata: {homepage: '<string>'}
  })
};

fetch('https://api.example.com/servers', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/servers",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => '<string>',
    'version' => '<string>',
    'description' => '<string>',
    'author' => '<string>',
    'lang' => '<string>',
    'license' => '<string>',
    'entrypoint' => '<string>',
    'repository' => [
        'type' => '<string>',
        'url' => '<string>'
    ],
    'pricing' => [
        'currency' => '<string>',
        'amount' => 123
    ],
    'metadata' => [
        'homepage' => '<string>'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/servers"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"version\": \"<string>\",\n  \"description\": \"<string>\",\n  \"author\": \"<string>\",\n  \"lang\": \"<string>\",\n  \"license\": \"<string>\",\n  \"entrypoint\": \"<string>\",\n  \"repository\": {\n    \"type\": \"<string>\",\n    \"url\": \"<string>\"\n  },\n  \"pricing\": {\n    \"currency\": \"<string>\",\n    \"amount\": 123\n  },\n  \"metadata\": {\n    \"homepage\": \"<string>\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/servers")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"version\": \"<string>\",\n  \"description\": \"<string>\",\n  \"author\": \"<string>\",\n  \"lang\": \"<string>\",\n  \"license\": \"<string>\",\n  \"entrypoint\": \"<string>\",\n  \"repository\": {\n    \"type\": \"<string>\",\n    \"url\": \"<string>\"\n  },\n  \"pricing\": {\n    \"currency\": \"<string>\",\n    \"amount\": 123\n  },\n  \"metadata\": {\n    \"homepage\": \"<string>\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/servers")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"<string>\",\n  \"version\": \"<string>\",\n  \"description\": \"<string>\",\n  \"author\": \"<string>\",\n  \"lang\": \"<string>\",\n  \"license\": \"<string>\",\n  \"entrypoint\": \"<string>\",\n  \"repository\": {\n    \"type\": \"<string>\",\n    \"url\": \"<string>\"\n  },\n  \"pricing\": {\n    \"currency\": \"<string>\",\n    \"amount\": 123\n  },\n  \"metadata\": {\n    \"homepage\": \"<string>\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "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
    }
  }
}

{
  "status": "error",
  "detail": "Validation failed: name must be lowercase with hyphens only"
}

{
  "status": "error",
  "detail": "Authentication token is required"
}

{
  "status": "error",
  "detail": "Server with this name already exists"
}

{
  "status": "error",
  "detail": "Security scan detected critical vulnerabilities"
}

Endpoint

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

Authentication

Required

This endpoint requires authentication. Include your Firebase JWT token in the Authorization header.

You must be authenticated to create servers

Request Body

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

string

required

Semantic version number. Format: MAJOR.MINOR.PATCH (e.g., 1.0.0, 2.3.1)

string

required

Clear description of your server’s functionality. Length: 20-500 characters

string

required

Your name or organization name

string

required

Programming language. Allowed values: python, javascript, typescript, go, rust

string

required

Software license. Common values: MIT, Apache-2.0, GPL-3.0, BSD-3-Clause, ISC

string

required

Main file that starts your server. Examples: main.py, index.js, server.ts, main.go

object

required

Git repository information

Show properties

string

default:"git"

Repository type (usually "git")

string

required

Public repository URL. Must be publicly accessible and contain MCP server code. Example: https://github.com/username/repo-name

object

required

Pricing configuration

Show properties

string

required

Three-letter currency code. Examples: INR, USD, EUR

number

required

Price amount (use 0 for free servers). Range: 0 to 99999

object

Optional additional metadata

Show properties

string

Project homepage URL. Example: https://weather-mcp.dev

Response

string

"success" on success, "error" on failure

string

Human-readable confirmation message

object

The created server object (same structure as the Get Server response)

Examples

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"
    }
  }'

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);
}

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']}")

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"])
}
}

Response Examples

{
  "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
    }
  }
}

{
  "status": "error",
  "detail": "Validation failed: name must be lowercase with hyphens only"
}

{
  "status": "error",
  "detail": "Authentication token is required"
}

{
  "status": "error",
  "detail": "Server with this name already exists"
}

{
  "status": "error",
  "detail": "Security scan detected critical vulnerabilities"
}

Deployment Process

After creating a server, SuperBox follows this workflow:

Repository Validation

Clone the repository, verify the structure and entrypoint, and check for required files.

Security Scanning

Run SonarCloud, tool discovery, Snyk, GitGuardian, and Bandit (for Python servers).

Servers with critical security issues will be rejected

Registry Storage

Upload metadata to R2 registry, store repository URL and configuration, and generate the server manifest.

Ready

The server is immediately discoverable in the registry once the response is returned.

Repository Requirements

Python Servers

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.

JavaScript/TypeScript Servers

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.

Go Servers

Required files:

main.go or specified entrypoint
go.mod
README.md (recommended)

Best Practices

Test Locally First

Test your server thoroughly before submitting to the registry

Follow Semver

Use semantic versioning: MAJOR.MINOR.PATCH

Write Good Descriptions

Clear descriptions help users understand your server’s purpose

Security First

Never commit secrets or API keys to your repository

Document Well

Include a comprehensive README with usage examples

Choose Appropriate License

Select a license that matches your intentions

Common Errors

Invalid Server Name

Error: name must be lowercase with hyphens onlyUse only lowercase letters, numbers, and hyphens: my-awesome-server (valid), MyAwesomeServer (invalid)

Repository Not Found

Error: Unable to access Git repositoryEnsure the repository is public and the URL is correct.

Missing Entrypoint

Error: Entry point file not found in repositoryEnsure the file specified in entrypoint exists in your repository root.

Security Scan Failed

Error: Security scan detected critical vulnerabilitiesRemove hardcoded secrets/API keys, fix code vulnerabilities, and update dependencies with known vulnerabilities.

Name Already Taken

Error: Server with this name already existsChoose a different, unique name or add your username as a prefix: username-server-name

Getting Started

Core Concepts

Infrastructure

Backend

Frontend

REST API

Servers API

Auth API

CLI

CLI Commands

Create Server

Endpoint

Authentication

Request Body

Response

Examples

Response Examples

Deployment Process

Repository Requirements

Best Practices

Test Locally First

Follow Semver

Write Good Descriptions

Security First

Document Well

Choose Appropriate License

Common Errors

​Endpoint

​Authentication

​Request Body

​Response

​Examples

​Response Examples

​Deployment Process

​Repository Requirements

​Best Practices

Test Locally First

Follow Semver

Write Good Descriptions

Security First

Document Well

Choose Appropriate License

​Common Errors

Endpoint

Authentication

Request Body

Response

Examples

Response Examples

Deployment Process

Repository Requirements

Best Practices

Common Errors