Skip to main content
mcp-agent cloud is not limited to full agent workflows—you can deploy any MCP-compliant server (Python, Node, Rust, etc.) and let the platform handle hosting, auth, and observability. This is ideal for tool libraries, data access APIs, or bridge services that you want to publish without maintaining infrastructure.

​
Why deploy plain MCP servers?

  • Standard MCP interface – Serve tools, resources, and prompts that any MCP client can consume.
  • Managed runtime – Containers, TLS, load balancing, and scaling handled automatically.
  • Security – Secrets vault, per-client API keys, optional unauthenticated mode for public registries.
  • Observability – Consistent logging + OTEL pipeline and CLI integration (mcp-agent cloud logger tail).
  • Upgrade path – When you are ready for long-running workflows, migrate the project to MCPApp without changing deployment tooling.

​
Side-by-side capabilities

CapabilityManaged MCP serverFull mcp-agent app
Tools & resources✅ Standard MCP tools/resources✅ Same, plus workflow-generated tools
Long-running work⚠️ Request lifetime only✅ Temporal workflows with pause/resume
Human inputManual implementation✅ Built-in request_human_input APIs
Retry & durabilityManual retries/logging✅ Automatic retries, state persistence
Observability✅ Logs + OTEL forwarding✅ All of the left, plus workflow history
Client integration✅ SSE/HTTP endpoints✅ Same endpoints

​
Choosing your deployment pattern

MCP Agent Cloud supports two deployment patterns depending on your use case:
PatternUse whenDecoratorFeatures
FastMCPDeploying simple tool servers@mcp.toolTools, resources, prompts via FastMCP interface
MCPAppBuilding agent apps with potential for workflows@app.toolApp context, logging, upgrade path to workflows
Key differences:
  • @mcp.tool – Exposes tools through the FastMCP interface. Use for lightweight MCP servers.
  • @app.tool – Provides access to app context and logging. Use when you might add workflows later with @app.async_tool and @app.workflow.
Both patterns require MCPApp for cloud deployment and produce the same SSE endpoints for clients.

​
Deploying a FastMCP server

Use this pattern when deploying simple MCP servers (tools and resources) without workflows. The @mcp.tool decorator exposes tools via the FastMCP interface. 
# main.py
from mcp.server.fastmcp import FastMCP
from mcp_agent.app import MCPApp

# FastMCP instance for tool definitions
mcp = FastMCP("utilities")

app = MCPApp(
    name="utilities-server",
    description="Handy utility tools exposed over MCP",
    mcp=mcp
)

@mcp.tool()
async def hash_text(text: str, algorithm: str = "sha256") -> str:
    """Generate a hash of text using hashlib."""
    import hashlib
    h = hashlib.new(algorithm)
    h.update(text.encode())
    return h.hexdigest()

# Optional: expose resources (data endpoints) in addition to tools
# @mcp.resource("utils://algorithms")
# async def list_algorithms():
#     return {"algorithms": ["md5", "sha1", "sha256", "sha3_512"]}
Configuration (mcp_agent.config.yaml): 
execution_engine: asyncio
logger:
  transports: [console]
  level: info
mcp_agent.secrets.yaml remains optional unless your server calls external APIs.

​
Deploying an MCPApp as a server

Use this pattern when building agent applications that may later need workflows, context, or advanced mcp-agent features. The @app.tool decorator provides access to app context and logging. 
# main.py
from mcp_agent.app import MCPApp

app = MCPApp(
    name="markdown-tools",
    description="Text processing tools",
)

@app.tool
async def to_title_case(text: str) -> str:
    """Convert text to title case."""
    return text.title()

@app.tool
async def count_words(text: str) -> int:
    """Count words in text."""
    return len(text.split())
Configuration (mcp_agent.config.yaml): 
execution_engine: asyncio
logger:
  transports: [console]
  level: info
This app behaves like a standard MCP server. When deploying to the cloud, you can add Temporal-backed workflows later (using @app.async_tool and @app.workflow) without changing the deployment command. For local testing with workflows, you’ll need to update execution_engine: temporal in your config and run a Temporal server.

​
Deploy the server

  1. Authenticate (once per environment): 
    mcp-agent login          # stores MCP_API_KEY
  2. Deploy from the directory that contains main.py and mcp_agent.config.yaml: 
    mcp-agent deploy utilities-server \
  --app-description "Utility functions as MCP tools"
    • Use --config-dir path/to/server if deploying from a monorepo.
    • Add --no-auth to expose a public endpoint (e.g., for ChatGPT Apps).
    • Use --non-interactive in CI/CD to reuse stored secrets.
  3. Describe the deployment: 
    mcp-agent cloud servers describe utilities-server
    Copy the Server URL for client integration.

​
Configure clients

Use either mcp-agent install (writes files automatically) or mcp-agent configure --client (prints snippets). 
mcp-agent install https://<app_id>.deployments.mcp-agent.com/sse \
  --client cursor

mcp-agent configure https://<app_id>.deployments.mcp-agent.com/sse \
  --client vscode --write
<app_id> is the hostname reported by the CLI (for example, app_abc123xyz.deployments.mcp-agent.com). For unauthenticated deployments (e.g., ChatGPT Apps), remember to deploy with --no-auth and run: 
mcp-agent install <server-url> --client chatgpt

​
Operate and monitor

Even though these servers do not use Temporal, you still get the operational surface:
  • mcp-agent cloud servers list – inventory of deployed servers.
  • mcp-agent cloud logger tail utilities-server --follow – live logs.
  • mcp-agent cloud servers delete utilities-server – tear down when finished.
  • mcp-agent cloud configure --id <url> – collect user-specific secrets if needed.

​
Upgrade path to full agents

Start simple and layer on durability when required: 
# Initial FastMCP tool
@mcp.tool()
async def fetch_issue(repo: str, number: int) -> dict: ...

# Later: wrap inside MCPApp to reuse the tool and add workflows
from mcp_agent.app import MCPApp
app = MCPApp(name="issue_triage")

@app.tool
async def fetch_issue(repo: str, number: int) -> dict: ...

@app.async_tool
async def triage_issue(repo: str, number: int) -> dict:
    # Durable workflow that assigns, notifies, etc.
    ...
Redeploy with the same name and clients keep working while gaining new capabilities (workflows-get_status, pause/resume, etc.).

​
Checklist for MCP server deployments

  • Entrypoint (main.py) starts the server when executed.
  • mcp_agent.config.yaml references the command + args.
  • requirements.txt or pyproject.toml included.
  • Secrets captured in mcp_agent.secrets.yaml (if needed).
  • .mcpacignore excludes large/unnecessary files.
  • Deployment tested locally with uv run main.py or npx @modelcontextprotocol/inspector.
  • Documentation for consumers (URL, sample tool calls, auth mode).

​
Resources