Microservices Sh MCP

What the microservices-sh/mcp MCP server does

The microservices-sh/mcp MCP server gives coding agents a structured workflow for planning and preparing Cloudflare-native applications from reusable microservices.sh templates and modules. Agents can browse available foundations, inspect the contracts behind them, select modules, and review the resulting application composition before any files or remote resources are changed.

The registry includes modules for product concerns such as authentication, booking, customer records, payments, files, and audit logs. The available inventory should be discovered through the server rather than assumed. Module inspection exposes details such as permissions, hooks, events, resources, storage requirements, and customization points.

Project generation is performed in memory. The generated source, documentation, migrations, and configuration can be inspected before a local project is created or edited. The server also supports readiness checks, secret-status reporting, update planning, and deployment planning.

How it works

A typical workflow starts with list_templates or list_modules. Use inspect_template or inspect_module to understand the selected contracts, and consult module documentation when implementation guidance is needed. compose_app produces a checked app composition and lockfile plan without writing files. validate_config checks the selected template, modules, and configuration for unsupported combinations or missing settings.

After generation and local checks, get_secrets_status reports required secret names and whether they are configured, without returning secret values. create_preview_plan prepares a deployment-readiness report containing resources, checks, warnings, errors, and approval requirements. deploy_preview can then prepare a remote preview deployment, but it is mutating and requires confirm: "preview". Use get_deployment_status afterward to inspect progress or deployment metadata.

The microservices-sh/mcp MCP server also supports module lifecycle planning. check_updates compares locked versions with the bundled registry snapshot, while plan_add_module and plan_module_upgrade report intended lockfile changes and review gates without applying them.

Setup and configuration

The package is available as @microservices-sh/mcp. The provided direct-run installation is:

npx -y @microservices-sh/mcp

The package is a standalone stdio MCP server. A client can start the microservices-mcp command and provide configuration through environment variables. MICROSERVICES_API_URL selects the remote control-plane URL and defaults to https://api.microservices.sh. MICROSERVICES_API_KEY supplies the bearer token for remote tools, while MICROSERVICES_TOKEN is the fallback bearer token.

Local planning capabilities do not necessarily require remote credentials, but preview deployment and other control-plane operations depend on access to the configured API. The README also documents a local development mode that runs the built dist/index.js file with Node.js.

Tools and capabilities

• Discover templates, modules, and module documentation.
• Inspect template and module contracts before composing an app.
• Compose and validate application plans without writing files.
• Generate project artifacts in memory for review.
• Run compatibility, contract, and readiness checks.
• Plan module additions and version upgrades with approval gates.
• Check secret requirements without exposing values.
• Create preview plans and prepare confirmation-gated remote deployments.
• Read preview deployment status from the control plane.

Limitations and notes

The server vendors a small SDK and module-contract snapshot until the public SDK is split out. Generated projects are returned in memory; generate_project does not write files. Planning tools similarly report intended changes rather than applying them. Remote deployment is the exception: deploy_preview can mutate remote state and should only be called after a human reviews the preview plan and supplies the required confirmation.

The microservices-sh/mcp MCP server does not return secret values through its tools. Its remote features require a reachable microservices.sh control plane and a bearer token configured through the documented environment variables.