ghl-mcp-remote

Servidor MCP (Model Context Protocol) remoto para GoHighLevel — multi-tenant, accesible vía URL, para ser usado desde Claude o ChatGPT por cualquier agencia, sin que cada una necesite ejecutar nada localmente.

Este es un proyecto separado del ghl-mcp original (stdio, uso personal/local). Ninguno de los dos depende del otro.

Diferencia con el ghl-mcp original

El código de negocio (las tools en src/tools/) es prácticamente idéntico en los dos — solo cambia la capa de autenticación/almacenamiento.

Related MCP server: GoHighLevel MCP Server

Arquitectura

Claude/ChatGPT ──(1) descobre──> GET /.well-known/oauth-authorization-server
               ──(2) registra───> POST /register                      (DCR, automático)
               ──(3) pede login─> GET /authorize ──redirect──> tela da GHL (o "login")
                                                        <──redirect── GET /oauth/ghl/callback
               <──code+state───── (nosso próprio código de autorização)
               ──(4) troca──────> POST /token ──> access_token + refresh_token nossos
               ──(5) chama tool─> POST /mcp  (Authorization: Bearer <access_token>)

• «Login» = autorizar la GHL. No existe cuenta/contraseña propia de este servicio. Cuando el admin de una agencia aprueba el acceso en la pantalla de la propia GHL, eso ya crea/actualiza su tenant (identificado por el companyId de la GHL) y completa el login del lado del MCP.

• Una única app de GHL Marketplace (mismo GHL_CLIENT_ID/GHL_CLIENT_SECRET) atiende a cualquier agencia que la instale — no hace falta crear una app por cliente.

• Cada llamada de tool llega autenticada con un Bearer token emitido por este servidor; el middleware resuelve ese token al companyId correcto e inyecta eso en un AsyncLocalStorage (src/tenant-context.ts) — así es como el código de las tools (idéntico al del proyecto original) permanece «sin saber» de multi-tenancy.

• Implementado sobre lo que el propio @modelcontextprotocol/sdk ya trae para servidores OAuth (server/auth/router.ts, provider.ts) — ver src/auth/mcp-oauth-provider.ts.

Requisitos previos para ejecutar en cualquier lugar

1. App OAuth en GHL Marketplace (Developer > tu app), distribución «Agency» o «Agency & Sub-Account»:

   • Redirect URI registrada: <PUBLIC_URL>/oauth/ghl/callback (debe ser la URL pública final de este servicio — HTTPS).

   • Scopes: los mismos listados en src/services/scopes.ts.

2. Postgres (cualquiera — Supabase, Neon, RDS, el Postgres gestionado por la propia plataforma de hosting, etc.). Ejecutar db/schema.sql en él una vez.

3. Node.js 20+ (o la imagen Docker de este proyecto, que ya lo incluye).

Variables de entorno

Ver .env.example. Resumen:

Ejecutar localmente (dev)

npm install
npm run build
npm start

Verificaciones posibles sin ningún dominio público:

curl localhost:8080/healthz
curl localhost:8080/.well-known/oauth-authorization-server

El flujo completo de OAuth (autorizar de verdad en la GHL, obtener token, llamar a una tool) solo funciona con una PUBLIC_URL real (HTTPS) en el aire, porque la GHL necesita poder redirigir el navegador del admin de la agencia de vuelta hacia aquí — y esa misma URL debe estar registrada como redirect URI en la app de GHL.

Despliegue

Este proyecto no asume ninguna plataforma de hosting específica — solo incluye un Dockerfile genérico. Cualquier plataforma que ejecute una imagen Docker (o node dist/index.js directamente) sirve, siempre que:

1. Exponga una URL pública HTTPS estable → eso se convierte en PUBLIC_URL.

2. Inyecte las variables de entorno de la tabla anterior.

3. El Postgres apuntado por DATABASE_URL ya haya ejecutado db/schema.sql.

4. El redirect URI de la app de GHL Marketplace se actualice a <PUBLIC_URL>/oauth/ghl/callback en cuanto se conozca la URL final.

Conectar en Claude / ChatGPT

Una vez alojado:

• Claude.ai / Claude Desktop: Configuración → Connectors → Add custom connector → URL: https://<seu-dominio>/mcp. Claude te llevará al flujo de autorización automáticamente.

• ChatGPT: en workspaces con soporte para Connectors/MCP remoto (varía según el plan — Team, Enterprise, o «Developer mode»), añadir un connector apuntando a https://<seu-dominio>/mcp.

Advertencia sobre ChatGPT: el soporte para conectores MCP remotos con OAuth en ChatGPT varía según el plan/workspace, y algunas superficies (p. ej. Deep Research) restringen qué formatos de tool aceptan (a veces solo tools en formato «search»/«fetch»). Este servidor sigue la spec de autorización del MCP al pie de la letra (la misma que usa Claude), lo que maximiza la compatibilidad — pero vale la pena probarlo de verdad una vez esté alojado, ya que el comportamiento del lado de ChatGPT escapa a nuestro control.

Estructura

src/
  index.ts                 App Express: monta o router de OAuth, POST/GET/DELETE /mcp,
                            GET /oauth/ghl/callback, GET /healthz, CORS.
  server.ts                 createMcpServer() — registra as tools (idêntico ao projeto original).
  tenant-context.ts          AsyncLocalStorage que carrega o companyId durante cada request.
  db/
    pool.ts                  Pool do `pg` a partir de DATABASE_URL.
    crypto.ts                 AES-256-GCM (tokens da GHL em repouso) + SHA-256 (hash dos nossos tokens).
    agencies.ts                Tokens de agência da GHL por companyId (substitui o antigo token-store.ts).
    oauth-store.ts              Clients MCP, pending auth, authorization codes, access/refresh tokens.
  auth/
    ghl-oauth.ts               Troca/refresh de tokens com a GHL — equivalente ao oauth-flow.ts original,
                               mas web-based e por tenant em vez de CLI + arquivo único.
    location-tokens.ts          Cache de location tokens, agora chaveado por companyId.
    mcp-oauth-provider.ts        Implementa OAuthServerProvider do SDK — o núcleo do "login = autorizar a GHL".
    ghl-callback.ts               Handler de GET /oauth/ghl/callback.
  services/
    constants.ts, scopes.ts, ghl-client.ts   Idênticos ao projeto original (só o import de token mudou).
  tools/
    *.ts                       Idênticos ao projeto original, exceto locations.ts (cache agora por tenant).
db/
  schema.sql                  DDL do Postgres — rodar uma vez antes do primeiro start.

Seguridad

• Refresh tokens de la GHL: cifrados en reposo (AES-256-GCM).

• Access/refresh tokens que este servidor emite para Claude/ChatGPT: guardados solo como hash SHA-256 — nunca en texto plano, igual que una contraseña.

• PKCE (S256) obligatorio en todo el flujo MCP-side, validado localmente (no delegado a la GHL).

• Ninguna credencial de una agencia es accesible desde el token de otra — todo acceso a Postgres está filtrado por companyId, y ese valor solo entra en escena después de que el Bearer token es validado.