MCP Integration for Internal Systems

🔒 Internal Use Only - AI-powered development and operational tools for the AltSportsData team.

Internal Documentation

This page contains internal tools and workflows for the AltSportsData development team. External users should not have access to these capabilities.

Overview

The internal MCP server configuration provides development and operations teams with:

Development Tools - Code generation, testing, debugging
Database Operations - Direct database access and migrations
Deployment Management - CI/CD control and environment management
Internal Analytics - Business intelligence and metrics
System Administration - Advanced platform control

Quick Setup

Configure for Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "altsportsdata-internal": {
      "command": "npx",
      "args": ["-y", "@altsportsdata/mcp-server-internal"],
      "env": {
        "API_KEY": "internal-team-api-key",
        "ROLE": "internal_developer",
        "ENVIRONMENT": "development",
        "DATABASE_ACCESS": "true"
      }
    }
  }
}

Available Tools

1. Database Query Tool

Execute database queries for debugging and analysis.

{
  "name": "query_database",
  "arguments": {
    "database": "production_readonly",  // readonly replica for safety
    "query": "SELECT COUNT(*) FROM matches WHERE status = 'live'",
    "timeout": 30
  }
}

Safety Features:

Read-only access by default
Query timeout enforcement
Automatic query logging
Dangerous operation detection

2. Generate Code

AI-powered code generation for common patterns.

{
  "name": "generate_code",
  "arguments": {
    "template": "api_endpoint",
    "specifications": {
      "endpoint": "/api/v1/teams/:id/stats",
      "method": "GET",
      "authentication": "required",
      "response_schema": "team_stats_v2"
    },
    "language": "typescript",
    "framework": "express"
  }
}

3. Deploy Service

Manage deployments across environments.

{
  "name": "deploy_service",
  "arguments": {
    "service": "api-server",
    "environment": "staging",
    "version": "v2.5.0",
    "strategy": "blue_green",
    "run_tests": true,
    "auto_rollback": true
  }
}

4. Query Internal Metrics

Access business intelligence and operational metrics.

{
  "name": "query_internal_metrics",
  "arguments": {
    "metric_type": "revenue",
    "breakdown": ["partner", "tier", "sport"],
    "timeframe": "30d",
    "compare_to": "previous_period"
  }
}

Response:

{
  "period": "2024-10-19 to 2024-11-18",
  "total_revenue": 125000,
  "growth": 0.18,
  "breakdown": {
    "by_tier": {
      "tier_1": 85000,
      "tier_2": 30000,
      "tier_3": 10000
    },
    "by_sport": {
      "basketball": 55000,
      "soccer": 45000,
      "football": 25000
    }
  }
}

5. Debug Production Issue

Tools for investigating production problems.

{
  "name": "debug_production",
  "arguments": {
    "issue_type": "slow_endpoint",
    "endpoint": "/api/v1/matches/live",
    "timeframe": "1h",
    "include_traces": true,
    "include_logs": true
  }
}

Internal Workflows

Workflow 1: Feature Development

Developer: "Create a new API endpoint for player injury history"

AI Agent (using MCP):
1. Generates code skeleton with generate_code
2. Creates database schema with generate_migration
3. Generates tests with generate_tests
4. Creates API documentation with generate_docs
5. Sets up monitoring with configure_monitoring

Result: Complete feature implementation ready for review

Workflow 2: Production Debugging

Developer: "API response time is slow for /matches/live"

AI Agent (using MCP):
1. Queries metrics with query_internal_metrics
2. Analyzes logs with analyze_logs
3. Profiles queries with profile_database_queries
4. Identifies bottleneck with find_performance_issues
5. Suggests optimization with recommend_fixes

Result: Root cause identified with fix recommendations

Workflow 3: Data Migration

Developer: "Migrate league tier data to new schema"

AI Agent (using MCP):
1. Analyzes current schema with analyze_schema
2. Generates migration with generate_migration
3. Creates rollback plan with create_rollback
4. Tests migration with test_migration
5. Executes migration with execute_migration

Result: Safe data migration with rollback capability

Workflow 4: Partner Onboarding

Developer: "Set up new tier 1 sportsbook partner"

AI Agent (using MCP):
1. Creates partner account with create_partner
2. Provisions infrastructure with provision_resources
3. Configures access with setup_access
4. Generates API keys with generate_keys
5. Sets up monitoring with configure_partner_monitoring

Result: Fully configured partner environment

Development Tools

Code Generation Templates

Available templates for common patterns:

Template	Description	Output
`api_endpoint`	REST API endpoint	TypeScript/Express
`database_model`	ORM model	Prisma schema
`migration`	Database migration	SQL/Prisma migration
`test_suite`	Unit and integration tests	Jest tests
`schema`	Data schema definition	JSON Schema/TypeScript
`documentation`	API documentation	Markdown/OpenAPI

Testing Tools

{
  "name": "run_tests",
  "arguments": {
    "test_suite": "api_endpoints",
    "environment": "testing",
    "coverage": true,
    "parallel": true,
    "filters": ["integration", "e2e"]
  }
}

Database Tools

// Generate migration
{
  "name": "generate_migration",
  "arguments": {
    "description": "add_player_injury_fields",
    "changes": [
      {
        "table": "players",
        "add_columns": [
          {"name": "injury_status", "type": "varchar(50)"},
          {"name": "expected_return_date", "type": "date"}
        ]
      }
    ]
  }
}
 
// Profile queries
{
  "name": "profile_queries",
  "arguments": {
    "duration": "1h",
    "min_duration_ms": 100,
    "include_explain_plan": true
  }
}

Deployment Management

Environment Management

{
  "environments": {
    "development": {
      "url": "https://dev-api.altsportsdata.com",
      "database": "dev",
      "auto_deploy": "main_branch"
    },
    "staging": {
      "url": "https://staging-api.altsportsdata.com",
      "database": "staging",
      "manual_approval": true
    },
    "production": {
      "url": "https://api.altsportsdata.com",
      "database": "production",
      "manual_approval": true,
      "require_review": 2
    }
  }
}

Deployment Strategies

// Blue-Green Deployment
{
  "name": "deploy_service",
  "arguments": {
    "strategy": "blue_green",
    "health_check_endpoint": "/health",
    "traffic_switch_delay": "5m",
    "keep_old_version": "30m"
  }
}
 
// Canary Deployment
{
  "name": "deploy_service",
  "arguments": {
    "strategy": "canary",
    "canary_percentage": 10,
    "canary_duration": "1h",
    "success_criteria": {
      "error_rate": "&lt;1%",
      "response_time_p95": "&lt;200ms"
    }
  }
}

Rollback

{
  "name": "rollback_deployment",
  "arguments": {
    "service": "api-server",
    "environment": "production",
    "to_version": "v2.4.8",
    "reason": "High error rate detected"
  }
}

Internal Analytics

Business Metrics

{
  "name": "get_business_metrics",
  "arguments": {
    "metrics": [
      "monthly_recurring_revenue",
      "active_partners",
      "api_usage_by_tier",
      "churn_rate",
      "customer_lifetime_value"
    ],
    "timeframe": "90d",
    "granularity": "daily"
  }
}

Platform Health Metrics

{
  "name": "get_platform_metrics",
  "arguments": {
    "metrics": [
      "api_uptime",
      "database_performance",
      "cache_hit_rate",
      "error_rate_by_endpoint",
      "active_websocket_connections"
    ],
    "timeframe": "24h"
  }
}

Cost Analysis

{
  "name": "analyze_costs",
  "arguments": {
    "breakdown": ["service", "environment", "team"],
    "services": ["cloud_run", "neo4j", "openai", "pinecone"],
    "timeframe": "30d",
    "compare_to_budget": true
  }
}

System Administration

Infrastructure Management

{
  "name": "manage_infrastructure",
  "arguments": {
    "action": "scale",
    "service": "api-server",
    "target_instances": 10,
    "environment": "production"
  }
}

Secret Management

{
  "name": "manage_secrets",
  "arguments": {
    "action": "rotate",
    "secret_name": "database_password",
    "environment": "production",
    "notify_team": true
  }
}

Backup Management

{
  "name": "manage_backups",
  "arguments": {
    "action": "create",
    "resources": ["database", "neo4j", "config"],
    "backup_type": "full",
    "retention": "30d"
  }
}

Integration Examples

TypeScript Integration

import { MCPClient } from '@modelcontextprotocol/sdk';
 
const internalClient = new MCPClient({
  serverUrl: 'http://localhost:3000/mcp-internal',
  apiKey: process.env.INTERNAL_API_KEY,
  role: 'internal_developer'
});
 
// Query database
const result = await internalClient.call('query_database', {
  database: 'production_readonly',
  query: 'SELECT COUNT(*) FROM active_matches'
});
 
// Deploy service
const deployment = await internalClient.call('deploy_service', {
  service: 'api-server',
  environment: 'staging',
  version: 'v2.5.0'
});

Python Integration

from altsportsdata_mcp import InternalMCPClient
 
client = InternalMCPClient(
    api_key=os.getenv('INTERNAL_API_KEY'),
    role='internal_developer'
)
 
# Generate code
code = client.call_tool('generate_code', {
    'template': 'api_endpoint',
    'specifications': {...}
})
 
# Query metrics
metrics = client.call_tool('query_internal_metrics', {
    'metric_type': 'revenue',
    'timeframe': '30d'
})

Example Prompts

Development

"Generate a new API endpoint for team rosters"
"Create tests for the partnership scoring module"
"Generate a migration to add injury tracking fields"

Operations

"Deploy the API server to staging"
"What's our current production error rate?"
"Show me slow database queries from the past hour"

Analytics

"What's our MRR growth this quarter?"
"Show API usage breakdown by partner tier"
"Calculate customer lifetime value by sport"

Debugging

"Why is the /matches/live endpoint slow?"
"Find all errors related to user authentication"
"Show me the deployment history for the API server"

Security Considerations

Access Control

Internal tools require elevated permissions
All operations are logged and audited
Database write access requires explicit approval
Production deployments require code review

Best Practices

Use Read-Only Access: Default to readonly database replicas
Test in Staging First: Always test changes in staging
Review Before Deployment: Require peer review for production
Monitor After Changes: Watch metrics after deployments
Document Decisions: Log rationale for manual interventions

Audit Logging

All internal tool usage is logged:

User/AI agent identity
Action performed
Timestamp
Result/outcome
Approval chain (if applicable)

Emergency Procedures

Incident Response

{
  "name": "initiate_incident_response",
  "arguments": {
    "severity": "critical",
    "description": "API servers unresponsive",
    "affected_services": ["api-server", "websocket-server"],
    "notify": ["on_call", "leadership"]
  }
}

Emergency Rollback

{
  "name": "emergency_rollback",
  "arguments": {
    "service": "all",
    "to_version": "last_stable",
    "skip_checks": false,  // Still run basic health checks
    "notify_team": true
  }
}

Troubleshooting

Common Issues

Issue: Cannot access production database

Solutions:

Verify VPN connection
Check database credentials
Confirm IP whitelist
Use readonly replica for queries

Issue: Deployment fails validation

Solutions:

Review test results
Check health check endpoint
Verify environment variables
Review deployment logs

Issue: Internal metrics not updating

Solutions:

Check data pipeline status
Verify BigQuery connection
Review ETL job logs
Validate data sources

Support Resources

Next Steps

Internal Dashboard

Access internal metrics and monitoring

Open Dashboard →

Deployment Pipeline

View CI/CD status and deploy services

Open Pipeline →

Admin Tools n8n Workflows

MCP Integration for Internal Systems

Internal Documentation

Overview

Quick Setup

Configure for Claude Desktop

Available Tools

1. Database Query Tool

2. Generate Code

3. Deploy Service

4. Query Internal Metrics

5. Debug Production Issue

Internal Workflows

Workflow 1: Feature Development

Workflow 2: Production Debugging

Workflow 3: Data Migration

Workflow 4: Partner Onboarding

Development Tools

Code Generation Templates

Testing Tools

Database Tools

Deployment Management

Environment Management

Deployment Strategies

Rollback

Internal Analytics

Business Metrics

Platform Health Metrics

Cost Analysis

System Administration

Infrastructure Management

Secret Management

Backup Management

Integration Examples

TypeScript Integration

Python Integration

Example Prompts

Development

Operations

Analytics

Debugging

Security Considerations

Access Control

Best Practices

Audit Logging

Emergency Procedures

Incident Response

Emergency Rollback

Troubleshooting

Common Issues

Support Resources

Next Steps

Internal Dashboard

Deployment Pipeline

Platform

Documentation

Community

Support