MWID MCP Server

Model Context Protocol (MCP) server for the MetaWealth Asset Launch Dashboard. This server enables AI assistants like ChatGPT and Claude to interact with the MWID Dashboard API for asset management, task tracking, and team collaboration.

Features

• 🔧 Comprehensive Tool Suite: 40+ tools for assets, tasks, users, departments, and teams
• 🔐 Multiple Auth Methods: JWT, Supabase, and Google OAuth support
• 📊 Real-time Data: Access to live dashboard data via REST API
• 🌐 SSE Transport: Server-Sent Events for reliable AI assistant connections
• 🚀 Production Ready: Dockerized and optimized for cloud deployment

Deploy to Railway

Step-by-Step Deployment

1. Push to GitHub:

   git add .
   git commit -m "Add Railway configuration"
   git push origin main
   

2. Create New Project on Railway:

   • Go to railway.app
   • Click "New Project"
   • Select "Deploy from GitHub repo"
   • Choose your repository: mwid-mcp-server

3. Configure Environment Variables:

   In Railway Dashboard → Variables, add these required variables:

   MWID_API_URL=https://your-backend-api.com/api/v1
   MWID_AUTH_METHOD=jwt
   MWID_JWT_TOKEN=your-jwt-token-here
   

   Optional variables:

   MWID_REQUEST_TIMEOUT=30
   MWID_DEBUG=false
   

4. Railway Auto-Detection:

   Railway will automatically detect:

   • ✅ Dockerfile for containerized deployment
   • ✅ railway.json for build/deploy configuration
   • ✅ Procfile for process management
   • ✅ Port configuration (Railway sets PORT automatically)

5. Deploy:

   Railway will automatically build and deploy. Monitor the deployment in the Railway dashboard logs.

6. Get Your MCP Server URL:

   Railway provides a public URL like: https://mwid-mcp-server-production-xxxx.up.railway.app

   You can also set a custom domain in Railway settings.

7. Configure Your AI Assistant:

   • ChatGPT: Add MCP server at https://your-railway-url.railway.app/sse
   • Claude Desktop: Add to claude_desktop_config.json (see configuration below)

Manual Deployment

Prerequisites

• Python 3.13+
• pip
• Docker (optional)

Local Development

# Clone the repository
git clone https://github.com/MetaWealth/mwid-mcp-server.git
cd mwid-mcp-server

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Create .env file
cat > .env << EOF
MWID_API_URL=http://localhost:8080/api/v1
MWID_AUTH_METHOD=jwt
MWID_JWT_TOKEN=your-token-here
EOF

# Run the server
python serve.py

Server will start on http://localhost:8000

Docker Deployment

# Build image
docker build -t mwid-mcp-server .

# Run container
docker run -p 8000:8000 \
  -e MWID_API_URL=https://your-api.com/api/v1 \
  -e MWID_AUTH_METHOD=jwt \
  -e MWID_JWT_TOKEN=your-token \
  mwid-mcp-server

Configuration

Environment Variables

Variable	Required	Default	Description
MWID_API_URL	Yes	http://localhost:8080/api/v1	Backend API endpoint
MWID_AUTH_METHOD	Yes	jwt	Authentication method: jwt, supabase, or google
MWID_JWT_TOKEN	For JWT	-	JWT authentication token
MWID_SUPABASE_URL	For Supabase	-	Supabase project URL
MWID_SUPABASE_KEY	For Supabase	-	Supabase anon key
MWID_GOOGLE_ACCESS_TOKEN	For Google	-	Google OAuth access token
PORT	No	8000	Server port (Railway sets automatically)

ChatGPT Configuration

Add the MCP server in ChatGPT settings:

Server URL: https://your-app.railway.app/sse

Claude Desktop Configuration

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "mwid-dashboard": {
      "url": "https://your-app.railway.app/sse"
    }
  }
}

Available Tools

The server provides 40+ tools organized into these categories:

✅ Working Features (External API - No JWT Required)

These tools work immediately with just the MWID_EXTERNAL_API_KEY:

Sales & Investor Data

• list_manual_sales - List sales records with filtering/pagination (3,692+ records)
  • Filters: userId, assetId, adjustmentType
  • Pagination: page, pageSize (max 500)
• get_manual_sale - Get specific sale details by ID
• list_manual_investors - List investor records with filtering/pagination (1,064+ records)
  • Filters: email, userId, country
  • Pagination: page, pageSize (max 500)
• get_manual_investor - Get specific investor details by ID

⚠️ Future Features (Internal API - Requires JWT Token)

These tools require MWID_JWT_TOKEN to be configured. They will return 403 errors until JWT authentication is set up.

Asset Management

• get_current_user - Get authenticated user info
• list_assets - List all assets
• get_asset - Get asset details
• create_asset - Create new asset
• update_asset - Update asset
• delete_asset - Delete asset (admin only)
• get_asset_phases - Get asset phases
• get_asset_tasks - Get tasks for asset
• calculate_minimum_time - Calculate task completion time

Task Management

• get_task - Get task details
• update_task - Update task
• assign_task - Assign task to user
• unassign_task - Remove task assignment
• get_assigned_tasks - Get user's assigned tasks
• get_unassigned_tasks - Get unassigned tasks
• get_my_department_tasks - Get department tasks
• get_task_comments - Get task comments
• create_task_comment - Add comment to task
• get_task_progress - Get task progress
• update_task_progress - Update task progress

Phase Management

• update_phase - Update phase details
• get_phase_tasks - Get tasks for a phase

User & Department Management

• list_users - List all users (admin only)
• get_user - Get user details
• get_users_for_assignment - Get assignable users
• get_my_team - Get team members
• get_department_members - Get department members
• list_departments - List departments
• get_department - Get department details
• get_department_stats - Get department statistics

Notifications

• get_notifications - Get user notifications
• get_unread_notification_count - Get unread count
• mark_notification_read - Mark notification as read
• mark_all_notifications_read - Mark all as read

Workflow Templates

• list_workflow_templates - List available templates
• get_workflow_template - Get template details
• apply_workflow_template - Apply template to asset

Legacy Internal API

• list_investor_records - List internal investor records
• get_investor_record - Get internal investor record details

Architecture

┌─────────────┐         ┌──────────────┐         ┌─────────────┐
│  ChatGPT/   │  SSE    │  MCP Server  │  HTTP   │   MWID      │
│   Claude    │◄────────┤  (Railway)   │────────►│  Backend    │
└─────────────┘         └──────────────┘         └─────────────┘
                         /sse endpoint             REST API
                         /messages endpoint        (8080)

Troubleshooting

Connection Timeout

Issue: ChatGPT times out connecting to the server

Solution:

• Ensure Railway deployment is running (check Railway dashboard)
• Verify environment variables are set correctly
• Check Railway logs for errors: railway logs

403 Forbidden

Issue: Getting 403 errors

Solution:

• Check MWID_JWT_TOKEN is valid and not expired
• Verify backend API is accessible from Railway
• Ensure backend CORS settings allow Railway domain

Empty Responses

Issue: Tools return empty data

Solution:

• Verify MWID_API_URL points to correct backend
• Check JWT token has necessary permissions
• Test backend API directly with curl/Postman

Development

Running Tests

python test_server.py

Debug Logging

Enable debug logging:

export MWID_DEBUG=true
python serve.py

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

License

MIT License - see LICENSE file for details

Support

For issues or questions:

• GitHub Issues: https://github.com/MetaWealth/mwid-mcp-server/issues
• Documentation: https://your-docs-site.com
• Email: support@metawealth.co