# Railway Setup Guide - No Template Needed

## Quick Setup (No Template Required)

Since Railway doesn't have a FastMCP template, we'll use **Nixpacks** (Railway's auto-detector) or a custom Dockerfile.

---

## Option 1: Nixpacks with uv (Recommended - Fastest)

### Step 1: Create New Service

1. Go to Railway Dashboard
2. Click **"New Project"** or **"New Service"** in existing project
3. Select **"Deploy from GitHub repo"**
4. Choose `dcisionai-mcp-platform` repository
5. Select branch: `prod`

### Step 2: Configure Service

Railway will auto-detect Python, but you need to configure:

**Settings → Build:**
- **Build Command** (optional): `pip install uv && uv pip install --system -r dcisionai_mcp_server/requirements.txt`
- Or Railway will auto-detect and use `nixpacks.mcp.toml` if present

**Settings → Deploy:**
- **Start Command**: `python dcisionai_mcp_server/start_mcp_server.py`
- **Health Check Path**: `/health` (or leave blank)
- **Restart Policy**: `ON_FAILURE`

**Settings → Variables:**
```bash
DCISIONAI_API_URL=https://dcisionai-mcp-platform-production.up.railway.app
DCISIONAI_DOMAIN_FILTER=ria  # or "all"
DCISIONAI_REQUEST_TIMEOUT=300
DCISIONAI_ASYNC_ENABLED=true
DCISIONAI_LOG_LEVEL=INFO
```

### Step 3: Deploy

Railway will:
1. Auto-detect Python 3.12
2. Install `uv` (fast Python package installer)
3. Install dependencies using `uv` (much faster than pip)
4. Run start command
5. Provide public URL

**Benefits of uv:**
- ✅ **10-100x faster** than pip
- ✅ **Better dependency resolution**
- ✅ **Works seamlessly with IDEs**
- ✅ **Drop-in replacement** for pip

---

## Option 2: Custom Dockerfile (More Control)

### Step 1: Create Service

1. Create new Railway service
2. Connect GitHub repo
3. In **Settings → Build**, select **"Dockerfile"**
4. Set **Dockerfile Path**: `Dockerfile.mcp`

### Step 2: Configure

Same as Option 1 - set environment variables and start command.

**Note:** `Dockerfile.mcp` uses `uv` for faster dependency installation.

### Step 3: Deploy

Railway will build using `Dockerfile.mcp` (with uv) and deploy.

---

## Option 3: Use railway.mcp.toml

### Step 1: Create Service

1. Create new Railway service
2. Connect GitHub repo
3. Railway will auto-detect `railway.mcp.toml` if present

### Step 2: Rename Config File

```bash
# In your repo, rename for MCP service
cp railway.mcp.toml railway.toml
# Or create service-specific config
```

**Note:** Railway uses `railway.toml` in the repo root. For multiple services, you can:
- Use service-specific settings in Railway dashboard
- Or create separate config files per service

---

## Configuration Details

### Start Command

```bash
python dcisionai_mcp_server/start_mcp_server.py
```

This script:
- Imports FastMCP server
- Reads Railway's `PORT` environment variable
- Starts server on `0.0.0.0:PORT`

### Environment Variables

| Variable | Value | Required |
|----------|-------|----------|
| `DCISIONAI_API_URL` | Backend URL | ✅ Yes |
| `DCISIONAI_DOMAIN_FILTER` | `ria` or `all` | ❌ No |
| `DCISIONAI_REQUEST_TIMEOUT` | `300` | ❌ No |
| `DCISIONAI_ASYNC_ENABLED` | `true` | ❌ No |
| `DCISIONAI_LOG_LEVEL` | `INFO` | ❌ No |
| `PORT` | Auto-set by Railway | ✅ Auto |

### Health Check

FastMCP provides a `/health` endpoint automatically. Railway will check:
- `GET /health` → Should return `200 OK`

---

## Deployment Steps

### 1. Create Service

```
Railway Dashboard
  → New Project (or add to existing)
  → Deploy from GitHub
  → Select repo: dcisionai-mcp-platform
  → Branch: prod
```

### 2. Configure Build

**If using Nixpacks (auto-detect):**
- Railway auto-detects Python
- No additional config needed

**If using Dockerfile:**
- Settings → Build → Dockerfile
- Dockerfile Path: `Dockerfile.mcp`

### 3. Set Start Command

**Settings → Deploy:**
```
Start Command: python dcisionai_mcp_server/start_mcp_server.py
```

### 4. Set Environment Variables

**Settings → Variables:**
```
DCISIONAI_API_URL=https://dcisionai-mcp-platform-production.up.railway.app
DCISIONAI_DOMAIN_FILTER=ria
```

### 5. Deploy

Railway will automatically:
- Build the service
- Install dependencies
- Start the server
- Provide public URL

---

## Verify Deployment

### Check Logs

Railway Dashboard → Service → Logs:
```
🚀 Starting DcisionAI MCP Server on Railway
Domain Filter: ria
API URL: https://dcisionai-mcp-platform-production.up.railway.app
Starting server on 0.0.0.0:8080
✅ FastMCP server imported successfully
🚀 Starting FastMCP server on 0.0.0.0:8080
```

### Test MCP Server

```bash
# Get your Railway URL (e.g., https://dcisionai-mcp-server.railway.app)

# Test health
curl https://your-mcp-server.railway.app/health

# Test tools list
curl https://your-mcp-server.railway.app/mcp \
  -H "Content-Type: application/json" \
  -d '{"method": "tools/list"}'
```

---

## Troubleshooting

### Build Fails: Module Not Found

**Issue:** Can't find `dcisionai_mcp_server`
**Fix:** Ensure `dcisionai_mcp_server/` directory is in repo root

### Server Not Starting

**Issue:** Port binding error
**Fix:** Railway sets `PORT` automatically, ensure start script uses it

### Import Errors

**Issue:** `ModuleNotFoundError: No module named 'fastmcp'`
**Fix:** Check `dcisionai_mcp_server/requirements.txt` includes `fastmcp>=2.13.0`

### Health Check Fails

**Issue:** `/health` returns 404
**Fix:** FastMCP provides `/health` automatically, check logs for errors

---

## Cost Estimate

**Railway Pricing:**
- **Hobby Plan**: $5/month + usage
- **Pro Plan**: $20/month + usage

**MCP Server Usage:**
- Low traffic: ~$5-10/month
- Medium traffic: ~$10-20/month

**Total (Backend + MCP Server):**
- Low: ~$10-15/month
- Medium: ~$25-40/month

---

## Next Steps

1. ✅ Create Railway service
2. ✅ Configure start command
3. ✅ Set environment variables
4. ✅ Deploy
5. ✅ Test MCP server
6. ✅ Update clients to use Railway URL

---

## References

- Railway Docs: https://docs.railway.app/
- Railway Python Guide: https://docs.railway.app/guides/python
- FastMCP Docs: https://fastmcp.wiki/
- Your Backend: https://dcisionai-mcp-platform-production.up.railway.app

