mcp-servers/gateway-proxy/INTEGRATION_INSTRUCTIONS.md

Dashboard Integration into gateway_proxy.py

Quick Integration Guide

Step 1: Add Imports at Top of gateway_proxy.py

import asyncio
from dashboard_routes import setup_dashboard_routes
from fastapi.staticfiles import StaticFiles

Step 2: Mount Static Files (After app creation)

Find where the FastAPI app is created (likely app = FastAPI(...)) and add after it:

# Setup static file serving for dashboard
try:
    app.mount("/", StaticFiles(directory="dashboard", html=True), name="static")
except Exception as e:
    print(f"Warning: Could not mount dashboard static files: {e}")

Step 3: Register Dashboard Routes (In app startup/initialization)

In the startup event or app initialization section, add:

@app.on_event("startup")
async def startup_event():
    # ... existing startup code ...

    # Setup dashboard routes
    try:
        dashboard_router = await setup_dashboard_routes(app)
        app.include_router(dashboard_router)
        print("✓ Dashboard routes registered")
    except Exception as e:
        print(f"Warning: Could not setup dashboard routes: {e}")

Step 4: Update Dockerfile

In gateway-proxy/Dockerfile, add a line to copy the dashboard:

# ... existing COPY commands ...

# Copy dashboard
COPY dashboard/ /app/dashboard/

Step 5: Verify dashboard_routes.py Dependencies

Make sure dashboard_routes.py has these imports available in your environment.

Required packages:

• aiohttp (likely already installed for MCP communication)
• asyncio (builtin)
• fastapi (already in use)

Complete Example Integration

Here's what a minimal integration looks like:

# gateway_proxy.py

import asyncio
from fastapi import FastAPI
from fastapi.staticfiles import StaticFiles
from dashboard_routes import setup_dashboard_routes

# Create app
app = FastAPI(title="MCP Gateway")

# Mount dashboard
app.mount("/", StaticFiles(directory="dashboard", html=True), name="dashboard")

@app.on_event("startup")
async def startup():
    dashboard_router = await setup_dashboard_routes(app)
    app.include_router(dashboard_router)
    print("Dashboard ready at /dashboard")

# ... rest of your routes ...

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=4444)

Testing After Integration

1. Rebuild the gateway image:

   docker compose build mcp-gateway
   

2. Restart the gateway:

   docker compose up mcp-gateway
   

3. Access the dashboard:

   • Local: http://localhost:4444/dashboard
   • Remote: https://mcp.wilddragon.net/dashboard

4. Test the API endpoint:

   curl http://localhost:4444/mcp/status | jq
   

Troubleshooting Integration

Module Not Found: dashboard_routes

• Ensure dashboard_routes.py is in the same directory as gateway_proxy.py
• Check Python path is correct

Dashboard Returns 404

• Verify dashboard/ folder exists in the gateway root
• Check dashboard.html file exists
• Review Dockerfile to ensure it copies the dashboard

Routes Not Registered

• Check startup event is being called
• Review application logs
• Verify no errors in dashboard_routes.py

CSS/TailwindCSS Not Loading

• This is expected since TailwindCSS is loaded via CDN in the HTML
• Check browser console for any fetch errors
• Verify network connectivity to cdn.tailwindcss.com

File Structure After Integration

mcp-gateway/
├── gateway-proxy/
│   ├── gateway_proxy.py          (MODIFIED - add imports & routes)
│   ├── dashboard_routes.py       (NEW)
│   ├── Dockerfile                (MODIFIED - add COPY dashboard)
│   └── ...
├── dashboard/
│   └── dashboard.html            (NEW)
├── docker-compose.yml
└── ...

Performance Considerations

• Dashboard queries all services on each status check
• Default refresh interval: 30 seconds
• Each check times out after 5 seconds per service
• Status queries run in parallel (async)
• No caching of results (fresh data each time)

To adjust refresh interval, edit dashboard/dashboard.html and find:

const interval = setInterval(fetchServiceStatus, 30000);  // 30 seconds

Change 30000 to desired milliseconds (e.g., 15000 for 15 seconds).