MCP_Server_and_Agents-Fat-Earth

niccolo-redantlergroup/MCP_Server_and_Agents-Fat-Earth

3.2

If you are the rightful owner of MCP_Server_and_Agents-Fat-Earth and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

A centralized MCP connector deployed on Google Cloud Run, providing custom AI skills for your team within the Claude.ai environment.

Tools
7
Resources
0
Prompts
0

MCP Connector for Claude

A centralized MCP (Model Context Protocol) connector deployed on Google Cloud Run, providing custom AI skills for your team within the Claude.ai environment.

Overview

This project provides seamless, centralized, and automatic access to custom AI skills for all team members on a Claude team plan. The connector is deployed to Google Cloud Run (GCR) for reliable 24/7 availability and is registered in your organization's Claude Admin settings.

Project Structure

mcp-agents/
├── mcp-connector/         # MCP server implementation and deployment
│   ├── server.py          # FastMCP server with agent tools
│   ├── Dockerfile         # Container configuration
│   ├── deploy.sh          # Deployment script
│   ├── test_mcp.sh        # Endpoint testing script
│   └── requirements.txt   # Python dependencies
├── skills/                # Agent implementations
│   └── Agents Code/      # All agent modules (7 agents)
├── utils/                 # Shared utilities
│   ├── benchmark_loader.py
│   ├── recommendation_builder.py
│   └── validation.py
├── config/                # Configuration files
│   ├── agent_config.json
│   └── benchmarks.json
├── schemas/               # Data contracts and schemas
│   ├── error_codes.json
│   ├── output_structures.json
│   └── universal_data_contracts.json
├── tests/                 # Test suite
│   ├── test_agents.py
│   └── fixtures/
├── cursor-context/        # Essential docs for Cursor AI agents
│   ├── 01_how_to_update_agents.md
│   ├── 02_deployment.md
│   ├── 03_server_api_reference.md
│   └── ... (see cursor-context/README_cursor_context.md)
├── docs/                  # Documentation
│   ├── how-to/           # Setup, deployment, adding skills
│   ├── reference/        # API references, guides, protocols
│   ├── reports/          # Diagnostic and compliance reports
│   └── archive/          # Historical documentation
├── archive/               # Archived code and files
│   └── agents/           # Historical agent versions
└── README.md             # This file

For detailed documentation, see directory.

Architecture

  • Server Framework: FastMCP with streamable-http transport
  • Deployment Platform: Google Cloud Run
  • Container Registry: Google Artifact Registry
  • Service Account: mcp-runtime@klaviyo-mcp-agents.iam.gserviceaccount.com

Deployment Information

  • Project ID: klaviyo-mcp-agents
  • Region: us-central1
  • Service Name: mcp-connector
  • Service URL: https://mcp-connector-553016312267.us-central1.run.app
  • MCP Endpoint: https://mcp-connector-553016312267.us-central1.run.app/mcp
  • Current Image: us-central1-docker.pkg.dev/klaviyo-mcp-agents/mcp/mcp-server:0.6

Setup and Deployment

Prerequisites

  • Google Cloud SDK installed and authenticated
  • Access to klaviyo-mcp-agents project
  • Claude Team/Enterprise plan with Admin access

Quick Deploy

cd mcp-connector
./deploy.sh

For detailed deployment instructions, see .

Adding Tools

Quick Start: For Cursor AI agents, see the folder which contains all essential documentation. For manual workflows, see and .

Overview: Add new tools by editing server.py and adding functions decorated with @mcp.tool(). Use Claude with the format guide to generate properly formatted tool code, then integrate and deploy.

Workflow:

  1. Upload format guide to Claude (see cursor-context/07_output_format_guide.md)
  2. Request skill code from Claude using the prompt template
  3. Add agent module to skills/Agents Code/
  4. Register in mcp-connector/server.py
  5. Deploy: cd mcp-connector && ./deploy.sh
  6. Refresh Claude connector to see new tool

Documentation:

  • - Essential docs for Cursor AI agents (start here!)
  • - Technical patterns and examples
  • - Complete step-by-step process

Registering in Claude

  1. Navigate to Claude Admin settings (Team/Enterprise) or Settings (Pro/Max)
  2. Go to Connectors section
  3. Click "Add custom connector"
  4. Enter:
    • Name: MCP-Agents (or your preferred name)
    • Remote MCP server URL: https://mcp-connector-553016312267.us-central1.run.app/mcp
  5. Click "Add"
  6. Enable the connector in your chat settings

Current Tools (v2.0)

All tools now support:

  • Structured JSON Envelopes: Standardized response format with status, analysis, recommendations, warnings, errors, metadata, and input_summary
  • Tiered Recommendations: Recommendations organized into Quick Wins, Strategic Initiatives, and Long-Term Opportunities with full metadata (priority, impact, effort, timeline)
  • Previous Analyses Context: Optional previous_analyses parameter for cross-agent intelligence and conflict detection
  • Schema Validation: Input validation with data quality scoring and graceful degradation
  • Execution Metrics: Execution time tracking and confidence scoring in metadata

Available Agents

  1. Performance Analyst - Campaign/flow performance analysis with anomaly detection
  2. Revenue Strategist - Revenue optimization and AOV analysis
  3. Email Marketing Consultant - Strategic email marketing guidance with priority focus
  4. Customer Intelligence Specialist - Customer behavior and lifecycle analysis
  5. Growth Marketer - Acquisition, retention, and attribution analysis
  6. Deliverability Expert - Email deliverability diagnostics
  7. Automation Architect - Flow architecture and optimization analysis

Schema & Configuration Files

  • Schemas: schemas/universal_data_contracts.json, schemas/output_structures.json, schemas/error_codes.json
  • Benchmarks: config/benchmarks.json (industry-specific benchmark data)
  • Agent Config: config/agent_config.json (per-agent thresholds and settings)
  • Test Fixtures: tests/fixtures/*.json (sample data for testing)

Running Tests

# Run the full test suite
pytest tests/test_agents.py -v

Tests validate:

  • Success/partial_success/error envelope flows
  • Recommendation tier structure
  • Anomaly detection with confidence scoring
  • Previous analyses context handling
  • Schema validation and data quality scoring
  • Multi-agent chaining and error propagation
  • Performance with large (100 campaigns) and minimal (1 campaign) datasets
  • Output quality (recommendation completeness, human-readable formatting, metadata accuracy)
  • Type safety and edge cases (JSON strings, empty lists, etc.)

Monitoring

View Logs

gcloud run services logs read mcp-connector --region us-central1 --limit 100

Check Service Status

gcloud run services describe mcp-connector --region us-central1

Pre-Deployment Checklist

  1. Run test suite: pytest tests/test_agents.py
  2. Verify all agents are registered in mcp-connector/server.py
  3. Deploy: cd mcp-connector && ./deploy.sh
  4. Test endpoint: cd mcp-connector && ./test_mcp.sh
  5. Restart Claude connector and verify tools are available

Test Endpoint

curl -i -N \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream, application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"client":{"name":"test","version":"1.0"},"capabilities":{}}}' \
  https://mcp-connector-553016312267.us-central1.run.app/mcp

Service Accounts

  • Runtime SA: mcp-runtime@klaviyo-mcp-agents.iam.gserviceaccount.com

    • Used by Cloud Run to run the service
    • Roles: Artifact Registry Reader

  • CI SA: mcp-ci@klaviyo-mcp-agents.iam.gserviceaccount.com

    • Used for building and deploying
    • Roles: Cloud Build Editor, Artifact Registry Writer, Cloud Run Admin
    • Has "Service Account User" permission on runtime SA

Security Considerations

  • Authentication: Cloud Run service is now configured with --no-allow-unauthenticated, requiring IAM authentication.
  • Production Setup:
    • Configure OAuth 2.0 for secure access from Claude.
    • Ensure the calling service account has roles/run.invoker.
    • Consider restricting access to specific IPs/domains and adding rate limiting.

Troubleshooting

Connector shows "Disconnected"

  • Verify the URL includes /mcp at the end
  • Check Cloud Run logs for errors
  • Ensure the service is running and healthy

Tools not appearing in Claude

  • Check that the connector is enabled in Claude settings
  • Verify tools are properly decorated with @mcp.tool()
  • Review Cloud Run logs for tool registration errors

Deployment fails

  • Verify service account permissions
  • Check Artifact Registry repository exists
  • Ensure Cloud Run API is enabled

References

Version History

  • v0.8 (2025-11-12): Added Performance Analyst tool, removed ping tool

    • Implemented performance_analyst tool for comprehensive performance analysis
    • Added statistical analysis, anomaly detection, and recommendation generation
    • Removed test ping tool
    • Created workflow documentation for adding new skills

  • v0.6 (2025-11-12): Initial deployment with FastMCP run_async() using streamable-http transport

    • Implemented ping tool
    • Configured for Google Cloud Run deployment
    • Successfully tested with Claude connector

License

Internal project for Klaviyo team use.