Skip to main content

Hosted Server CLI

The MintMCP Hosted Server CLI lets you package an MCP server and deploy it onto MintMCP-managed infrastructure in one command. The CLI builds your project, uploads artifacts, provisions hosting, and performs health checks before exposing the server to the rest of your organization.

When to Use the Hosted CLI​

Use the CLI when you:

  • Have developed an MCP server (stdio or HTTP) and you want to host it on MintMCP.
  • Want to make your MCP server accessible to web-based AI clients (like ChatGPT) that can't connect to local stdio processes running on user machines.
  • Prefer MintMCP to manage scaling, logs, and environment variables for the server instead of maintaining your own infrastructure.
  • Need a repeatable deployment path from source control to MintMCP-hosted runtime.

How It Fits into MintMCP​

  • A connector is an MCP server that MintMCP calls; see MCP Connector fundamentals.
  • A Virtual MCP packages one or more connectors and exposes them with policies to members in your organization (Virtual MCP concepts).
  • The Hosted Server CLI creates the hosted connector artifact for self-managed servers, so administrators can wire it into Virtual MCPs without manual container work.

Prerequisites​

  • MintMCP account with permission to deploy hosted servers.
  • Node.js 18+ locally so you can run npx.
  • Source code for an MCP server that implements the stdio or HTTP streamable transport.
    • Preferred: stdio. Per-User environment variables are only supported on the stdio transport.
    • If your server implements the HTTP streamable transport, it must serve at /mcp on port 8000.
  • Framework-specific prerequisites remain your responsibility:
    • TypeScript/JavaScript servers: install dependencies and ensure npm run build succeeds locally.
    • Python FastMCP servers: confirm uv/uvx is installed and your entrypoint runs locally.
    • Other runtimes: make sure any custom build tools or binaries needed for the startup command are vendored in your repo.

Deploying a JavaScript or TypeScript MCP Server​

IMPORTANT: First confirm that your server builds and runs locally.

If your server depends on private npm packages, see Using Private npm Packages in Hosted Servers for configuration details before deploying.

Then, continue with the following steps.

  1. From the project root, run:
npx @mintmcp/hosted-cli deploy -n "<Hosted server title>"

If your server implements HTTP streamable (at /mcp on port 8000), also pass -t http, to tell MintMCP to connect using HTTP streamable.

  1. By default the CLI runs npm install && npm run build && npm run start. Override with --startup-command if you use a different command.
npx @mintmcp/hosted-cli deploy -n "<Hosted server title>" \
  --startup-command "npm install && npm run build && npm run serve -- stdio"
  1. Watch the CLI output for the management URL. The MintMCP console shows logs, environment variables, health checks, and revision history.
  2. Redeploy any time to push changes. The previous revision continues serving traffic until the new one reports healthy.

Troubleshooting

  • Make sure you are running the CLI from the project root; the script packages up the current working directory, and the build may fail if it references files outside what was uploaded to the platform.
  • Build artifacts must be generated inside the workspace—make sure your build step writes to dist or similar before npm run start executes.

Deploying a Python FastMCP Server​

  1. Your entrypoint should call FastMCP with stdio transport.
if __name__ == "__main__":
    mcp.run(transport="stdio")
  1. Package layout determines the startup command:

    • Python package (pyproject.toml or setup.py present):

      npx @mintmcp/hosted-cli deploy -n "<Hosted server title>" \
        --startup-command "uvx --from . python <main.py>"

    • Single-file project:

      npx @mintmcp/hosted-cli deploy -n "<Hosted server title>" \
        --startup-command "uvx --with fastmcp python <main.py>"

If your server runs HTTP streamable (at /mcp on port 8000), also pass -t http, to tell MintMCP to connect using HTTP streamable.

  1. Add additional dependencies with repeated --with flags (for example --with requests).
  2. The CLI publishes the bundle, waits for health checks, and returns the management URL.
  3. Redeploy to ship updates; MintMCP swaps traffic to the new revision after it reports healthy.

Troubleshooting

  • Import errors mean the dependency was not included—add --with for each library.
  • If FastMCP fails to bind to port 8000, confirm no other process is using the port in your startup command.

Deploying Other MCP Servers​

Any framework works as long as the final process runs MCP stdio or MCP HTTP streamable transports.

For stdio:

npx @mintmcp/hosted-cli deploy -n "<Hosted server title>" \
  --startup-command "<command that starts stdio server>"

For HTTP streamable:

npx @mintmcp/hosted-cli deploy -n "<Hosted server title>" -t http \
  --startup-command "<command that starts HTTP streamable on port 8000>"
  • Include any build or install steps inside the startup command (for example pnpm install && pnpm start).

Managing Hosted Servers​

  • The CLI output includes the MintMCP management URL. Use it to:
    • Inspect deploy logs and runtime logs.
    • Check startup and health status.
    • Configure environment variables and secrets.
    • Manage revisions or roll back to a previous version.
  • Kubernetes-style scaling is automatic; the platform adds or removes instances based on load and keeps one healthy revision live at all times.

Environment Variables​

You can set environment variables for your server at the server management URL. Click "Edit" in the "Server Configuration" section and then select "Environment Variables".

Environment Variable Editor

There are two types of environment variables:

  • Global: Variable applies to all users across your organization.
  • Per-User: Each user will be prompted for values the first time they access the server. (These are only supported with the stdio transport).

Troubleshooting and FAQ​

  • The deploy succeeded but the app 500s. Review runtime logs in the management URL; fix the underlying error and redeploy. Reach out to support if you need help.
  • npm dependencies were not installed. Make sure your startup command includes npm install (or pnpm install) before the server starts.
  • Python dependencies are missing. Supply extra --with <package> arguments so uvx installs them during startup.
  • The server binds to the wrong port. Update your startup command to serve HTTP on port 8000.
  • Need to roll back quickly. Use the management page to revert to the previous revision; MintMCP keeps multiple revisions by default.

Next Steps​