Wayve MCP Server (Remote)

Remote MCP server for Wayve with OAuth authentication via Microsoft Entra External ID.

Overview

This server exposes Wayve tools via Streamable HTTP transport, enabling integration with Claude Code, Claude.ai, and other MCP clients.

Authentication uses Microsoft Entra External ID OAuth 2.1 with PKCE, allowing users to log in via their Wayve account.

Features

• OAuth 2.1 + PKCE authentication via Entra External ID
• Streamable HTTP transport for remote MCP connections
• All Wayve tools:
  • Activities (CRUD, bulk operations)
  • Buckets (life areas)
  • Projects (goals tracking)
  • Time Locks (recurring blocked time)
  • Week Reviews (reflections, rituals)
  • Planning (context aggregation, availability calculation)

AI Agent Optimization

This server is optimized for AI agents (Claude, ChatGPT, etc.) to help users plan their week:

Planning Tools

| Tool | Description | |------|-------------| | wayve_get_planning_context | Get complete planning context in 1 call (buckets, activities, time locks, preferences, last week review) | | wayve_get_availability | Calculate available time slots per day with blocked_by info |

Semantic Metadata

Activities and Buckets support semantic fields for smarter scheduling:

Activities:

• priority (1-5): Higher priority = schedule first
• energy_required (high/medium/low): Match with user's energy patterns
• time_flexibility (fixed/flexible): Fixed activities can't be moved
• location_context (home/office/gym/outdoors/anywhere): Group by location

Buckets:

• target_hours_per_week: Goal hours for life balance
• preferred_time_slot (morning/afternoon/evening/flexible): Best time for bucket activities

Agent Flow

1. wayve_get_planning_context → Complete context
2. wayve_get_availability → Free time slots
3. Agent reasons about suggestions/scheduling
4. wayve_create_activity or wayve_bulk_create_activities

Setup

Prerequisites

• Node.js 18+
• Microsoft Entra External ID tenant with app registration
• Wayve API running

Environment Variables

# Microsoft Entra External ID
ENTRA_TENANT_SUBDOMAIN=wayve
ENTRA_TENANT_ID=your-tenant-id
ENTRA_CLIENT_ID=your-client-id

# Wayve API
WAYVE_API_URL=https://wayve-api.azurewebsites.net/api

# Server
PORT=3000
MCP_SERVER_URL=https://your-deployed-server.com

Local Development

# Install dependencies
npm install

# Run in development mode (with auto-reload)
npm run dev

# Build
npm run build

# Start production server
npm start

Testing with ngrok

For local testing with Claude Code:

# Start the server
npm run dev

# In another terminal, expose via ngrok
ngrok http 3000

Use the ngrok URL in Claude Code's MCP settings.

Endpoints

| Endpoint | Description | |----------|-------------| | GET /health | Health check | | GET /.well-known/oauth-protected-resource | OAuth resource metadata | | GET /.well-known/oauth-authorization-server | OAuth server metadata | | POST /mcp | MCP protocol endpoint |

OAuth Flow

1. Client requests /.well-known/oauth-protected-resource
2. Client initiates OAuth flow with Entra External ID
3. User authenticates via Wayve login
4. Client receives access token
5. Client makes MCP requests with Bearer token

Claude Code Configuration

Add to your Claude Code settings:

{
  "mcpServers": {
    "wayve": {
      "url": "https://wayve-mcp-server.azurecontainerapps.io/mcp",
      "transport": "streamable-http"
    }
  }
}

Or via UI: Settings → MCP Servers → Add → Enter URL.

Docker Deployment

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

# Run container
docker run -p 3000:3000 \
  -e ENTRA_TENANT_SUBDOMAIN=wayve \
  -e ENTRA_TENANT_ID=your-tenant-id \
  -e ENTRA_CLIENT_ID=your-client-id \
  -e WAYVE_API_URL=https://wayve-api.azurewebsites.net/api \
  wayve-mcp-server

Azure Container Apps Deployment

# Deploy to Azure Container Apps
az containerapp create \
  --name wayve-mcp-server \
  --resource-group wayve \
  --image wayve/mcp-server:latest \
  --target-port 3000 \
  --ingress external \
  --env-vars \
    ENTRA_TENANT_SUBDOMAIN=wayve \
    ENTRA_TENANT_ID=your-tenant-id \
    ENTRA_CLIENT_ID=your-client-id \
    WAYVE_API_URL=https://wayve-api.azurewebsites.net/api \
    MCP_SERVER_URL=https://wayve-mcp-server.azurecontainerapps.io

Entra App Registration

In Azure Portal → Entra External ID → App registrations:

1. Add redirect URIs for OAuth callbacks
2. Enable "Access tokens" in Authentication
3. Scopes: openid, profile, email

Security

• Tokens are validated via Entra JWKS endpoint
• Each request creates a fresh MCP server instance
• User's token is forwarded to Wayve API for authorization
• No credentials stored on the MCP server

Deployment Checklist

1. Database Migration (Required for Semantic Metadata)

Run the migration script on your Azure SQL database:

# Connect to Azure SQL and run:
# api-dotnet/Wayve.Api/Migrations/001_add_semantic_metadata.sql

This adds:

• priority, energy_required, time_flexibility, location_context to activities
• target_hours_per_week, preferred_time_slot to buckets

2. Deploy Backend API

The .NET API needs to be redeployed with the updated models.

3. Deploy MCP Server

# Build and deploy
npm run build
# Then deploy to Azure Container Apps (see above)

4. Test

# Via MCP Inspector or Claude Desktop
wayve_get_planning_context { "week": 6, "year": 2026 }
wayve_get_availability { "week": 6, "year": 2026 }