# MCP Cloud Mode - Quick Start Guide

## Overview

The Synqed MCP (Model Context Protocol) system now supports **Cloud Mode**, where all MCP tool calls route through a centralized Fly.io server instead of running in-process.

## Architecture

```
┌─────────────────────────────────────────────────────┐
│  Your Local Agent                                   │
│  ┌───────────────────────────────────────────────┐  │
│  │ Agent Logic                                   │  │
│  │   await context.mcp.call_tool(               │  │
│  │       "salesforce.query_leads",              │  │
│  │       {"query": "..."}                       │  │
│  │   )                                          │  │
│  └──────────────────┬────────────────────────────┘  │
│                     │                               │
│              RemoteMCPClient                        │
│                     │                               │
└─────────────────────┼───────────────────────────────┘
                      │
                      │ HTTPS POST
                      │
                      ▼
┌─────────────────────────────────────────────────────┐
│  Fly.io: synqed.fly.dev                             │
│                                                     │
│  ┌─────────────────────────────────────────────┐   │
│  │  /mcp/call_tool                             │   │
│  │    1. Receive tool call                     │   │
│  │    2. Look up tool → agent mapping          │   │
│  │    3. Bridge to A2A                         │   │
│  │    4. Execute agent task                    │   │
│  │    5. Return result                         │   │
│  └─────────────────────────────────────────────┘   │
│                                                     │
│  Email Registry + MCP Server (unified)              │
└─────────────────────────────────────────────────────┘
```

## Setup

### 1. Configure Environment

Copy `env.example` to `.env`:

```bash
cp env.example .env
```

Edit `.env`:

```bash
# Required: Your LLM API key
ANTHROPIC_API_KEY=sk-ant-...

# Cloud Mode Configuration
SYNQ_MCP_MODE=cloud
SYNQ_MCP_ENDPOINT=https://synqed.fly.dev/mcp
```

### 2. Deploy to Fly.io (One-Time Setup)

```bash
# Deploy the unified server (email + MCP)
./scripts/deploy_mcp_fly.sh
```

This deploys both:
- Email-based agent registry
- Global MCP server at `/mcp/*`

### 3. Verify Deployment

```bash
# Check health
curl https://synqed.fly.dev/health

# List available MCP tools
curl https://synqed.fly.dev/mcp/tools

# Test tool call
curl -X POST https://synqed.fly.dev/mcp/call_tool \
  -H 'Content-Type: application/json' \
  -d '{"tool":"salesforce.query_leads","arguments":{"query":"test"}}'
```

## Running Examples

### Dynamic Agents with MCP

```bash
cd synqed-samples/api/examples/email
python dynamic_agents_email.py
```

Expected output:
```
🔧 Attaching MCP capability to all agents...
   • Mode: CLOUD
   • Remote MCP Endpoint: https://synqed.fly.dev/mcp
   • All MCP calls will route through Fly.io server

   ✅ ResearchLead - MCP enabled
   ✅ VenueCoordinator - MCP enabled
   ✅ MarketingManager - MCP enabled
```

### Universal MCP Demo

```bash
cd synqed-python
python universal_mcp_demo.py
```

## How It Works

### Local Mode (Development)

```python
# Creates local router and A2A client
mcp_router = synqed.MessageRouter()
a2a_client = A2AClient(mcp_router, workspace_id="local")

# Register agents locally
mcp_router.register_agent("salesforce", salesforce_agent)

# Middleware uses LocalMCPClient
middleware = create_mcp_middleware(
    router=mcp_router,
    a2a_client=a2a_client,
    mode="local"
)
```

### Cloud Mode (Production)

```python
# NO local router or A2A client needed!
# Middleware uses RemoteMCPClient pointing to Fly.io
middleware = create_mcp_middleware(
    router=None,  # Ignored in cloud mode
    a2a_client=None,  # Ignored in cloud mode
    mode="cloud",
    endpoint="https://synqed.fly.dev/mcp"
)
```

## Key Differences

| Aspect | Local Mode | Cloud Mode |
|--------|------------|------------|
| Router | Local `MessageRouter` | None (remote server) |
| A2A Client | Local `A2AClient` | None (remote server) |
| Tool Registry | Local tool registry | Remote `/mcp/tools` |
| Agent Registration | `router.register_agent()` | Managed by cloud server |
| MCP Client | `LocalMCPClient` | `RemoteMCPClient` |
| Latency | ~1ms | ~50-100ms (network) |
| Scalability | Single process | Multi-tenant cloud |

## Troubleshooting

### MCP calls return 404

**Problem**: `/mcp/tools` returns 404

**Solution**: Check that:
1. `ENABLE_MCP=true` in fly.toml
2. MCP imports succeeded (check logs)
3. App redeployed after code changes

```bash
flyctl logs -a synqed
```

### Import errors

**Problem**: `No module named 'fastmcp'`

**Solution**: This is OK! The cloud MCP server doesn't need `fastmcp`. Only the stdio MCP server uses it.

### Agent calls timeout

**Problem**: Tool calls hang or timeout

**Solution**:
1. Check Fly.io server logs: `flyctl logs -a synqed`
2. Verify endpoint is correct: `echo $SYNQ_MCP_ENDPOINT`
3. Test endpoint directly: `curl https://synqed.fly.dev/mcp/tools`

## Next Steps

1. **Add Custom Tools**: Register your own tools in `synqed_mcp/registry.py`
2. **Deploy Agents**: Deploy agents that use MCP to call each other
3. **Monitor**: Use Fly.io dashboard to monitor MCP server performance
4. **Scale**: Fly.io auto-scales based on load

## Resources

- [Fly.io Dashboard](https://fly.io/dashboard)
- [Synqed Documentation](../README.md)
- [MCP Architecture](./GLOBAL_MCP_ARCHITECTURE.md)

