> ## Documentation Index
> Fetch the complete documentation index at: https://docs.surfa.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Remote MCP Deployment

> Deploy your MCP server to production with HTTP/SSE transport

## Overview

Deploy your MCP server to the cloud for remote access via HTTP/SSE transport. This enables:

* Access from anywhere (not just localhost)
* Integration with web applications
* Multi-user support
* Always-available analytics

## Deployment Options

### Fly.io (Recommended)

**Why Fly.io:**

* Built-in MCP support (`fly mcp wrap`)
* Automatic HTTPS
* Global edge network
* Free tier available

**Steps:**

1. **Install flyctl**

```bash theme={null}
curl -L https://fly.io/install.sh | sh
```

2. **Wrap your MCP server**

```bash theme={null}
fly mcp wrap --port 8080
```

3. **Deploy**

```bash theme={null}
fly deploy
```

4. **Get your endpoint**

```bash theme={null}
fly status
# Your MCP is now at: https://your-app.fly.dev/sse
```

<Warning>
  Fly.io machines auto-stop after 5 minutes of inactivity. The Surfa platform handles cold starts automatically with retry logic (3 attempts × 9 seconds).
</Warning>

### Other Platforms

**Railway, Render, Heroku:**

* Use HTTP/SSE transport
* Expose port 8080
* Set environment variables
* Enable HTTPS

## Transport: SSE vs STDIO

### STDIO (Local Only)

**Pros:**

* ✅ Fast, low latency
* ✅ Simple setup

**Cons:**

* ❌ Only works on localhost
* ❌ Can't be accessed remotely

### SSE (Remote-Ready)

**Pros:**

* ✅ Works over HTTP/HTTPS
* ✅ Accessible from anywhere
* ✅ Web-compatible

**Cons:**

* ⚠️ Slightly higher latency
* ⚠️ May have cold starts

**When to use SSE:**

* Deploying to cloud platforms
* Building web applications
* Multi-user scenarios
* Remote access needed

## Authentication

### API Key via Headers

```bash theme={null}
curl -X POST https://your-mcp.fly.dev/sse \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":"1","method":"tools/list","params":{}}'
```

### In Surfa Platform

The platform automatically handles authentication when you add your MCP with headers:

```json theme={null}
{
  "Authorization": "Bearer sk_live_your_key"
}
```

## Cold Start Handling

Remote MCPs may "sleep" after inactivity. The Surfa platform handles this automatically:

<Steps>
  <Step title="First Request">
    Returns 202 (machine starting)
  </Step>

  <Step title="Retry 1">
    Wait 9 seconds, try again
  </Step>

  <Step title="Retry 2">
    Wait 9 seconds, try again
  </Step>

  <Step title="Retry 3">
    Wait 9 seconds, try again
  </Step>

  <Step title="Success">
    Tools discovered and displayed
  </Step>
</Steps>

**Total wait time:** Up to 27 seconds for cold starts.

**To avoid cold starts:**

* Keep machines always-on (costs more)
* Use health check pings
* Accept the retry delay

## Testing Your Deployment

### 1. Test with curl

```bash theme={null}
curl -X POST https://your-mcp.fly.dev/sse \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":"1","method":"tools/list","params":{}}'
```

### 2. Test in Surfa Platform

<Steps>
  <Step title="Navigate">
    Go to **Settings → MCP**
  </Step>

  <Step title="Add MCP">
    Click **Add New MCP**
  </Step>

  <Step title="Configure">
    * Name: "My Remote MCP"
    * Transport: SSE
    * Endpoint: `https://your-mcp.fly.dev/sse`
    * Headers: `{"Authorization": "Bearer sk_live_your_key"}`
  </Step>

  <Step title="Test">
    Click **Test Connection**
  </Step>

  <Step title="Wait">
    Wait for retries (if cold start)
  </Step>

  <Step title="Success">
    See discovered tools ✅
  </Step>
</Steps>

## CORS Configuration

If accessing from web apps, enable CORS:

```python theme={null}
from fastapi.middleware.cors import CORSMiddleware

app.add_middleware(
    CORSMiddleware,
    allow_origins=["https://surfa.dev"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)
```

## Security Best Practices

<AccordionGroup>
  <Accordion title="Always use HTTPS" icon="lock">
    Never expose API keys over HTTP. Use HTTPS in production.
  </Accordion>

  <Accordion title="Validate API keys" icon="key">
    Check API keys on every request. Reject invalid keys immediately.
  </Accordion>

  <Accordion title="Rate limit" icon="gauge">
    Prevent abuse by limiting requests per IP or API key.
  </Accordion>

  <Accordion title="Log access" icon="file-lines">
    Track all API requests for auditing and debugging.
  </Accordion>

  <Accordion title="Rotate keys" icon="arrows-rotate">
    Regularly rotate API keys and revoke old ones.
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="502 Bad Gateway" icon="circle-exclamation">
    **Cause:** Machine is starting (cold start)

    **Solution:**

    * Wait for retry logic to complete
    * Check Fly.io logs: `fly logs`
    * Verify machine is running: `fly status`
  </Accordion>

  <Accordion title="401 Unauthorized" icon="circle-exclamation">
    **Cause:** Invalid or missing API key

    **Solution:**

    * Check API key is correct
    * Verify Authorization header format: `Bearer sk_live_...`
    * Ensure key has correct permissions
  </Accordion>

  <Accordion title="Timeout" icon="circle-exclamation">
    **Cause:** Server not responding after 27 seconds

    **Solution:**

    * Increase timeout in Surfa platform
    * Check machine is running: `fly status`
    * Configure always-on if needed
  </Accordion>

  <Accordion title="Tools not discovered" icon="circle-exclamation">
    **Cause:** MCP server not returning tools

    **Solution:**

    * Verify `/sse` endpoint is correct
    * Check `initialize` request works
    * Test `tools/list` manually with curl
    * Review server logs for errors
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Test Connection" icon="plug" href="/mcp-testing">
    Learn how to test your MCP connection
  </Card>

  <Card title="Claude Desktop Setup" icon="sparkles" href="/claude-desktop-setup">
    Connect Claude Desktop to your remote MCP
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference">
    Complete API documentation
  </Card>

  <Card title="GitHub Repository" icon="github" href="https://github.com/gamladz/surfa-mcp">
    View source and contribute
  </Card>
</CardGroup>