MCP Enterprise Patterns

name: mcp-enterprise-patterns description: Patterns for building and consuming enterprise MCP (Model Context Protocol) servers. Use when wrapping enterprise APIs (Salesforce, ServiceNow, SAP, Oracle) as MCP servers, or consuming MCP servers from Claude, OpenAI, or Gemini agents.

MCP Enterprise Integration Patterns

Patterns for building MCP servers that wrap enterprise APIs, and for consuming MCP servers across different AI agent frameworks (Claude, OpenAI Agents SDK, Google ADK).

When to Use

• Wrapping an enterprise REST API (Salesforce, ServiceNow, SAP OData) as an MCP server
• Connecting MCP servers to Claude Desktop, Claude Code, OpenAI Agents SDK, or Google ADK
• Building multi-tenant MCP servers with authentication and audit logging
• Designing MCP tool schemas for complex enterprise workflows

MCP Ecosystem Adoption

Patterns

1. Build an Enterprise MCP Server (Python/FastMCP)

from mcp.server.fastmcp import FastMCP
import httpx

mcp = FastMCP("Enterprise CRM Server")

# Configuration via environment
import os
CRM_BASE_URL = os.environ["CRM_BASE_URL"]
CRM_API_KEY = os.environ["CRM_API_KEY"]

@mcp.tool()
async def search_customers(query: str, limit: int = 10) -> list[dict]:
    """Search customers by name or email.

    Args:
        query: Search term (name, email, or phone)
        limit: Maximum results to return (default: 10)
    """
    async with httpx.AsyncClient() as client:
        response = await client.get(
            f"{CRM_BASE_URL}/api/customers/search",
            params={"q": query, "limit": limit},
            headers={"Authorization": f"Bearer {CRM_API_KEY}"},
        )
        response.raise_for_status()
        return response.json()["results"]


@mcp.tool()
async def create_ticket(
    customer_id: str,
    subject: str,
    description: str,
    priority: str = "medium",
) -> dict:
    """Create a support ticket for a customer.

    Args:
        customer_id: The customer's unique ID
        subject: Brief ticket subject (max 200 chars)
        description: Detailed description of the issue
        priority: Ticket priority: low, medium, high, critical
    """
    async with httpx.AsyncClient() as client:
        response = await client.post(
            f"{CRM_BASE_URL}/api/tickets",
            json={
                "customer_id": customer_id,
                "subject": subject,
                "description": description,
                "priority": priority,
            },
            headers={"Authorization": f"Bearer {CRM_API_KEY}"},
        )
        response.raise_for_status()
        return response.json()


@mcp.resource("crm://schema")
async def get_schema() -> str:
    """Return the CRM data model schema for agent context."""
    return """
    Customer: id, name, email, phone, company, created_at
    Ticket: id, customer_id, subject, description, priority, status, created_at
    Order: id, customer_id, items[], total, status, created_at
    """

2. Consume MCP from Claude Code

// .mcp.json (project-level MCP config)
{
  "mcpServers": {
    "enterprise-crm": {
      "command": "python",
      "args": ["-m", "crm_mcp_server"],
      "env": {
        "CRM_BASE_URL": "https://crm.example.com",
        "CRM_API_KEY": "${CRM_API_KEY}"
      }
    },
    "servicenow": {
      "command": "npx",
      "args": ["-y", "@community/mcp-server-servicenow"],
      "env": {
        "SERVICENOW_INSTANCE": "mycompany",
        "SERVICENOW_USER": "${SN_USER}",
        "SERVICENOW_PASSWORD": "${SN_PASSWORD}"
      }
    }
  }
}

3. Consume MCP from OpenAI Agents SDK

from agents import Agent, Runner
from agents.mcp import MCPServerStdio

# Connect to enterprise MCP server
crm_server = MCPServerStdio(
    command="python",
    args=["-m", "crm_mcp_server"],
    env={"CRM_BASE_URL": "https://crm.example.com", "CRM_API_KEY": "..."},
)

agent = Agent(
    name="Customer Service Agent",
    instructions="Help customers by looking up their info and creating tickets when needed.",
    mcp_servers=[crm_server],
)

async def main():
    async with crm_server:
        result = await Runner.run(agent, "Find customer John Smith and check his open tickets")
        print(result.final_output)

4. Consume MCP from Google ADK

from google.adk.agents import Agent
from google.adk.tools.mcp_tool import MCPToolset, StdioServerParameters

crm_mcp = MCPToolset(
    connection_params=StdioServerParameters(
        command="python",
        args=["-m", "crm_mcp_server"],
        env={"CRM_BASE_URL": "https://crm.example.com"},
    )
)

agent = Agent(
    model="gemini-2.0-flash",
    name="customer_service",
    instruction="Help customers using CRM tools.",
    tools=[crm_mcp],
)

5. Multi-Tenant MCP Server Pattern

from mcp.server.fastmcp import FastMCP
from contextvars import ContextVar

mcp = FastMCP("Multi-Tenant Enterprise Server")

# Tenant context (set per-session)
current_tenant = ContextVar("current_tenant", default=None)

@mcp.tool()
async def query_data(table: str, filters: dict | None = None) -> list[dict]:
    """Query data scoped to the current tenant.

    Args:
        table: Table name (customers, orders, tickets)
        filters: Optional key-value filters
    """
    tenant_id = current_tenant.get()
    if not tenant_id:
        return {"error": "No tenant context. Authenticate first."}

    # All queries automatically scoped to tenant
    query = f"SELECT * FROM {table} WHERE tenant_id = :tenant_id"
    # ... execute with tenant isolation

6. Enterprise MCP Server Checklist

## Production Readiness Checklist

### Security
- [ ] Authentication required (API key, OAuth, mTLS)
- [ ] Multi-tenant data isolation (tenant_id in all queries)
- [ ] PII handling documented (what data flows through)
- [ ] Secrets via environment variables (never hardcoded)
- [ ] Rate limiting implemented

### Observability
- [ ] Structured logging (JSON, with correlation IDs)
- [ ] Metrics exposed (tool call count, latency, errors)
- [ ] Audit trail for all write operations
- [ ] Error messages are actionable (guide agent to fix)

### Reliability
- [ ] Timeout handling for upstream API calls
- [ ] Retry logic with exponential backoff
- [ ] Circuit breaker for upstream failures
- [ ] Graceful degradation (read-only mode if writes fail)

### Documentation
- [ ] Tool descriptions are clear and specific
- [ ] Parameter descriptions include constraints and examples
- [ ] Resource URIs follow consistent naming scheme
- [ ] README with setup and authentication instructions

Anti-Patterns

• Building one mega MCP server for all enterprise systems -- split by domain (CRM, ITSM, ERP)
• Exposing raw database queries as tools -- always add business logic and validation
• Skipping authentication -- enterprise MCP servers MUST authenticate
• Returning raw API responses -- transform to agent-friendly format (relevant fields only)
• Missing error handling -- agents need structured error messages to recover

Key MCP Server Registries

References

• MCP Specification
• MCP Python SDK
• MCP TypeScript SDK
• Official MCP Servers
• AWS MCP Servers
• OpenAI Agents SDK MCP
• Google ADK MCP