Partiri Cloud MCP Server
The Partiri Cloud MCP Server enables AI agents to manage cloud infrastructure on the Partiri PaaS platform, covering workspaces, projects, services, deployments, metrics, and billing.
User & Workspace Management
Retrieve the authenticated user's profile
List all workspaces the user has access to
Check a workspace's billing balance
Project Management
List projects within a workspace
Create new projects
Service Lifecycle Management
List, get details for, create, and update services
Preflight-validate service configurations before applying them
Deploy, pause, and unpause services
Deployments & Monitoring
List deployment jobs and track their status (open, in-progress, succeeded, failed, etc.)
Retrieve CPU, memory, and network usage metrics for services
Infrastructure & Pricing
Discover available compute pod types and deployment regions
Query pod and volume pricing for a region
Persistent Storage
List and get details for persistent volumes within a project
CLI Guidance
Get advisory instructions (not execution) for sensitive operations intentionally excluded from MCP tools — such as managing secrets, environment variables, volume lifecycle (create/detach/delete), and service teardown — to keep secrets out of the model context. These are handled via the local
partiriCLI.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Partiri Cloud MCP Server show my active deployments"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Partiri Cloud MCP Server
MCP server for the Partiri Cloud PaaS platform. Allows AI agents (Claude Code, VS Code, etc.) to manage workspaces, projects, services, deployments, and metrics through the Model Context Protocol.
Transports
The server supports two transport modes:
Transport | Use case | Set via |
stdio (default) | Local CLI / direct integration |
|
HTTP | Remote access with OAuth 2.1 |
|
Related MCP server: paperclip-mcp
Quick Start
npm install
npm run buildstdio (local)
PARTIRI_API_KEY=your-key npx tsx src/index.tsOr point your MCP client at the built binary:
{
"partiri": {
"type": "stdio",
"command": "node",
"args": ["dist/index.mjs"],
"env": { "PARTIRI_API_KEY": "your-key" }
}
}HTTP (remote)
MCP_TRANSPORT=http \
MCP_TOKEN_SECRET=$(openssl rand -hex 32) \
MCP_BASE_URL=https://your-domain.com \
PORT=3000 \
npx tsx src/index.tsThen configure your MCP client:
{
"partiri": {
"type": "http",
"url": "https://your-domain.com/mcp"
}
}No API key in the config — the OAuth 2.1 browser flow handles authentication.
Authentication
stdio
The API key is resolved in order:
PARTIRI_API_KEYenvironment variable~/.config/partiri/keyfile (written bypartiri auth)If the process is interactive (TTY attached and no CI environment detected),
browserLogin()opens a browser and waits for the user to authorizeOtherwise, throws a descriptive error with a link to docs
Headless / CI usage: set PARTIRI_API_KEY. In CI or non-TTY contexts step 3 is skipped and the server fails fast with a clear error rather than hanging on a browser prompt.
HTTP (OAuth 2.1)
The HTTP transport implements a full OAuth 2.1 authorization server. When a client like Claude Code connects, the flow is:
Client discovers endpoints via
/.well-known/oauth-protected-resource/mcpand/.well-known/oauth-authorization-serverClient dynamically registers via
POST /registerThe client opens
/authorize, which redirects the browser to the hosted Partiri sign-in page (PARTIRI_WEB_URL/cli-auth) with a shortstateand the server's publiccallbackURLAfter the user confirms, the sign-in page mints a Partiri API key and redirects it back to the server's
GET /callback, which validates the key against the Partiri APIThe server issues an encrypted authorization code (bound to the client's PKCE challenge and redirect URI) and redirects to the client, which exchanges it for access/refresh tokens
All subsequent MCP requests use
Authorization: Bearer <token>
Tokens are stateless — the API key is AES-256-GCM encrypted inside the token itself. No token database is needed.
Legacy x-api-key header authentication is also supported for backward compatibility with curl and non-OAuth clients.
Resource binding (RFC 8707)
Issued tokens are audience-bound to this server's canonical resource, MCP_BASE_URL + /mcp (e.g. https://mcp.partiri.cloud/mcp). A resource parameter naming any other server is rejected with invalid_target, and an access token whose audience names another server fails verification. Tokens issued before this claim existed remain valid until their natural expiry and are upgraded to audience-bound tokens on their next refresh.
The protected-resource metadata (RFC 9728) is served at both /.well-known/oauth-protected-resource/mcp and /.well-known/oauth-protected-resource, and every 401 carries a WWW-Authenticate header with a resource_metadata pointer so clients can discover the authorization server.
Environment Variables
Variable | Required | Default | Description |
| stdio only | — | API key for the Partiri REST API |
| No |
| Partiri API base URL (must be HTTPS) |
| No |
| Hosted Partiri web app URL (HTTP OAuth sign-in redirect) |
| No |
| API request timeout in seconds |
| No |
| Transport mode: |
| No |
| HTTP server port |
| HTTP prod | — | 32-byte hex key (64 chars) for token encryption. Auto-generated in dev with a warning. |
| HTTP prod |
| Public URL of the MCP server |
| No | — | Persistent dir for client registrations + token secret (survives restarts; single-replica) |
| No | — | Comma-separated OAuth redirect hosts allowed in addition to loopback |
| No | claude.ai, claude.com, chatgpt.com, chat.openai.com | Comma-separated browser Origins allowed on |
| HTTP prod |
| Trusted proxy IP(s)/CIDR(s) for client-IP rate limiting; set to your ingress so X-Forwarded-For can't be spoofed |
| No |
| Max concurrent MCP sessions |
| No |
| Max sessions per API key |
| No |
| Session inactivity timeout |
| No |
| When truthy, only read-only tools are registered |
| No | — | Comma-separated tool names to enable on top of the base set |
| No | — | Comma-separated tool names to remove (wins over allowlist) |
Available Tools
Tool | Description |
| List all workspaces the user has access to |
| Get the authenticated user's profile |
| List projects in a workspace |
| Create a new project |
| List available compute pods (catalogue only; custom sizes are excluded) |
| List available deployment regions |
| List services in a project |
| Get service details |
| Create a new service ( |
| Update service configuration |
| Preflight-validate a service config; optionally probe repo/registry reachability (needs |
| Trigger a new deployment |
| Pause a running service |
| Resume a paused service |
| List deployment jobs for a service |
| List persistent volumes in a project |
| Get details of a single volume |
| Get CPU usage metrics |
| Get memory usage metrics |
| Get network metrics |
| Get pod and volume pricing for a region (pass |
| Get the CPU/memory range, step grid, and rate card for a custom-sized pod |
| Get a workspace's billing balance |
| Advisory guidance for running the |
Deploy types and billing
Long-running types (webservice, static, private-service, worker) are billed a
flat monthly rate per pod, charged up front — total pods being replicaCount times
the number of regions.
A cronjob is metered instead: nothing is charged at creation, and each run is
debited on its actual duration (rounded up to the minute, 1-minute floor). An attached
volume is still charged a flat month on either model, so disk_monthly appears on both.
Cost objects returned by create_service and validate_service carry a billing_model
discriminator (flat_monthly or metered); update_service's cost_delta carries
current_billing_model and new_billing_model, so a delta stays meaningful across a
switch — converting a cronjob to a long-running type reports the full monthly charge it
starts paying, not zero. A cost object is omitted entirely when it cannot be computed;
absent means unknown, never free.
Suspending a recurring cronjob's schedule is done with pause_service /
unpause_service, not through update_service — the API owns that flag and keeps it in
step with the metered billing assignment.
CLI-only operations
To keep long-lived credentials out of the model context and irreversible
operations off the MCP surface, the following are not individual MCP tools.
You run them yourself with the locally-installed partiri CLI, which
authenticates independently of the MCP session. The use_partiri_cli tool does
not execute anything — it returns guidance for the command to run in your
own shell:
Workspace secrets — create / list / delete repository and registry secrets
Service environment variables —
partiri service env; values hold secrets (DB URLs, API keys), so they are never read or written through the MCP —create_service/update_servicedon't acceptenvandget_serviceomits itVolume lifecycle — create / attach / detach / delete / retry
Service teardown —
partiri service kill
Discover exact subcommands and flags at runtime (partiri llm guide,
partiri llm capabilities -j, or partiri <area> --help) rather than assuming
syntax. For credential values, pass them on stdin (e.g. --key-stdin) so they
stay out of the argument list and this context.
Project Structure
src/
index.ts Entry point (transport selection)
auth.ts API key resolution (env / file / browser login)
auth-login.ts Browser-based login flow for interactive stdio sessions
client.ts PartiriApiClient (HTTP, retry on 429)
server.ts MCP server creation, tool filtering, and tool registration
errors.ts Error formatting helpers
net-guard.ts SSRF / OAuth-redirect host classification (private/loopback/metadata)
http.ts HTTP transport (Express, OAuth, sessions)
oauth/
provider.ts OAuthServerProvider — authorize, token exchange, verification
client-store.ts Dynamic client registration (in-memory and file-backed)
crypto.ts AES-256-GCM token encryption/decryption
tools/
index.ts Tool aggregator
workspaces.ts Workspace tools
user.ts User tools
projects.ts Project tools
resources.ts Pod, region, pricing, custom-pod, and balance tools
cost.ts Shared cost math — decides flat monthly vs metered
service-rules.ts Shared create/validate rules (blocking vs advisory)
services.ts Service CRUD tools
validate.ts validate_service preflight tool (SSRF-guarded reachability probe)
deployments.ts Deploy, pause, unpause, and job-list tools
storage.ts Volume read tools (list_volumes, get_volume)
metrics.ts CPU, memory, network metrics tools
cli.ts use_partiri_cli advisory tool
resources/ Embedded MCP documentation resources
index.ts Resource registration
content/ Guides (getting started, services, deployments, …)Development
npm install
npm test # run tests (vitest)
npm run test:watch # watch mode
npm run dev # run with tsx (stdio)
npm run build # bundle to dist/Adding a New Tool
Add the API method to
src/client.tsAdd a tool definition and handler in the appropriate
src/tools/<domain>.tsThe tool is automatically registered via
tools/index.tsaggregation
Deployment
For production behind a reverse proxy (Cloudflare, nginx):
Set
MCP_TRANSPORT=httpGenerate a stable token secret:
openssl rand -hex 32Set
MCP_TOKEN_SECRETto the generated valueSet
MCP_BASE_URLto the public URL (e.g.https://mcp.partiri.cloud)Set
PARTIRI_API_URLif the API is not at the defaulthttps://api.partiri.cloudSet
MCP_TRUSTED_PROXIESto your ingress/proxy IP or CIDR (e.g.10.0.0.0/8)Deploy and expose port
3000(or setPORT)
Rate limiting keys on the client IP derived from X-Forwarded-For, which is only
trusted from the proxies named in MCP_TRUSTED_PROXIES (default: loopback only).
Set it to your real ingress range and ensure the proxy overwrites inbound
X-Forwarded-For — otherwise a client able to reach the server through a
trusted/loopback proxy could spoof its IP and bypass per-IP limits. The session
and client-registration stores are independently bounded (the API key is
validated before a session is created, and stores evict oldest-first), so
resource exhaustion and lockout are prevented even if IP limiting is
misconfigured.
Usage Examples
The following examples show realistic prompts an end user might give to an AI agent connected to this MCP server, and which tools each prompt exercises.
Inspect a service and check its resource usage
"Show me CPU and memory usage for my api service over the last hour."
Exercises: list_workspaces → list_projects → list_services → get_service → get_cpu_metrics, get_memory_metrics
Deploy a service and monitor progress
"Deploy the latest commit of the frontend service in my production project, then tell me when it succeeds."
Exercises: list_workspaces → list_projects → list_services → deploy_service → list_jobs
Create a new service from a Git repository
"List all services in my staging project and create a new Node.js web service from github.com/owner/repo on the main branch."
Exercises: list_workspaces → list_projects → list_services → list_pods → list_regions → create_service
Put a service in maintenance mode
"Enable maintenance mode on the checkout service while I push a hotfix."
Exercises: list_workspaces → list_projects → list_services → update_service
Support
For questions, bug reports, or integration help: support@partiri.cloud
Full documentation is available at https://partiri.cloud/documentation/mcp.
Privacy
This connector accesses workspace, project, service, deployment, log, and metrics data from your Partiri account on behalf of the authenticated user, and only that data. Secrets never reach the model context: environment variable values and secret references (env, fk_service_secret) are stripped from every tool response, and secret management is deliberately CLI-only. It does not maintain a token database — API keys are AES-256-GCM encrypted inside stateless OAuth tokens — and server-side session state is in-memory with a 30-minute inactivity TTL.
Privacy policy: https://partiri.cloud/privacy
Available Tools
23 toolscreate_projectCreate ProjectA
Create a new project in a workspace. Returns the created project with its id. Get a workspace id from list_workspaces first.
Inputs: name (required), environment (required), workspaceId (required).
create_serviceCreate ServiceA
Create a new service in a project. Requires exactly one source (repository URL or registry URL), a compute pod, and a region. Get IDs from list_projects, list_pods, and list_regions. Returns the created service with its id. Supported deploy types: webservice, static, private-service, worker (long-running background process with no inbound network — no port, no URL, no health check); for static the runtime is forced to "static" server-side. Environment variables are NOT set here — manage them with the partiri CLI (see use_partiri_cli).
Inputs: name (required), fkPod (required), runtime (required), fkRegion (required), +12 more.
deploy_serviceDeploy ServiceADestructive
Trigger a new deployment. Checks workspace balance and enforces a 10-minute cooldown. Use list_jobs to check deployment status afterward.
Inputs: serviceId (required).
get_balanceGet Workspace BalanceARead-onlyIdempotent
Get the current workspace balance. Returns currency, amount, and last-updated timestamp. Requires billing:r permission — degrades gracefully (returns null) on a 403. Use this to warn the user before creating services.
Inputs: workspaceId (required).
get_cpu_metricsGet CPU MetricsARead-onlyIdempotent
Get CPU usage metrics (average, peak, current in cores) for a service. Automatically uses the current deploy tag if not specified. Use get_service to find service IDs.
Inputs: serviceId (required), end, start, deployTag.
get_current_userGet Current UserARead-onlyIdempotent
Get the profile of the currently authenticated user. Returns id, email, and name.
Inputs: no named parameters.
get_memory_metricsGet Memory MetricsARead-onlyIdempotent
Get memory usage metrics (average, peak, current in bytes) for a service. Automatically uses the current deploy tag if not specified. Use get_service to find service IDs.
Inputs: serviceId (required), end, start, deployTag.
get_network_metricsGet Network MetricsARead-onlyIdempotent
Get network download and upload metrics (bytes/s) for a service. Automatically uses the current deploy tag if not specified. Use get_service to find service IDs.
Inputs: serviceId (required), end, start, deployTag.
get_pricingGet PricingARead-onlyIdempotent
Get pod and volume pricing for a region. Returns pod prices (monthly, per-minute) and volume price per GB per month. Use a region id from list_regions. Useful for estimating monthly cost before creating a service.
Inputs: regionId (required).
get_serviceGet ServiceARead-onlyIdempotent
Get full configuration of a service including repository, build commands, region, pod, and deploy tag. Environment variables are omitted from the response — they hold secrets and are managed out-of-band via the partiri CLI (see use_partiri_cli). Use list_services to find service IDs.
Inputs: serviceId (required).
get_volumeGet VolumeARead-onlyIdempotent
Get details of a single persistent volume by ID.
Inputs: volumeId (required).
list_jobsList Deployment JobsARead-onlyIdempotent
List deployment jobs for a service. Returns job id, type, status (open, in_progress, succeeded, failed, canceled, timed_out), and timestamps. Use after deploy_service to track progress.
Inputs: serviceId (required).
list_podsList Compute PodsARead-onlyIdempotent
List available compute pods (instance types) for a workspace. Returns id, name, label, cpu, and ram for each pod. Use a pod id when creating a service with create_service.
Inputs: workspaceId (required).
list_projectsList ProjectsARead-onlyIdempotent
List all projects in a workspace. Returns id, name, and environment for each project. Get a workspace id from list_workspaces first. Use a project id with list_services.
Inputs: workspaceId (required).
list_regionsList RegionsARead-onlyIdempotent
List available deployment regions for a workspace. Returns id, name, label, and country_code for each region. Use a region id when creating a service with create_service.
Inputs: workspaceId (required).
list_servicesList ServicesARead-onlyIdempotent
List all services in a project. Returns a summary (id, name, runtime, deploy_type, deploy_tag, active) for each service — call get_service for full configuration. Get a project id from list_projects first. Returns at most limit services (default 50); when has_more is true, raise limit to fetch the rest.
Inputs: projectId (required), limit.
list_volumesList VolumesARead-onlyIdempotent
List persistent volumes in a project. Returns id, name, size, mount_path, status, and attached service for each volume. Status can be: pending, provisioning, available, attached, deleting, or failed.
Inputs: projectId (required).
list_workspacesList WorkspacesARead-onlyIdempotent
List all workspaces the authenticated user has access to. Returns id, name, and email for each workspace. Use a workspace id with list_projects, list_pods, or list_regions.
Inputs: no named parameters.
pause_servicePause ServiceAIdempotent
Pause a running service. The service will stop receiving traffic but can be unpaused later.
Inputs: serviceId (required).
unpause_serviceUnpause ServiceAIdempotent
Resume a paused service.
Inputs: serviceId (required).
update_serviceUpdate ServiceADestructiveIdempotent
Update an existing service configuration. Only include fields you want to change. Use get_service to see current values first. Environment variables are NOT managed here — use the partiri CLI (see use_partiri_cli).
Inputs: serviceId (required), name, fkPod, runtime, +13 more.
use_partiri_cliGet Partiri CLI GuidanceARead-onlyIdempotent
Guidance for running the locally-installed partiri CLI yourself for sensitive operations that are intentionally not exposed as direct MCP tools: managing workspace secrets (partiri secret create-repository / create-registry), detaching or deleting a volume (partiri storage detach / delete), killing a service (partiri service kill), and managing service environment variables (partiri service env). This tool does NOT execute anything — it returns instructions for you to run the command in your own shell. These operations are kept CLI-only because they pass long-lived credentials or cause irreversible data loss, and the CLI authenticates independently of the MCP session. Note: creating, attaching, or retry-provisioning a volume has no CLI subcommand — use the dashboard or API. Service-scoped commands like service kill read the service ID from a local .partiri.jsonc (only service deploy accepts --service <UUID>). Discover exact subcommands and flags at runtime — run partiri llm guide, partiri llm capabilities -j, or partiri <area> --help first; do not assume command syntax. For credential values prefer stdin (with the CLI flag that reads stdin, e.g. --token-stdin / --password-stdin) over an argument so the secret stays out of the command line and this context.
Inputs: action (required), command.
validate_serviceValidate Service ConfigurationAIdempotent
Preflight-validate a service configuration before creating or updating it. Checks source XOR rule (repository vs registry), deploy_type/runtime compatibility, and name length (≤16). When probeReachability is set, performs an OUTBOUND network probe of the supplied git repository or registry URL (not side-effect-free). Returns a list of checks with ok/fail status.
Inputs: name (required), fkPod (required), runtime (required), fkRegion (required), +11 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 23 tools
Each tool targets a distinct resource or action: create, deploy, metrics, pricing, etc. No two tools have overlapping purposes. Even similar get_/list_ tools separate singular vs plural and target different entities.
All tools follow a consistent verb_noun pattern in snake_case. Verbs are imperative (create, get, list, pause, etc.) and nouns are clear, even for compound terms like cpu_metrics. No mixing of styles.
23 tools cover a cloud platform's essential operations (workspaces, projects, services, volumes, metrics, pricing) without being overwhelming. Each tool earns its place; no obvious bloat.
Service lifecycle is mostly covered (create, get, list, update, deploy, pause/unpause, validate, metrics) but missing delete operation and environment variable management (delegated to CLI). Volumes lack CRUD entirely. Projects and workspaces have only read or create. These gaps are notable but the core workflow for services is functional.
Maintenance
Related MCP Connectors
MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
MCP-first control plane for ProAgentStore agents and private instances.
Related MCP Servers
- AlicenseAqualityBmaintenanceMCP server for hyperpanes terminal workspace app, enabling AI agents to compose and launch workspace layouts, inspect and drive terminal panes, stream output, and orchestrate agent hierarchies.501MIT
- AlicenseNot gradedqualityDmaintenanceMCP server for the Paperclip AI agent orchestration API, enabling management of AI companies, agents, projects, and tasks through any MCP-compatible client.41 npm4MIT
- FlicenseNot gradedqualityBmaintenanceMCP server for AI DevTool workflow, exposing tools and resources for code review, repository chat, and repository operations.1-
- AlicenseAqualityCmaintenanceMCP server for Azure resource management, AI Foundry, and Entra ID — inspect and operate Azure infrastructure through AI agents.3MIT