Servidor MCP Exir

Una puerta de enlace multiinquilino del Model Context Protocol que se sitúa entre los hosts MCP (Claude, ChatGPT o cualquier otro agente compatible con MCP) y la API de Exir CRM (Perfex CRM bajo el capó).

                    ┌──────────────────────┐
                    │   ChatGPT / Agent     │
                    │ Claude / Other Host   │
                    └──────────┬────────────┘
                               │
                         MCP / HTTPS
                               │
                               ▼
              ┌────────────────────────────────┐
              │        Exir MCP Server          │
              │                                 │
              │ OAuth 2.1 / OIDC                │
              │ Tenant Resolver                 │
              │ Permission Engine               │
              │ Tool Registry                   │
              │ Audit Logger                    │
              │ Rate Limiter                    │
              │ Input Validation                │
              └───────────────┬─────────────────┘
                               │
                        Internal API
                               │
                               ▼
              ┌────────────────────────────────┐
              │          Exir CRM API           │
              │                                 │
              │ Customers / Leads / Sales       │
              │ Tasks / Projects / Tickets      │
              │ Invoices / Contracts / ...      │
              └───────────────┬─────────────────┘
                               │
                               ▼
                    ┌──────────────────┐
                    │ Customer Tenant   │
                    │ Data / Database   │
                    └──────────────────┘

Cómo fluye una solicitud

1. Transporte — un host MCP envía una solicitud POST /mcp (Streamable HTTP) con un token de acceso Bearer.

2. OAuth 2.1 / OIDC (src/auth/oidc.ts) — la firma, el emisor, la audiencia y la caducidad del token se verifican contra el JWKS del proveedor de identidad. Los tokens no verificados nunca llegan a nada por debajo de esta capa.

3. Resolvedor de inquilinos (src/tenant/tenantResolver.ts) — el id del inquilino se lee de una reclamación del token verificado y se asigna a la conexión de Exir CRM de ese inquilino (URL base + clave de API). Las solicitudes nunca pueden cruzar los límites de los inquilinos.

4. Limitador de velocidad (src/middleware/rateLimiter.ts) — las solicitudes se limitan por inquilino para que un llamador ruidoso no pueda privar a otro en una implementación compartida.

5. Registro de herramientas (src/tools/) — el servidor MCP para esta solicitud se construye envolviendo cada herramienta registrada (src/mcp/server.ts) con:

   • Motor de permisos (src/permissions/permissionEngine.ts) — comprueba los alcances OAuth del token contra el alcance requerido por la herramienta.

   • Validación de entrada — cada herramienta declara un esquema zod; la entrada no válida se rechaza antes de que llegue al CRM.

   • Registro de auditoría (src/audit/auditLogger.ts) — cada llamada (permitida, denegada, exitosa o con error) se registra con inquilino, sujeto, nombre de la herramienta y resultado.

6. API interna (src/crm/perfexClient.ts) — un cliente HTTP con ámbito de inquilino llama a la API real de Exir CRM (API REST de Perfex CRM, autenticación con cabecera authtoken) y devuelve el resultado hacia arriba en la cadena como salida de la herramienta.

Related MCP server: Nervora

Estructura del proyecto

src/
  auth/oidc.ts            OAuth 2.1 / OIDC bearer-token verification
  tenant/tenantResolver.ts Tenant lookup + per-tenant CRM connection details
  permissions/permissionEngine.ts  Scope-based authorization
  audit/auditLogger.ts     Structured audit trail for every tool call
  middleware/rateLimiter.ts Per-tenant rate limiting
  crm/perfexClient.ts      Internal API client to the Exir CRM API
  tools/                   Tool Registry + one file per CRM domain
    customers.ts leads.ts tasks.ts invoices.ts
  mcp/server.ts            Wires tools -> permissions -> validation -> audit -> CRM
  http/app.ts              Express app: /healthz, POST /mcp
  index.ts                 Process entrypoint
tests/                     Vitest unit tests (permission engine, tool registry)

Primeros pasos

npm install
cp .env.example .env   # fill in OIDC_ISSUER, CRM_API_BASE_URL, CRM_API_KEY, ...
npm run dev             # ts-node/tsx dev server on :3333

Compilar y ejecutar para producción:

npm run build
npm start

O mediante Docker:

docker compose up --build

Ejecutar pruebas:

npm test

Añadir una nueva herramienta

1. Añade una llamada registry.register({...}) en el archivo correspondiente bajo src/tools/ (o un archivo nuevo para un nuevo dominio del CRM), con un name, description, requiredScope, un inputSchema de zod y un handler(crm, input) que llame al PerfexClient.

2. Si es un archivo nuevo, conéctalo en buildToolRegistry() en src/tools/index.ts.

3. Añade una prueba en tests/tools.test.ts que verifique que la herramienta está registrada y que su esquema rechaza entradas incorrectas.

No se necesitan cambios en ningún otro lugar: los permisos, la validación y la auditoría se aplican genéricamente a cada herramienta registrada mediante src/mcp/server.ts.

Multiinquilinato

src/tenant/tenantResolver.ts incluye un EnvTenantStore de respaldo para desarrollo que resuelve cada id de inquilino a la única conexión CRM en .env. Para implementaciones reales de multiinquilinato, implementa la interfaz TenantStore contra tu directorio de inquilinos (Postgres, un servicio de configuración, etc.) que asigne id de inquilino -> { baseUrl, apiKey }, y pásalo a tenantResolver(myStore) en src/http/app.ts.

Notas de seguridad

• El id del inquilino solo se confía en una reclamación de un token de acceso verificado criptográficamente, nunca en una cabecera proporcionada por el cliente, a menos que TENANT_HEADER_FALLBACK=true se establezca explícitamente para llamadores de confianza en la red interna (por ejemplo, desarrollo local).

• Las claves de API del CRM por inquilino nunca se registran (src/logger.ts redacta Authorization, *.apiKey, *.token).

• Cada llamada a una herramienta se valida dos veces: una por el SDK de MCP contra el esquema JSON de la herramienta, y otra por zod.safeParse dentro del manejador, antes de realizar cualquier llamada a la API del CRM.

• El servidor se ejecuta sin estado (sessionIdGenerator: undefined): se crea una nueva instancia del servidor MCP por solicitud HTTP, con ámbito al inquilino y permisos verificados de esa solicitud, por lo que no hay estado de sesión compartido que pueda filtrarse entre inquilinos.