# ezForge Platform Documentation — Concise Summary for AI Readers
#
# This file is manually maintained. Update it when page content changes.
# A companion llms-full.txt contains complete page content.
# If Mintlify adds native llms.txt / llms-full.txt auto-generation,
# both files should be deleted and replaced by the auto-generated output.
#
# Last updated: 2026-03-20

# ezForge Platform Documentation

## What is ezForge?

ezForge Platform is a managed cloud platform for deploying Model Context Protocol (MCP) servers. It handles infrastructure, authentication, and deployment so you can focus on building MCP tools.

## Key facts

- **Base API URL:** https://api.ezforge.ai/v1
- **Authentication:** Bearer token (`Authorization: Bearer ezf_live_<key>`)
- **MCP server subdomains:** `{slug}.mcp.ezforge.ai`
- **CLI install:** `brew install ezforgeai/tap/ezforge`
- **CLI deploy command:** `ezforge deploy`
- **Supported regions:** ord (Chicago), iad (Ashburn), lax (Los Angeles), ams (Amsterdam), syd (Sydney)
- **MCP auth:** OAuth 2.1 with mandatory PKCE (S256); BYOA supported

## Core concepts

### Projects
Workspaces that group servers, API keys, and billing. Create with `ezforge project create <name>`.

### Servers
Deployed MCP instances running in Firecracker microVMs. Each gets a live HTTPS subdomain. Status values: provisioning, running, stopped, error, deleted.

### Deployments
Each `ezforge deploy` creates a deployment. Pipeline: build → Trivy scan → push → provision VM → health check → traffic swap. Auto-rollback on failure. Last 10 deployments kept for rollback (3 on Free tier).

### API Keys
Scoped credentials with prefixes `ezf_live_` (prod) or `ezf_test_` (test). Scopes: servers:read, servers:write, deployments:read, deployments:write, logs:read, metrics:read, billing:read.

## REST API endpoints

- GET /v1/projects — list projects
- POST /v1/projects — create project
- GET /v1/projects/:id — get project
- PATCH /v1/projects/:id — update project
- DELETE /v1/projects/:id — delete project
- GET /v1/projects/:id/servers — list servers
- POST /v1/projects/:id/servers — create server
- GET /v1/servers/:id — get server
- PATCH /v1/servers/:id — update server
- DELETE /v1/servers/:id — delete server
- GET /v1/servers/:id/metrics — get server metrics
- POST /v1/servers/:serverId/deploy — trigger deployment
- GET /v1/servers/:serverId/deployments — list deployments
- POST /v1/servers/:serverId/rollback — roll back
- GET /v1/servers/:serverId/logs — stream logs (SSE)
- GET /v1/projects/:id/keys — list API keys
- POST /v1/projects/:id/keys — create API key
- DELETE /v1/keys/:id — delete API key
- GET /v1/billing — get billing status
- POST /v1/billing/subscribe — subscribe/upgrade plan
- POST /v1/auth/signup — sign up
- POST /v1/auth/login — log in
- POST /v1/auth/logout — log out
- GET /v1/health — platform health check

## CLI commands

- ezforge auth login [--api-key <key>]
- ezforge auth logout
- ezforge auth status
- ezforge deploy [--image <uri>] [--server <name>] [--region <r>]
- ezforge servers list
- ezforge servers status <name>
- ezforge servers stop <name>
- ezforge servers start <name>
- ezforge servers delete <name>
- ezforge logs <name> [--level <l>] [--since <t>]
- ezforge rollback <name> --version <deployment-id>
- ezforge env set <server> KEY=value
- ezforge env list <server>
- ezforge env unset <server> KEY
- ezforge project create <name>
- ezforge project list
- ezforge project use <name>
- ezforge project delete <name>
- ezforge project create-key <project> --name <n> --scopes <s>
- ezforge billing upgrade --plan <developer|pro>
- ezforge billing status

## MCP server requirements

Your MCP server container must:
1. Listen on PORT environment variable (default 8080)
2. Implement GET /healthz returning HTTP 200 with JSON body
3. Implement GET /sse for MCP SSE transport
4. Implement POST /message for MCP message handling

## Server config (ezforge.toml)

```toml
[project]
name = "my-project"
[server]
name = "my-server"
region = "ord"
cpu = "shared-1x"
memory = "256mb"
[health]
path = "/healthz"
timeout = 30
[deploy]
auto_rollback = true
retention_count = 10
```

## Billing plans

- Free: $0/mo, 1 server, ord only, 1000 req/mo, auto-stop required
- Developer: $29/mo, 10 servers, all regions, unlimited requests
- Pro: $99/mo, unlimited servers, custom domains, priority support

## MCP OAuth 2.1

Servers are protected by OAuth 2.1 + PKCE (mandatory S256). Two modes:
- ezforge_managed: ezForge acts as auth server (default)
- byoa: bring your own OAuth 2.1 provider

Token lifetimes: access token 15 min, refresh token 30 days (rotated on use), auth code 5 min single-use.

MCP scopes: mcp:read, mcp:write, mcp:execute, offline_access.

Protected resource metadata: GET /.well-known/oauth-protected-resource on each server.

## Templates

- Node.js/TypeScript: https://github.com/ezforgeai/template-nodejs-mcp-server
- Python: https://github.com/ezforgeai/template-python-mcp-server

## Links

- Dashboard: https://app.ezforge.ai
- API: https://api.ezforge.ai
- Status: https://status.ezforge.ai
- GitHub: https://github.com/ezforgeai