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": {
    "tags": [
      {}
    ],
    "homepage": "<string>"
  }
}
'
{
  "success": true,
  "data": {
    "name": "weather-mcp",
    "version": "1.0.0",
    "status": "scanning",
    "securityScanId": "scan_abc123def456",
    "estimatedTime": 90,
    "url": "https://superbox-ai.vercel.app/server/weather-mcp",
    "message": "Server created successfully. Security scanning in progress."
  },
  "meta": {
    "timestamp": "2025-12-09T10:30:00Z",
    "version": "v1",
    "requestId": "req_xyz789"
  }
}

​
Endpoint

​
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, my-awesome-server
​
version
string
required
Semantic version number Format: MAJOR.MINOR.PATCH (e.g., 1.0.0, 2.3.1) Examples: 1.0.0, 2.1.5, 0.9.0-beta
​
description
string
required
Clear description of your server’s functionality Length: 20-500 characters Example: “Get real-time weather information and forecasts for any location using OpenWeatherMap API”
​
author
string
required
Your name or organization name Example: “Areeb Ahmed”, “SuperBox Team”
​
lang
string
required
Programming language of your server 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

​
success
boolean
Indicates if the server was created successfully
​
data
object
Created server information

​
Examples

cURL
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": "Amartya Anand",
    "lang": "python",
    "license": "MIT",
    "entrypoint": "main.py",
    "repository": {
      "type": "git",
      "url": "https://github.com/areeb/weather-mcp"
    },
    "pricing": {
      "currency": "USD",
      "amount": 0
    },
    "metadata": {
      "tags": ["weather", "api", "forecast"],
      "homepage": "https://weather-mcp.dev"
    }
  }'

​
Response Examples

{
  "success": true,
  "data": {
    "name": "weather-mcp",
    "version": "1.0.0",
    "status": "scanning",
    "securityScanId": "scan_abc123def456",
    "estimatedTime": 90,
    "url": "https://superbox-ai.vercel.app/server/weather-mcp",
    "message": "Server created successfully. Security scanning in progress."
  },
  "meta": {
    "timestamp": "2025-12-09T10:30:00Z",
    "version": "v1",
    "requestId": "req_xyz789"
  }
}

​
Deployment Process

After creating a server, SuperBox follows this workflow:
1

Repository Validation

  • Clone the repository - Verify structure and entrypoint - Check for required files
2

Security Scanning

  • SonarCloud: Code quality and vulnerabilities - GitGuardian: Secrets detection - Bandit: Python security audit (if applicable)
    Servers with critical security issues will be rejected
3

Container Building

  • Build Docker container image - Install dependencies - Configure runtime environment
4

Lambda Deployment

  • Push image to Amazon ECR - Create Lambda function - Configure execution settings
5

Registry Update

  • Add server to S3 registry - Generate metadata - Make server discoverable

​
Repository Requirements

Your repository must meet these requirements:
Required files: - main.py or specified entrypoint - requirements.txt or pyproject.toml - README.md (recommended) Structure: my-mcp-server/ ├── main.py ├── requirements.txt ├── README.md └── src/ └── tools/ Dependencies: - Must include mcp package - All dependencies must be installable via pip
Required files: - index.js/index.ts or specified entrypoint - package.json - README.md (recommended) Structure: my-mcp-server/ ├── index.ts ├── package.json ├── tsconfig.json (for TypeScript) ├── README.md └── src/ └── tools/ Dependencies: - Must include @modelcontextprotocol/sdk - All dependencies must be on npm registry
Required files: - main.go or specified entrypoint - go.mod - README.md (recommended) Structure: my-mcp-server/ ├── main.go ├── go.mod ├── go.sum ├── README.md └── pkg/ └── tools/

​
Best Practices

Validate Locally

Test your server thoroughly before deploying to SuperBox

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 & Solutions

Error: Server name must be lowercase with hyphens only Solution: Use only lowercase letters, numbers, and hyphens - my-awesome-server (valid) - MyAwesomeServer (invalid) - my_awesome_server (invalid)
Error: Unable to access Git repository Solutions: - Ensure repository is public - Check URL is correct - Verify repository exists - Wait a few minutes if just created
Error: Entry point file not found in repository Solution: Ensure the file specified in entrypoint exists in your repository root
Error: Security scan detected critical vulnerabilities Solutions: - Remove any hardcoded secrets/API keys - Fix code vulnerabilities reported by scanners - Update dependencies with known vulnerabilities - Review security report details
Error: Server with this name already exists Solutions: - Choose a different, unique name - Contact existing server owner for transfer - Add your username as prefix: username-server-name

​
Monitoring Deployment

After creating a server, monitor its status: 
JavaScript
async function waitForDeployment(serverName) {
  const checkStatus = async () => {
    const response = await fetch(
      `https://api.superbox.ai/api/v1/servers/${serverName}`,
      {
        headers: {
          'Authorization': `Bearer ${process.env.SUPERBOX_API_TOKEN}`
        }
      }
    );
    const { data } = await response.json();
    return data.status;
  };
  
  let status = 'scanning';
  while (status !== 'ready' && status !== 'failed') {
    await new Promise(resolve => setTimeout(resolve, 5000)); // Wait 5s
    status = await checkStatus();
    console.log(`Status: ${status}`);
  }
  
  return status === 'ready';
}

// Usage
const success = await waitForDeployment('weather-mcp');
if (success) {
console.log('✓ Server deployed successfully!');
} else {
console.error('✗ Deployment failed');
}

​
Pricing Your Server

Set pricing.amount to 0 for free serversBenefits:
  • Maximum reach and adoption
  • Community contributions
  • Portfolio building
Ideal for:
  • Open source projects
  • Learning/educational tools
  • Community tools

List Servers

View all available servers

Get Server

View your server details

Update Server

Modify server metadata
Ready to deploy your first MCP server? Follow the examples above and you’ll have your server live in minutes!