Skip to main content
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>"
  }
}
'
{
  "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
    }
  }
}

​
Endpoint

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

​
Authentication

This endpoint requires authentication. Include your Firebase JWT token in the Authorization header.
You must be authenticated to create servers

​
Request Body

​
name
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
​
version
string
required
Semantic version number. Format: MAJOR.MINOR.PATCH (e.g., 1.0.0, 2.3.1)
​
description
string
required
Clear description of your server’s functionality. Length: 20-500 characters
​
author
string
required
Your name or organization name
​
lang
string
required
Programming language. Allowed values: python, javascript, typescript, go, rust
​
license
string
required
Software license. Common values: MIT, Apache-2.0, GPL-3.0, BSD-3-Clause, ISC
​
entrypoint
string
required
Main file that starts your server. Examples: main.py, index.js, server.ts, main.go
​
repository
object
required
Git repository information
​
pricing
object
required
Pricing configuration
​
metadata
object
Optional additional metadata

​
Response

​
status
string
"success" on success, "error" on failure
​
message
string
Human-readable confirmation message
​
server
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"
    }
  }'

​
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
    }
  }
}

​
Deployment Process

After creating a server, SuperBox follows this workflow:
1

Repository Validation

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

Security Scanning

Run SonarCloud, tool discovery, Snyk, GitGuardian, and Bandit (for Python servers).
Servers with critical security issues will be rejected
3

Registry Storage

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

Ready

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

​
Repository Requirements

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

Error: name must be lowercase with hyphens onlyUse only lowercase letters, numbers, and hyphens: my-awesome-server (valid), MyAwesomeServer (invalid)
Error: Unable to access Git repositoryEnsure the repository is public and the URL is correct.
Error: Entry point file not found in repositoryEnsure the file specified in entrypoint exists in your repository root.
Error: Security scan detected critical vulnerabilitiesRemove hardcoded secrets/API keys, fix code vulnerabilities, and update dependencies with known vulnerabilities.
Error: Server with this name already existsChoose a different, unique name or add your username as a prefix: username-server-name