Diseñar herramientas MCP para un CRM: 4 lecciones - Relaticle         

Diseñar herramientas MCP para un CRM: cuatro lecciones
======================================================

Lo que nos enseñó construir el MCP server de Relaticle sobre esquemas, validación compartida de campos personalizados, autorización y descubrimiento por parte de los clientes.

 Manuk Minasyan · 11 de septiembre de 2026 · 13 min de lectura

 ![Diseñar herramientas MCP para un CRM: cuatro lecciones](https://relaticle.com/storage/ink/01M7T44F7DRPQY5A1ESYYX2WJE.png) 

Construimos el MCP server de Relaticle a partir de las acciones de escritura que el CRM ya tenía. Cuatro lecciones lo moldearon: esquemas explícitos, validación compartida, autorización clara y descubrimiento fiable por parte de los clientes. Los campos personalizados se describen de forma distinta en el chat y en MCP, pero ambos normalizan los datos de entrada con el mismo servicio. El servidor cubre todos los tipos de registro del CRM, el contexto del espacio de trabajo y las cargas de archivos. Las conexiones con acceso al correo reciben además herramientas de correo.

Nada de esto resultaba evidente al leer la especificación de MCP. Esto es lo que encontramos al construir sobre ella.

![Familias históricas de herramientas MCP antes de agregar la carga de archivos](https://relaticle.com/storage/ink/01M12RRDBW8CWGZR6CNZFZ8VWN.png)

*Diagrama histórico de agosto de 2026. El servidor actual incluye además `upload-file` y `create-upload-url`.*

[](#las-familias-de-herramientas-y-por-qué-no-son-simétricas "Permalink")Las familias de herramientas y por qué no son simétricas
---------------------------------------------------------------------------------------------------------------------------------

| Familia de herramientas | Cantidad | Decisión de diseño |
|---|---|---|
| CRUD de empresas / personas / oportunidades | 15 (5 × 3) | Solo List, Get, Create, Update y Delete. Las relaciones son claves foráneas simples (`company_id`, `contact_id`) que se validan directamente al crear y actualizar, así que no hace falta una herramienta de asociación aparte |
| CRUD de tareas / notas + relaciones | 14 (7 × 2) | Las mismas cinco, más Attach/Detach. Las tareas y las notas tienen relaciones polimórficas de muchos a muchos con empresas, personas y oportunidades (las tareas además tienen asignados), así que un único campo de clave foránea no puede expresar la relación |
| Utilidades del espacio de trabajo y entre entidades | 10 | `search`, `fetch`, contexto de la cuenta, cinco lecturas del espacio de trabajo y las herramientas `upload-file` y `create-upload-url` |

Las familias de herramientas tienen responsabilidades distintas. Las relaciones de empresas, personas y oportunidades se expresan con campos al crear y actualizar. Por ejemplo, una oportunidad puede hacer referencia a una empresa. Las relaciones de tareas y notas son asociativas: una tarea puede afectar a tres empresas y a dos personas a la vez, por eso tienen sus propios endpoints de sincronización. No agregamos Attach/Detach a las otras tres por simple coherencia. No tienen nada a lo que asociarse.

[](#search-y-fetch-son-un-contrato-no-una-comodidad "Permalink")Search y fetch son un contrato, no una comodidad
----------------------------------------------------------------------------------------------------------------

`search` y `fetch` no son herramientas genéricas a las que casualmente pusimos esos nombres. Son exactamente el par que exige el conector Company Knowledge de ChatGPT: un cliente que encuentra registros mediante una consulta y los cita con una URL estable. Ambas llevan los atributos `#[Name('search')]` y `#[Name('fetch')]`, de modo que el nombre en el protocolo coincide sin importar cómo se llame la clase. Además, ambas están fijadas como de solo lectura, idempotentes y de mundo cerrado en sus anotaciones de herramienta MCP.

En el primer intento hicimos mal el contrato. `search` publicaba URL como `/app/{segment}/{id}` y omitía el slug del espacio de trabajo que exige el enrutamiento de Filament, así que todas las URL de cita daban un 404, incluso para el propietario del registro. `fetch` solo sabía interpretar esa misma forma errónea, de modo que también rechazaba la URL real que un usuario copiaría de la barra de direcciones de su navegador. Las tareas y las notas no tenían ninguna página propia por registro. Por eso, dos de los cinco tipos de entidad que se podían buscar no tenían una URL que citar desde el principio.

La solución fue `CanonicalRecordUrl`, una sola clase que construye e interpreta el formato de la URL y que usan ambas herramientas. Separar la lógica de construcción y la de interpretación en dos archivos hace que ambas pierdan coherencia. Un resultado de búsqueda que un cliente no puede pegar de vuelta en fetch es peor que no tener ninguna cita.

[](#las-descripciones-de-esquema-son-prompts-no-documentación "Permalink")Las descripciones de esquema son prompts, no documentación
------------------------------------------------------------------------------------------------------------------------------------

Los esquemas de las herramientas de creación y actualización usan esta instrucción para `custom_fields`:

> "Valores de campos personalizados como pares clave-valor. IMPORTANTE: PRIMERO debe leer el recurso crm-schema para conocer los códigos de campo válidos para este tipo de entidad. Los códigos de campo desconocidos se rechazarán. Use los códigos de campo exactos del esquema (por ejemplo, 'job\_title', no 'jobTitle')."

Eso no es documentación de API. Es una instrucción dirigida a un agente en plena tarea para evitar dos errores que los modelos realmente cometen. El primero consiste en adivinar un código de campo aparentemente válido en lugar de consultarlo. El segundo consiste en escribir en camelCase una clave en snake\_case porque camelCase es la convención más habitual en los datos de entrenamiento. Las descripciones de las herramientas hacen lo mismo a un nivel más general: "Cree una empresa nueva en el CRM. Use el recurso crm-schema para conocer los campos personalizados disponibles". Remiten al modelo al recurso de esquema de cada entidad (`relaticle://schema/company`, un URI por entidad) antes de que llame siquiera a la herramienta.

Esto solo funciona porque el recurso de esquema es barato de leer y se guarda en caché por espacio de trabajo durante 60 segundos. Si el descubrimiento fuera otra consulta a la base de datos en cada búsqueda de campo, nos tentaría incluir el esquema completo en cada descripción de herramienta. Entonces el costo en tokens se pagaría en cada llamada y no una sola vez por lectura del recurso.

[](#descripciones-distintas-normalización-compartida-de-campos-personalizados "Permalink")Descripciones distintas, normalización compartida de campos personalizados
--------------------------------------------------------------------------------------------------------------------------------------------------------------------

Los campos personalizados pertenecen a cada espacio de trabajo. El `CustomFieldsSchemaDescriber` del chat presenta los códigos de campo y las etiquetas de las opciones dentro del esquema de la herramienta. El `CustomFieldSchema` de MCP devuelve definiciones estructuradas con etiquetas e ID de opción.

Ambas superficies de escritura llaman a `CustomFieldInput::normalize()` antes de que `ValidCustomFields` valide el resultado. Los campos de selección aceptan etiquetas de opción o ID. Las etiquetas ambiguas no pasan la validación, por lo que un ID de opción resuelve los casos de etiquetas duplicadas.

El enum `CustomFieldType` define los formatos de entrada y los ejemplos que usan ambas descripciones de esquema. Los valores del editor enriquecido aceptan Markdown o HTML y se guardan como HTML.

Este límite mantiene la presentación específica de cada cliente y centraliza la normalización. Un campo nuevo no necesita un espacio de esquema escrito a mano en cada herramienta.

[](#el-procesamiento-por-lotes-pertenece-a-la-superficie-de-aprobación-no-al-protocolo "Permalink")El procesamiento por lotes pertenece a la superficie de aprobación, no al protocolo
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

Nuestras herramientas de eliminación se ven distintas según el cliente que las llame, y eso es una decisión de diseño deliberada, no una desviación. La herramienta de eliminación del chat recibe `ids: string[]`, uno o varios. Su docstring lo explica: "Pase un ID para eliminar una sola empresa, o varios para eliminarlas todas en una sola llamada." Una solicitud con varios ID se convierte en una única `PendingAction` que una persona revisa como parte de un plan. Se pueden tomar decisiones por lotes para cada elemento. Así el modelo no lanza tres llamadas de eliminación separadas que exigen cada una su propia aprobación.

Las herramientas de eliminación de MCP reciben un único `id` escalar. No hay un paso de aprobación para el que agrupar llamadas: una escritura por MCP se ejecuta de inmediato en cuanto el token OAuth supera la comprobación de permisos, así que no existe nada equivalente a "reducir el número de tarjetas que una persona tiene que revisar". Para un agente que hace una limpieza masiva, eso es una carencia real (eliminar doce oportunidades obsoletas son hoy doce llamadas). No creemos que sea evidente que esta sea la mejor solución intermedia. Es la que adoptamos al no revisar el patrón cuando ya existía en el chat.

[](#los-permisos-del-token-y-la-autorización-del-usuario-son-comprobaciones-distintas "Permalink")Los permisos del token y la autorización del usuario son comprobaciones distintas
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

Una escritura por MCP tiene que responder dos preguntas distintas antes de tocar la base de datos: si este token permite la operación y si este usuario puede modificar el registro. Ambas se aplican en lugares distintos, a propósito.

`ChecksTokenAbility` se encarga de la primera y tiene que tratar OAuth como caso especial. Un token de acceso personal de Sanctum puede llevar permisos granulares (`read`, `create`, `update`, `delete`), pero un token OAuth de Passport, el que realmente tienen Claude o ChatGPT, solo puede solicitar `mcp:use`, porque es el único scope que [laravel/mcp](https://github.com/laravel/mcp) publica en los metadatos de su servidor de autorización. OAuth no permite conceder permisos para cada operación. Por eso, tener `mcp:use` autoriza el conjunto completo de herramientas. El propio token determina por separado a qué espacio de trabajo pertenecen los datos que esas herramientas pueden consultar.

Ese enlace lo hace `SetApiWorkspaceContext`. Los tokens OAuth contienen el `workspace_id` que determina el espacio de trabajo. El middleware ignora `X-Workspace-Id` para esos tokens. Establece el contexto del tenant y el guard web, y luego aplica `WorkspaceScope` a los modelos con scope. Su método `terminate()` elimina esos scopes. El middleware admite expresamente FPM y no Octane, porque su estado estático de modelos puede sobrevivir a una limpieza fallida en Octane.

Ninguna de esas dos comprobaciones verifica que una clave foránea del cuerpo de la solicitud pertenezca de verdad al espacio de trabajo de quien llama. De eso se ocupa `TenantFkValidator::assertOwned()`, que se invoca dentro de la propia acción. `CreateOpportunity` comprueba, antes de insertar, que `company_id` y `contact_id` existen y pertenecen al espacio de trabajo de quien llama, con independencia de lo que el middleware ya haya acotado. Un token con `mcp:use` y un enlace de espacio de trabajo válido sigue sin poder apuntar una oportunidad nueva a un ID de empresa que haya adivinado a partir de los datos de otro tenant, porque a esta profundidad de la ruta de escritura nada confía solo en el scoping.

[](#las-anotaciones-de-herramienta-son-una-superficie-de-políticas-y-una-lista-mantenida-a-mano-se-desajusta "Permalink")Las anotaciones de herramienta son una superficie de políticas, y una lista mantenida a mano se desajusta
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

Las [anotaciones de herramienta](https://modelcontextprotocol.io/specification/2025-06-18/server/tools#tool-annotations) de MCP (`readOnlyHint`, `idempotentHint`, `destructiveHint`, `openWorldHint`) no son decoración. Las comprobaciones del envío al directorio de Claude y de ChatGPT las leen, y un cliente puede usar con razón `destructiveHint` para decidir si pregunta al usuario antes de llamar a una herramienta. Anotamos todas las herramientas: las de lectura se marcan como de solo lectura e idempotentes. Las actualizaciones, las eliminaciones y las desvinculaciones llevan indicaciones destructivas cuando corresponde. Las escrituras de tareas que envían notificaciones y las cargas de archivos declaran comportamiento de mundo abierto.

Aun así, publicamos una versión con una omisión. La primera versión de nuestra prueba de anotaciones comprobaba expectativas concretas sobre una lista de clases de herramienta elegidas a mano, y `WhoAmiTool` nunca se agregó a esa lista. Así, 31 de las 32 herramientas que teníamos entonces declaraban `openWorldHint`, la prueba seguía en verde y la herramienta número 32 no lo declaraba sin que nadie lo notara. La solución no fue una lista más grande. Consistió en leer por reflexión `RelaticleServer::$tools` y comprobar la propiedad en cada clase registrada realmente ahí, de modo que una herramienta nueva no pueda saltarse la comprobación porque nadie se acordó de agregarla a un conjunto de datos:

```
$tools = (new ReflectionClass(RelaticleServer::class))->getDefaultProperties()['tools'];
foreach ($tools as $toolClass) {
    expect(app($toolClass)->annotations())->toHaveKey('openWorldHint');
}

```

La misma lección, que el límite es más amplio de lo que uno piensa, apareció también en la capa de transporte. Con `MCP_DOMAIN` definido, el MCP server se monta en la raíz de un subdominio que es además su identificador de recurso protegido de OAuth. Los clientes RFC 9728 descubren ese identificador haciendo un `GET` a la URL sin ruta y tratando cualquier respuesta 200 como el documento de metadatos del recurso protegido. Nuestra ruta raíz servía ahí un banner informativo en HTML, de modo que un cliente basado en rmcp (Codex, en nuestro caso) leyó el banner como metadatos, no encontró ningún campo `resource` y falló con un mensaje bastante opaco: "Protected resource metadata missing required resource field." Claude y ChatGPT nunca se toparon con esto, porque su SDK solo consulta rutas bajo `/.well-known`, y por eso nadie lo notó. La solución invierte el comportamiento por defecto: un GET sin ruta recibe ahora la respuesta correcta del protocolo. El banner solo se muestra cuando el navegador hace una navegación real de nivel superior. Esta se detecta mediante `Sec-Fetch-Mode: navigate`, una señal de navegación del navegador. Los clientes que no son navegadores también pueden enviar ese encabezado, así que no es un control de autenticación.

[](#qué-haríamos-de-otra-manera "Permalink")Qué haríamos de otra manera
-----------------------------------------------------------------------

Al principio mantuvimos rutas de traducción de campos personalizados separadas. La implementación actual comparte la normalización mediante `CustomFieldInput` y las descripciones de formato mediante `CustomFieldType`. Eso reduce los desajustes y deja que el chat destaque las etiquetas mientras MCP expone definiciones estructuradas. La paridad de esquemas sigue necesitando pruebas cada vez que cambian los formatos de valor admitidos.

También revisaríamos ahora el procesamiento por lotes de las eliminaciones en MCP, en lugar de dejarlo como una asimetría que solo notamos al escribir este artículo. Fue acertado lanzar primero las eliminaciones de un solo registro y resolver bien la aprobación por lotes en el lado del chat, donde el costo de experiencia de usuario de no agrupar era inmediato y visible. Pero un agente que limpia un CRM de forma masiva es un caso de uso real de MCP, y hoy lo paga en número de llamadas sin ningún beneficio de seguridad. La comprobación de scope de OAuth no se vuelve más rigurosa por hacerla doce veces en lugar de una.

Si construye un MCP server sobre datos de producción, este fue el patrón que mejor nos funcionó. Canalice cada escritura por las mismas clases de acción que ya usa su aplicación web. Trate la herramienta MCP como una capa fina de traducción: esquema de entrada, llamada validada a la acción, recurso de salida. Todo lo demás, es decir, las anotaciones, el descubrimiento de campos personalizados y las URL canónicas, es decoración propia del protocolo sobre ese mismo núcleo. La lista completa de herramientas y las instrucciones de configuración están en [/developers/mcp](https://relaticle.com/es/developers/mcp). Para la vista orientada al usuario del mismo servidor, consulte [cómo conectar Claude a su CRM con MCP](https://relaticle.com/es/blog/como-conectar-claude-a-su-crm-con-mcp) y [qué significa realmente un CRM agent-native](https://relaticle.com/es/blog/que-significa-realmente-un-crm-agent-native).

 Etiquetas [ #mcp ](https://relaticle.com/es/blog/tag/mcp) 

 En esta página

 Siga leyendo

 Artículos relacionados. 
-------------------------

- [  2 de nov. de 2026  Ingeniería 

    ###  Abusaron de una prueba gratuita de modelos de IA premium: qué cambiamos 

    Una prueba sin tarjeta que desbloqueaba modelos de IA premium atrajo cuentas que nunca tocaron el CRM. En lugar de pedir una tarjeta, vinculamos los modelos premium con el primer registro real.

     ![](https://relaticle.com/storage/ink/01M7T5522BJSGFB1CXDCPP1CFP.png) 

     ](https://relaticle.com/es/blog/prueba-gratuita-de-modelos-de-ia-premium-abusada-que-cambiamos)
- [  21 de oct. de 2026  Ingeniería 

    ###  php2shell: cómo parcheamos Relaticle y cómo parchear su instalación 

    php2shell son dos fallas críticas de PHP que permiten a un atacante ejecutar código en un servidor web. Qué parcheamos en Relaticle Cloud y qué debe hacer hoy una instalación autoalojada.

     ![](https://relaticle.com/storage/ink/01M7T57XDGVV1RD8HF8DQTQDKH.png) 

     ](https://relaticle.com/es/blog/php2shell-parchear-php-en-docker-y-forge)
- [  22 de sep. de 2026  Ingeniería 

    ###  Campos personalizados que funcionan en todas partes sin código por campo 

    Cómo Relaticle hace que los campos personalizados estén disponibles en formularios, API, chat y MCP, con normalización compartida, semántica clara de valores vacíos y límites explícitos.

     ![](https://relaticle.com/storage/ink/01M7T4K1A46GQZWMVA6VMW0NH0.png) 

     ](https://relaticle.com/es/blog/campos-personalizados-que-funcionan-en-todas-partes)
