Getting Started with mcp-agent cloud

mcp-agent cloud is currently in open beta. Follow the instructions below to get started. For feedback, issues and feature requests, visit our github issues or join our Discord.

Prerequisites

Before you begin, make sure you have:

mcp-agent installed

# Using uv (recommended)
uv tool install mcp-agent

# Or using pip
pip install mcp-agent

A working agent

An mcp-agent project that runs locally

Quick Start

Initialize Project

Create a new mcp-agent project:

mcp-agent init

This will initialize a mcp-agent project for you and create all the necessary files.

Authenticate

mcp-agent login

This will direct you to the API keys page for obtaining credentials.

Prepare Your Project

Ensure your project has the required configuration files:

mcp_agent.config.yaml

execution_engine: temporal
logger:
  transports: [console]
  level: info

mcp:
  servers:
    # Your MCP server configurations
    fetch:
      command: "uvx"
      args: ["mcp-server-fetch"]

# Your LLM provider config
openai:
  default_model: gpt-4o

Deploy

Deploy your agent with a single command:

mcp-agent deploy my-first-agent

The deployment process will:

Check for existing app with this name or create a new one
Process your secrets file
Bundle and upload your code
Deploy to MCP Agent Cloud’s managed infrastructure

You’ll see output like:

App ID: app_abc123xyz
App URL: https://deployments.mcp-agent.com/servers/my-first-agent
App Status: ONLINE

Test Your Deployment

List your deployed agents:

mcp-agent cloud servers list

Test your agent:

# Get server details
mcp-agent cloud servers describe app_abc123xyz

# View logs - this is essential for debugging!
mcp-agent cloud logger tail app_abc123xyz --follow

# Filter for errors
mcp-agent cloud logger tail app_abc123xyz --grep "ERROR" --since 5m

The cloud logger tail command is your best friend for debugging deployments. Use --follow to stream logs in real-time and --grep to filter for specific patterns.

Your First Cloud Workflow

Let’s create and deploy a simple agent that can fetch web content and summarize it.

Create the Agent

import asyncio
from mcp_agent.app import MCPApp
from mcp_agent.agents.agent import Agent
from mcp_agent.executor.workflow import Workflow, WorkflowResult
from mcp_agent.workflows.llm.augmented_llm_openai import OpenAIAugmentedLLM

app = MCPApp(name="web_summarizer")

@app.workflow
class WebSummarizerWorkflow(Workflow[str]):
    """Fetches and summarizes web content."""
    
    @app.workflow_run
    async def run(self, url: str) -> WorkflowResult[str]:
        # Create an agent with fetch capabilities
        agent = Agent(
            name="summarizer",
            instruction="Fetch and summarize web content concisely.",
            server_names=["fetch"]
        )
        
        async with agent:
            llm = await agent.attach_llm(OpenAIAugmentedLLM)
            
            # Fetch and summarize
            summary = await llm.generate_str(
                f"Fetch {url} and provide a 3-sentence summary"
            )
            
            return WorkflowResult(value=summary)

# For local testing
if __name__ == "__main__":
    async def test():
        async with app.run():
            workflow = WebSummarizerWorkflow()
            result = await workflow.run("https://example.com")
            print(result.value)
    
    asyncio.run(test())

Deploy to Cloud

# Deploy the agent
mcp-agent deploy web-summarizer

# Or deploy from a specific app directory
mcp-agent deploy web-summarizer -c <path-to-app-directory>


# or deploy with a custom app description
mcp-agent deploy web-summarizer --app-description "Web content summarizer agent"

Use Your Cloud Agent

Your agent is now available as an MCP server. Here’s how to use it:

Claude Desktop
Python Client
cURL

First configure the agent (this handles authentication and user secrets):

mcp-agent cloud configure --id https://deployments.mcp-agent.com/servers/web-summarizer

Then add to your Claude Desktop config (~/.claude-desktop/config.json):

.claude-desktop/config.json

{
  "servers": {
    "web-summarizer": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://deployments.mcp-agent.com/servers/web-summarizer/sse",
        "--header",
        "Authorization: Bearer <MCP_AGENT_API_KEY>"
      ]
    },
  }
}

Restart Claude Desktop and your agent will appear in the tools menu.

Advanced Deployment Options

Deployment Configuration

Control your deployment with additional options:

# Deploy with custom configuration directory
mcp-agent deploy my-agent --config-dir ./my-config

# Skip secrets processing if not needed
mcp-agent deploy my-agent --no-secrets

# Non-interactive mode (fail if secrets require prompting)
mcp-agent deploy my-agent --non-interactive

# Dry run to validate without deploying
mcp-agent deploy my-agent --dry-run

# Deploy with description
mcp-agent deploy my-agent --app-description "My production agent"

Environment Variables

Environment variables for the CLI:

# Set API base URL
export MCP_API_BASE_URL="https://deployments.mcp-agent.com"

# Set API key (alternative to login)
export MCP_API_KEY="your-api-key"

# Deploy with environment variables
MCP_API_KEY="your-key" mcp-agent deploy my-agent

Secrets Management

MCP Agent Cloud securely handles secrets through the mcp_agent.secrets.yaml file:

During mcp-agent deploy, you will be prompted through the secrets management flow
Secrets are safely secured in MCP Agent Cloud

Testing with MCP Inspector

MCP Inspector is a powerful tool for testing and debugging your deployed MCP servers. It provides a web interface to interact with your agent’s tools and resources.

Using MCP Inspector

Test your deployed agent with the MCP Inspector:

Open MCP Inspector: Visit https://modelcontextprotocol.io/inspector
Connect to your server:
- Select “SSE” as the transport
- Enter your server URL, and append “/sse”
- Add the required authentication headers (Bearer $MCP_AGENT_CLOUD_API_KEY)
Test your tools:
- Browse available tools and resources
- Execute tool calls interactively
- View request/response payloads
- Debug workflow executions

MCP Inspector is especially useful for:

Testing tool implementations before integrating with clients
Debugging authentication issues
Understanding the exact payloads your agent expects
Verifying workflow execution flows

Managing Deployments

View Deployments

# List all deployments
mcp-agent cloud servers list

# Get details
mcp-agent cloud servers describe app_abc123xyz

# View statistics (if available)
mcp-agent cloud servers stats app_abc123xyz

Monitor Workflows

# List workflow runs
mcp-agent cloud servers workflows app_abc123xyz

# Get workflow status
mcp-agent cloud workflows describe app_abc123xyz run_123

# Suspend a workflow
mcp-agent cloud workflows suspend app_abc123xyz run_123

# Resume with data
mcp-agent cloud workflows resume app_abc123xyz run_123 \
  --payload '{"continue": true}'

# Cancel a workflow
mcp-agent cloud workflows cancel app_abc123xyz run_123

View Logs

# Tail logs
mcp-agent cloud logger tail app_abc123xyz

# Follow logs
mcp-agent cloud logger tail app_abc123xyz --follow

# Filter logs
mcp-agent cloud logger tail app_abc123xyz \
  --since 1h \
  --grep "ERROR" \
  --limit 100

Update Deployment

# Redeploy with latest code (simply run deploy again)
mcp-agent deploy my-agent

# The deployment will update the existing app if it already exists

Delete Deployment

# Delete a deployment
mcp-agent cloud servers delete app_abc123xyz

# Force delete (skip confirmation)
mcp-agent cloud servers delete app_abc123xyz --force

Client Integration

Help users connect to your deployed agent:

# Configure access for a deployed agent (handles auth and secrets)
mcp-agent cloud configure --id https://deployments.mcp-agent.com/servers/my-agent

# Show required parameters for configuration
mcp-agent cloud configure --id https://deployments.mcp-agent.com/servers/my-agent --params

After configuration, users can connect with their MCP client using the server URL and appropriate transport (SSE or streamable HTTP).

Best Practices

Use Temporal Execution Engine

Always set execution_engine: temporal in your config for cloud deployments. This enables durable execution and workflow management.

Implement Health Checks

Add health check endpoints to your workflows for better monitoring:

@app.tool
async def health() -> str:
    """Health check endpoint."""
    return "healthy"

Use Structured Logging

Use the app logger for better observability:

logger = app.context.logger
logger.info("Processing request", data={"url": url})

Handle Secrets Properly

Never hardcode secrets. Use environment variables or the secrets store:

import os
api_key = os.getenv("API_KEY")

Version Your Deployments

Tag your deployments for easy rollback:

git tag v1.2.0
git push origin v1.2.0
mcp-agent deploy my-agent

Troubleshooting

Deployment Fails

Check build logs:

mcp-agent cloud logger tail app_abc123xyz --since 10m

Common issues:

Missing dependencies in requirements.txt
Invalid configuration syntax
Missing required secrets

Workflow Not Starting

Verify worker is running:

mcp-agent cloud servers describe app_abc123xyz

Check for “Workers: Running” in the output.

Authentication Issues

Refresh your authentication:

mcp-agent logout
mcp-agent login

Connection Timeouts

Check your network and firewall settings. MCP Agent Cloud requires:

HTTPS (port 443) for API access
WebSocket support for real-time features

Example Projects

Explore complete examples:

Basic Agent Examples

Simple agents with MCP servers

Workflow Patterns

All workflow pattern implementations

MCP Agent Server

Agent-as-server examples

Temporal Examples

Durable workflow examples

Next Steps

Agent Server Concepts

Understand agents as MCP servers

Workflow Management

Manage long-running workflows

CLI Reference

Complete command reference

Monitoring

Set up logging and alerts

Getting Started

Core Concepts

Workflow Patterns

MCP Protocol

Agent as MCP Server

mcp-agent cloud

Advanced Topics

Reference

​Prerequisites

mcp-agent installed

A working agent

​Quick Start

​Your First Cloud Workflow

​Create the Agent

​Deploy to Cloud

​Use Your Cloud Agent

​Advanced Deployment Options

​Deployment Configuration

​Environment Variables

​Secrets Management

​Testing with MCP Inspector

​Using MCP Inspector

​Managing Deployments

​View Deployments

​Monitor Workflows

​View Logs

​Update Deployment

​Delete Deployment

​Client Integration

​Best Practices

​Troubleshooting

​Example Projects

Basic Agent Examples

Workflow Patterns

MCP Agent Server

Temporal Examples

​Next Steps

Agent Server Concepts

Workflow Management

CLI Reference

Monitoring

Prerequisites

Quick Start

Your First Cloud Workflow

Create the Agent

Deploy to Cloud

Use Your Cloud Agent

Advanced Deployment Options

Deployment Configuration

Environment Variables

Secrets Management

Testing with MCP Inspector

Using MCP Inspector

Managing Deployments

View Deployments

Monitor Workflows

View Logs

Update Deployment

Delete Deployment

Client Integration

Best Practices

Troubleshooting

Example Projects

Next Steps