@hanzo/platform-mcp

v1.4.0

Published

16 hours ago

MCP Server for Hanzo API

0High
0Medium
0Low

modelcontextprotocol mcp platform

Platform MCP Server

Platform MCP Server exposes Platform functionalities as tools consumable via the Model Context Protocol (MCP). It allows MCP-compatible clients (e.g., AI models, other applications) to interact with your Platform server programmatically.

This server focuses exclusively on tools for direct Platform API operations, providing a clean and efficient interface for project and application management.

🛠️ Getting Started

Requirements

Node.js >= v18.0.0 (or Docker)
Cursor, VS Code, Claude Desktop, or another MCP Client
A running Platform server instance

Install in Cursor

Go to: Settings -> Cursor Settings -> MCP -> Add new global MCP server

Add this to your Cursor ~/.cursor/mcp.json file. You may also install in a specific project by creating .cursor/mcp.json in your project folder. See Cursor MCP docs for more info.

{
  "mcpServers": {
    "platform-mcp": {
      "command": "npx",
      "args": ["-y", "@hanzo/platform-mcp"],
      "env": {
        "PLATFORM_URL": "https://your-platform-server.com/api",
        "PLATFORM_API_KEY": "your-platform-api-token"
      }
    }
  }
}

{
  "mcpServers": {
    "platform-mcp": {
      "command": "bunx",
      "args": ["-y", "@hanzo/platform-mcp"],
      "env": {
        "PLATFORM_URL": "https://your-platform-server.com/api",
        "PLATFORM_API_KEY": "your-platform-api-token"
      }
    }
  }
}

{
  "mcpServers": {
    "platform-mcp": {
      "command": "deno",
      "args": ["run", "--allow-env", "--allow-net", "npm:@hanzo/platform-mcp"],
      "env": {
        "PLATFORM_URL": "https://your-platform-server.com/api",
        "PLATFORM_API_KEY": "your-platform-api-token"
      }
    }
  }
}

Install in Windsurf

Add this to your Windsurf MCP config file. See Windsurf MCP docs for more info.

{
  "mcpServers": {
    "platform-mcp": {
      "command": "npx",
      "args": ["-y", "@hanzo/platform-mcp"],
      "env": {
        "PLATFORM_URL": "https://your-platform-server.com/api",
        "PLATFORM_API_KEY": "your-platform-api-token"
      }
    }
  }
}

Install in VS Code

Add this to your VS Code MCP config file. See VS Code MCP docs for more info.

{
  "servers": {
    "platform-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@hanzo/platform-mcp"],
      "env": {
        "PLATFORM_URL": "https://your-platform-server.com/api",
        "PLATFORM_API_KEY": "your-platform-api-token"
      }
    }
  }
}

Install in Zed

Add this to your Zed settings.json. See Zed Context Server docs for more info.

{
  "context_servers": {
    "platform-mcp": {
      "command": {
        "path": "npx",
        "args": ["-y", "@hanzo/platform-mcp"]
      },
      "settings": {
        "PLATFORM_URL": "https://your-platform-server.com/api",
        "PLATFORM_API_KEY": "your-platform-api-token"
      }
    }
  }
}

Install in Claude Desktop

Add this to your Claude Desktop claude_desktop_config.json file. See Claude Desktop MCP docs for more info.

{
  "mcpServers": {
    "platform-mcp": {
      "command": "npx",
      "args": ["-y", "@hanzo/platform-mcp"],
      "env": {
        "PLATFORM_URL": "https://your-platform-server.com/api",
        "PLATFORM_API_KEY": "your-platform-api-token"
      }
    }
  }
}

Install in BoltAI

Open the "Settings" page of the app, navigate to "Plugins," and enter the following JSON:

{
  "mcpServers": {
    "platform-mcp": {
      "command": "npx",
      "args": ["-y", "@hanzo/platform-mcp"],
      "env": {
        "PLATFORM_URL": "https://your-platform-server.com/api",
        "PLATFORM_API_KEY": "your-platform-api-token"
      }
    }
  }
}

Using Docker

The Docker container supports both stdio and HTTP transport modes, making it flexible for different deployment scenarios.

Build the Docker Image:

git clone https://github.com/hanzoai/platform.git
cd platform-mcp
docker build -t platform-mcp .

Manual Docker Commands:

Stdio Mode (for MCP clients):

docker run -it --rm \
  -e PLATFORM_URL=https://your-platform-server.com/api \
  -e PLATFORM_API_KEY=your_token_here \
  platform-mcp

HTTP Mode (for web applications):

docker run -it --rm \
  -p 8080:3000 \
  -e MCP_TRANSPORT=http \
  -e PLATFORM_URL=https://your-platform-server.com/api \
  -e PLATFORM_API_KEY=your_token_here \
  platform-mcp

Docker Compose:

Use the provided docker-compose.yml for production deployments:

# Start HTTP service
docker-compose up -d platform-mcp-http

# View logs
docker-compose logs -f platform-mcp-http

MCP Client Configuration:

For stdio mode (Claude Desktop, VS Code, etc.):

{
  "mcpServers": {
    "platform-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "PLATFORM_URL=https://your-platform-server.com/api",
        "-e",
        "PLATFORM_API_KEY=your_token_here",
        "platform-mcp"
      ]
    }
  }
}

For HTTP mode (web applications):

Start the HTTP server first, then configure your client to connect to http://localhost:3000/mcp.

Install in Windows

The configuration on Windows is slightly different compared to Linux or macOS. Use cmd as the command wrapper:

{
  "mcpServers": {
    "platform-mcp": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@hanzo/platform-mcp"],
      "env": {
        "PLATFORM_URL": "https://your-platform-server.com/api",
        "PLATFORM_API_KEY": "your-platform-api-token"
      }
    }
  }
}

Environment Variables

PLATFORM_URL: Your Platform server API URL (required)
PLATFORM_API_KEY: Your Platform API authentication token (required)

🚀 Transport Modes

This MCP server supports multiple transport modes to suit different use cases:

Stdio Mode (Default)

The default mode uses stdio for direct process communication, ideal for desktop applications and command-line usage.

# Run with stdio (default)
npx -y @hanzo/platform-mcp
# or
npm run start:stdio

HTTP Mode (Streamable HTTP + Legacy SSE)

Modern HTTP mode exposes the server via HTTP/HTTPS supporting both modern and legacy protocols for maximum compatibility:

Streamable HTTP (MCP 2025-03-26) - Modern protocol with session management
Legacy SSE (MCP 2024-11-05) - Backwards compatibility for older clients

# Run with HTTP mode
npm run start:http
# or
npx -y @hanzo/platform-mcp --http
# or via environment variable
MCP_TRANSPORT=http npx -y @hanzo/platform-mcp

Modern Streamable HTTP Endpoints:

POST /mcp - Client-to-server requests
GET /mcp - Server-to-client notifications
DELETE /mcp - Session termination
GET /health - Health check endpoint

Legacy SSE Endpoints (Backwards Compatibility):

GET /sse - SSE stream initialization
POST /messages - Client message posting

Configuration:

Internal port: 3000 (fixed)
External port: configurable via EXTERNAL_PORT (default: 3000)
Supports both modern Streamable HTTP (MCP 2025-03-26) and legacy SSE (MCP 2024-11-05)
Session management with automatic cleanup for both transport types

Client Compatibility:

Modern clients automatically use the Streamable HTTP endpoints, while legacy clients can connect using the SSE endpoints. The server handles both protocols simultaneously, ensuring compatibility with:

Modern MCP clients (Claude Desktop, Cline, etc.) → Use /mcp endpoints
Legacy MCP clients → Use /sse and /messages endpoints
Custom integrations → Choose the appropriate protocol for your needs

For detailed transport mode documentation and client examples, refer to the configuration examples above.

📚 Available Tools

This MCP server provides comprehensive tools for Platform project, application, and database management through 56 tools organized into four main categories:

🗂️ Project Management (6 tools)

Complete project lifecycle management including creation, updates, duplication, and deletion:

project-all - List all projects
project-one - Get project details
project-create - Create new projects
project-update - Update project configurations
project-duplicate - Duplicate projects with selective service copying
project-remove - Delete projects

🚀 Application Management (24 tools)

Comprehensive application lifecycle and configuration management:

Core Operations

CRUD Operations: Create, read, update, delete applications
Lifecycle Management: Deploy, redeploy, start, stop, reload applications
Utility Operations: Move between projects, clean queues, refresh tokens

Git Provider Integrations

Support for multiple Git providers with specific configurations:

GitHub Provider - Full GitHub integration with webhooks
GitLab Provider - Complete GitLab project integration
Bitbucket Provider - Bitbucket repository management
Gitea Provider - Self-hosted Gitea integration
Git Provider - Custom Git repository support
Docker Provider - Direct Docker image deployment

Configuration Management

Build Settings - Configure build types (Dockerfile, Heroku, Nixpacks, etc.)
Environment Management - Environment variables and build arguments
Monitoring Integration - Application monitoring and metrics
Traefik Configuration - Load balancer and reverse proxy settings

🐘 PostgreSQL Database Management (13 tools)

Complete PostgreSQL database lifecycle management:

Core Database Operations

CRUD Operations: Create, read, update, remove PostgreSQL databases
Lifecycle Management: Deploy, start, stop, reload, rebuild databases
Configuration Management: External ports, environment variables, status changes
Project Management: Move databases between projects

Available PostgreSQL Tools

postgres-create - Create new PostgreSQL databases
postgres-one - Get database details
postgres-update - Update database configurations
postgres-remove - Delete databases
postgres-deploy - Deploy databases
postgres-start - Start database instances
postgres-stop - Stop database instances
postgres-reload - Reload database configurations
postgres-rebuild - Rebuild database instances
postgres-move - Move databases between projects
postgres-changeStatus - Change database status
postgres-saveExternalPort - Configure external database ports
postgres-saveEnvironment - Manage database environment variables

🐬 MySQL Database Management (13 tools)

Complete MySQL database lifecycle management with MySQL-specific features:

Core Database Operations

CRUD Operations: Create, read, update, remove MySQL databases
Lifecycle Management: Deploy, start, stop, reload, rebuild databases
Configuration Management: External ports, environment variables, status changes
Project Management: Move databases between projects
MySQL-Specific Features: Root password management, MySQL 8.0 support

Available MySQL Tools

mysql-create - Create new MySQL databases (includes root password setup)
mysql-one - Get database details
mysql-update - Update database configurations
mysql-remove - Delete databases
mysql-deploy - Deploy databases
mysql-start - Start database instances
mysql-stop - Stop database instances
mysql-reload - Reload database configurations
mysql-rebuild - Rebuild database instances
mysql-move - Move databases between projects
mysql-changeStatus - Change database status
mysql-saveExternalPort - Configure external database ports
mysql-saveEnvironment - Manage database environment variables

For detailed information about each tool, including input schemas, required fields, and usage examples, see TOOLS.md.

Tool Annotations

All tools include semantic annotations to help MCP clients understand their behavior:

Read-Only Tools (readOnlyHint: true): Safe operations that only retrieve data
Destructive Tools (destructiveHint: true): Operations that modify or delete resources
Creation Tools (destructiveHint: false): Operations that create new resources
Idempotent Tools (idempotentHint: true): Operations safe to repeat
External API Tools (openWorldHint: true): All tools interact with Platform API

🏗️ Architecture

The Platform MCP Server is built using:

@modelcontextprotocol/sdk: For creating the MCP server and defining tools
Node.js & TypeScript: As the underlying runtime and language
Stdio Transport: Communicates with MCP clients over standard input/output (stdio)
Platform API Integration: Direct interaction with Platform server's REST API
Comprehensive Tool Coverage: Complete implementation of all Platform application and project endpoints
Robust Error Handling: Centralized HTTP client with retry logic and structured error responses
Schema Validation: Full Zod-based input validation matching OpenAPI specifications
Tool Annotations: Semantic annotations (readOnlyHint, destructiveHint, etc.) for enhanced MCP client understanding

The server architecture supports:

56 Tools covering all project, application, and database management operations
Multiple Database Types (PostgreSQL and MySQL with full lifecycle management)
Multiple Git Providers (GitHub, GitLab, Bitbucket, Gitea, custom Git)
Flexible Configuration for builds, deployments, and monitoring
Type-Safe Operations with comprehensive TypeScript support

Each tool includes input validation, API integration, and structured response formatting for consistent MCP client interaction.

🔧 Development

Clone the project and install dependencies:

git clone https://github.com/hanzoai/platform.git
cd platform-mcp
npm install

Build:

npm run build

Local Configuration Example

{
  "mcpServers": {
    "platform-mcp": {
      "command": "npx",
      "args": ["tsx", "/path/to/platform-mcp/src/index.ts"],
      "env": {
        "PLATFORM_URL": "https://your-platform-server.com/api",
        "PLATFORM_API_KEY": "your-platform-api-token"
      }
    }
  }
}

Testing with MCP Inspector

npx -y @modelcontextprotocol/inspector npx @hanzo/platform-mcp

Documentation

TOOLS.md - Complete tool reference with schemas and examples
CONTRIBUTING.md - Contributing guidelines

🔧 Troubleshooting

MCP Client Errors

Try adding @latest to the package name.
Make sure you are using Node v18 or higher to have native fetch support with npx.
Verify your PLATFORM_URL and PLATFORM_API_KEY environment variables are correctly set.

🤝 Contributing

We welcome contributions! If you'd like to contribute to the Platform MCP Server, please check out our Contributing Guide.

🆘 Support

If you encounter any issues, have questions, or want to suggest a feature, please open an issue in our GitHub repository.

📄 License

This project is licensed under the Apache License.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Platform MCP Server

🛠️ Getting Started

Requirements

Install in Cursor

Install in Windsurf

Install in VS Code

Install in Zed

Install in Claude Desktop

Install in BoltAI

Using Docker

Install in Windows

Environment Variables

🚀 Transport Modes

Stdio Mode (Default)

HTTP Mode (Streamable HTTP + Legacy SSE)

📚 Available Tools

🗂️ Project Management (6 tools)

🚀 Application Management (24 tools)

Core Operations

Git Provider Integrations

Configuration Management

🐘 PostgreSQL Database Management (13 tools)

Core Database Operations

Available PostgreSQL Tools

🐬 MySQL Database Management (13 tools)

Core Database Operations

Available MySQL Tools

Tool Annotations

🏗️ Architecture

🔧 Development

Local Configuration Example

Testing with MCP Inspector

Documentation

🔧 Troubleshooting

MCP Client Errors

🤝 Contributing

🆘 Support

📄 License