Servidor MCP de CDP

Un servidor MCP (Protocolo de Contexto de Modelo) que pone la Plataforma de Datos de Clientes de Acquia al alcance de tu LLM. Apunta Claude, Copilot o cualquier cliente compatible con MCP a este servidor y podrá leer tus inquilinos, gestionar campañas, revisar flujos de trabajo, consultar informes y, en general, realizar el trabajo administrativo aburrido para que tú no tengas que hacerlo.

Creado porque hacer clic en las pantallas de CDP a las 2 a. m. no es la idea de diversión de nadie.

Qué obtienes

• ~300 herramientas que abarcan permisos, almacén de datos, campañas, configuración, conectores, informes, predicciones, correo, páginas enviables por correo electrónico, seguridad, caché y API de estado; consulta SUPPORTED_TOOLS.md para ver el catálogo completo.

• 8 recursos de manuales (playbooks) que enseñan al LLM cómo secuenciar flujos reales de varios pasos (asistente de campañas, renderizado de perfiles C360, creación de flujos de trabajo, incorporación de conectores, ediciones de esquemas UDMP, etc.); estos provienen de la ingeniería inversa de las interfaces de usuario de Vega y Config para que el modelo deje de adivinar.

• Dos modos de autenticación: concesión de contraseña OAuth2 (actualización automática, reintento 401, serialización de bloqueo) o un token de portador estático si ya tienes uno.

• Cambio entre Dev / QA / Prod mediante una única variable CDP_ENVIRONMENT.

• Transporte Stdio, por lo que se integra directamente en Claude Desktop, VS Code Copilot, Continue, mcphost, Open WebUI (a través de supergateway) o MCP Inspector.

Si lo anterior suena a sopa de letras, echa un vistazo a TUTORIAL.md; recorre cada pieza con comandos que puedes copiar y pegar. Para obtener la lista completa de nombres de herramientas y lo que hace cada una, consulta SUPPORTED_TOOLS.md.

Inicio rápido

# 1. Clone and install
git clone https://github.com/atharva-joshi77/cdp-mcp.git
cd cdp-mcp
python3 -m venv .venv && source .venv/bin/activate
pip install -e .

# 2. Configure
cp .env.example .env
# edit .env: CDP_ENVIRONMENT, CDP_TENANT_ID, and either
#   CDP_CLIENT_ID/SECRET + CDP_USERNAME/PASSWORD  (OAuth2)
# or CDP_AUTH_TOKEN                                (static token)

# 3. Run
cdp-mcp

cdp-mcp habla JSON-RPC en stdio, por lo que ejecutarlo sin más parecerá que se queda colgado; eso es correcto. Conéctalo a un cliente MCP (ver más abajo) y cobrará vida.

Conéctalo a Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "cdp": {
      "command": "/absolute/path/to/cdp-mcp/.venv/bin/cdp-mcp",
      "env": {
        "CDP_ENVIRONMENT": "dev",
        "CDP_TENANT_ID": "12345",
        "CDP_CLIENT_ID": "...",
        "CDP_CLIENT_SECRET": "...",
        "CDP_USERNAME": "...",
        "CDP_PASSWORD": "..."
      }
    }
  }
}

Reinicia Claude y deberías ver aparecer ~300 herramientas cdp_* en el selector de herramientas. Para configuraciones de VS Code, Continue, Ollama/Open WebUI y MCP Inspector, las recetas completas están en TUTORIAL.md §5.

Requisitos

Dependencias (instaladas automáticamente):

• mcp>=1.13.0 — framework FastMCP

• httpx>=0.27.0 — HTTP asíncrono

• pydantic + pydantic-settings — configuración + validación

• python-dotenv — carga de .env

Diseño del proyecto

src/cdp_mcp/
├── __main__.py           # entry point: `cdp-mcp` / `python -m cdp_mcp`
├── server.py             # FastMCP server, registers tools + resources
├── config.py             # env/.env loader
├── auth/                 # OAuth2 + static-token provider
├── utils/                # shared httpx client, error helpers
├── resources/            # MCP resource URIs (tenant/*, docs/*)
├── docs/                 # the eight playbooks, shipped as resources
├── types/                # pydantic request/response models
└── tools/                # one subpackage per CDP service area
    ├── permissions/      users, roles, clients
    ├── dw/               data warehouse, A360, audiences, offers, trackers
    ├── campaign/         defs, audiences, messages, dispatches, runs, exports
    ├── config_api/       tenants, workflows, schedules, UDMP, DQE, clusters…
    ├── connectors/       input + output connectors, templates
    ├── reports/          dashboards, widgets, cubes, QL
    ├── predictions/      prediction defs + content templates
    ├── mailer/           accounts, subusers, identifiers, batches
    ├── emailable_pages/  emailable-pages CRUD
    ├── security/         token, auth, SSO, password reset
    ├── cache/            cache ops
    ├── spam/             spam score
    ├── status/           status + orchestration/purge status
    ├── provisions/       self-service provisioning
    ├── global_actions/   platform-wide actions
    └── alerts/           stub (real Alerts API lives in a different stack)

Cada herramienta comparte un único HttpClient con conexiones httpx agrupadas, una caché de tokens de autenticación compartida, un asyncio.Lock para las actualizaciones, reintento de un solo intento ante 401, IDs de inquilino codificados en URL y seguimiento de solicitudes/respuestas con logger.info. Si algo parece extraño, los registros suelen decir la verdad.

Manuales (el ingrediente secreto)

Las listas de herramientas por sí solas no son suficientes; muchos flujos de CDP son "POST a una definición, luego POST ?action=publish, luego GET estado, luego quizás POST ?action=schedule con un ID de programación separado". El LLM suele equivocarse si se le deja a su suerte.

Por lo tanto, el servidor incluye ocho manuales en Markdown como recursos MCP:

Los clientes MCP los descubren automáticamente al conectarse, y el bloque de instrucciones del servidor dirige al modelo a cada uno.

Notas de autenticación

• OAuth2 (preferido): el proveedor realiza un POST {baseUrl}/token?action=create con credenciales en los encabezados, almacena el token en memoria, serializa las actualizaciones concurrentes detrás de un asyncio.Lock y actualiza ~60s antes de que expire. Cualquier 401 de una llamada descendente activa una actualización forzada de un solo intento + reintento.

• Token estático: establece CDP_AUTH_TOKEN y la ruta OAuth2 se omite por completo. Tú eres responsable de la rotación.

Nunca pongas secretos reales en este repositorio. .env está ignorado por git.

Desarrollo

# smoke test: should print the server's capabilities + tool list
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"t","version":"1"}}}' | cdp-mcp

# interactive tool browser
npx @modelcontextprotocol/inspector cdp-mcp

# verify tool count
python3 -c "from cdp_mcp.server import create_server; import asyncio; \
  print(len(asyncio.run(create_server().list_tools())))"

Hay una matriz de solución de problemas más completa (el servidor no arranca, 401s, el cliente no puede conectarse, etc.) en TUTORIAL.md §9.

Estado

• Recuento de herramientas: 301 en 12 servicios de CDP

• Recursos de manuales: 8

• Las herramientas de alertas están intencionalmente como stubs; la API de Alertas real vive en una pila separada de MuleSoft/Go que necesita su propia URL base y autenticación (se aceptan PRs)

• El arnés de pruebas de integración está en progreso (andamios presentes, cobertura de contrato completa rastreada como seguimiento)

Contribución

1. Haz fork, crea una rama, programa.

2. Ejecuta ./gradlew-equivalent — está bien, solo pip install -e . y la prueba de humo anterior.

3. Si añades una herramienta, regístrala en el registrador tools/<area>/__init__.py correspondiente.

4. Si añades un flujo de varios pasos, escribe un manual para él en src/cdp_mcp/docs/ y registra el recurso en resources/resource_providers.py.

5. Abre un PR. Sé amable en la descripción.

Licencia

Interna / propietaria — consulta con Acquia antes de usar esto fuera de tu propio inquilino.

Construido con partes iguales de httpx, pydantic y despecho por los asistentes de CDP inestables.