Skip to content

Canonical MCP Structures

Overview

This section documents the standardized approach for integrating Model Context Protocol (MCP) servers with WorkBuddy across our organization. Following a canonical structure ensures consistency, maintainability, and enables automated setup by AI agents.

Why Canonical Structures?

Integrating new MCP servers (Odoo, GitHub, Notion, Cloudflare, etc.) typically involves similar steps:

  1. Package Installation – Python, npm, or other package managers
  2. Configuration Management – Credentials, endpoints, settings
  3. MCP Registration – Updating WorkBuddy's mcp.json
  4. Environment Setup – Environment variables for secrets
  5. Testing & Validation – Verifying the connection works

Without a standard approach, each integration becomes a one‑off exercise, leading to:

  • Inconsistent configurations
  • Duplication of effort
  • Difficulty in automation
  • Higher maintenance overhead

The Canonical Workflow

1. Package Installation Pattern

# Python packages
pip install <mcp-package-name>

# npm packages
npm install -g <mcp-package-name>

# Other package managers – follow provider documentation

2. Configuration Template Creation

Create a service‑specific configuration template file in the workspace:

{
  "url": "default_or_placeholder_endpoint",
  "username": "placeholder_username",
  "apiKey": "placeholder_api_key",
  "timeout": 60,
  "maxRetries": 3,
  "pollInterval": 60,
  "logLevel": "INFO"
}

File naming: <service>_config.json (e.g., odoo_config.json)

Purpose: Documents the expected configuration structure and provides a template for users to fill with real values.

3. MCP Server Registration

Update ~/.workbuddy/mcp.json with a structured server entry:

{
  "mcpServers": {
    "<service-name>": {
      "command": "<interpreter>",
      "args": ["<module-or-script>"],
      "env": {
        "SERVICE_URL": "${placeholder_from_config}",
        "SERVICE_USERNAME": "${placeholder_from_config}",
        "SERVICE_API_KEY": "${placeholder_from_config}",
        "SERVICE_TIMEOUT": "60",
        "SERVICE_MAX_RETRIES": "3",
        "SERVICE_LOG_LEVEL": "INFO"
      }
    }
  }
}

4. Environment Variable Convention

  • Uppercase with service prefix: SERVICE_* (e.g., ODOO_*, GITHUB_*)
  • Separate credentials from configuration: URL, DB, USERNAME, API_KEY
  • Include operational settings: TIMEOUT, MAX_RETRIES, POLL_INTERVAL, LOG_LEVEL

5. Testing Protocol

# Verify package installation
python -m <module_name> --help

# Test module import
python -c "import <module>; print('Module loaded successfully')"

# Check MCP server configuration
# (After WorkBuddy restart/MCP reload)

Compliance Checklist

For any new MCP integration, verify:

  • [ ] Installation command documented
  • [ ] Configuration template file created
  • [ ] mcp.json entry with proper env‑var structure
  • [ ] Environment variables follow naming convention
  • [ ] Basic package test performed

Example Implementation: Odoo MCP

See the Odoo MCP Connection for a complete, real‑world example following this canonical structure.

Benefits

Consistency

All MCP integrations follow the same structure, making them predictable and easier to understand.

Automation

AI agents can reliably perform future MCP setups using this pattern, reducing manual work.

Documentation

Configuration templates serve as live documentation, always reflecting the current required fields.

Maintainability

Standardized environment variables make debugging, rotation, and updates straightforward.

Portability

Configurations can be version‑controlled separately from credentials, enabling safe sharing and reuse.

Governance

Review Process

New MCP connections should be reviewed against this canonical structure before being added to production.

Updates to the Canonical Structure

Proposed changes to the canonical workflow should be documented as an Architecture Decision Record (ADR) and reviewed by the platform team.

Non‑Compliance Handling

If a service cannot follow this structure due to unique requirements, document the deviation and the reasons in the service's connection documentation.

Last Updated: 2026‑05‑19
Owner: Platform Team
Status: Active and Enforced ✅