Synapse

Un servidor MCP consciente de permisos para Frappe y ERPNext. Permite que un cliente LLM lea y escriba los datos de un sitio como un usuario real, bajo los permisos de ese usuario, mediante OAuth, con cada llamada registrada en un registro de auditoría.

POST https://<your-site>/api/method/synapse.mcp.handle_mcp

Por qué otro

La mayoría de los servidores MCP de Frappe se ejecutan con privilegios y le dan al modelo SQL crudo o acceso a documentos con ignore_permissions. Eso está bien para un sandbox personal e inaceptable en un sistema empresarial. Synapse adopta la posición contraria:

• Sin ignore_permissions, en ningún sitio. Cada herramienta se ejecuta como el usuario que llama. Se aplican los permisos de DocType, los permisos de usuario, las reglas de uso compartido y los derechos de envío/cancelación, y las escrituras pasan por Document.insert/save/submit/cancel para que las validaciones, los hooks y los flujos de trabajo se disparen exactamente igual que en el escritorio.

• Una segunda frontera por encima de los permisos, porque "este usuario puede editar Sales Invoices en el escritorio" y "un agente que posee el token de este usuario puede editar Sales Invoices" son decisiones distintas.

• Todo queda registrado, incluidas las llamadas rechazadas antes de llegar a una herramienta.

• Sin dependencias. El servidor MCP está integrado (vendored), así que bench install-app es toda la instalación y bench update sigue siendo seguro.

Related MCP server: Frappe Assistant Core

Instalación

bench get-app https://github.com/erpuae/synapse
bench --site <your-site> install-app synapse

Luego comprueba en qué punto está el sitio en cualquier momento:

bench --site <your-site> execute synapse.mcp_tools.check.report

Imprime lo que está configurado y lo que falta, en el orden en que debe corregirse. Una instalación nueva está totalmente cerrada: nada es accesible hasta que tú lo indiques.

Herramientas

Las fechas se devuelven en el formato establecido en MCP Settings, ISO por defecto. Las escrituras aceptan tanto ISO como DD-MM-YYYY, de modo que un ciclo de lectura-modificación-escritura no puede intercambiar día y mes.

Deliberadamente no expuesto: frappe.db.set_value (omite validaciones y hooks — la herramienta set_value carga y guarda el documento en su lugar), ejecución arbitraria de métodos en lista blanca, renombrar y enmendar.

Cuatro barreras

Toda llamada pasa por las cuatro. Son independientes, y la más restrictiva gana.

1. Autenticación. El endpoint está cerrado para invitados, por lo que el framework rechaza un POST no autenticado antes de que se ejecute cualquier código de herramienta.

2. Un rol en la herramienta. Las herramientas de documentos necesitan MCP Agent, la herramienta SQL necesita MCP SQL Reader. Sin el rol, la herramienta ni siquiera aparece en la lista.

3. La lista de acceso de MCP (MCP Settings), una lista de permitidos o una lista de denegados. Para cualquier cosa que no sea una lectura, el llamante también debe tener un rol al que el sitio haya concedido esa acción.

4. Los permisos propios de Frappe, como se ha descrito anteriormente.

El Administrador no está exento. Tiene todos los roles, por lo que las comprobaciones de rol de las barreras 2 y 3 se superan, pero la lista de DocTypes sigue siendo vinculante.

Modo de acceso

Lista de permitidos — nada es accesible excepto los DocTypes enumerados, cada uno con las acciones marcadas. Falla en modo cerrado; un DocType nuevo permanece inaccesible hasta que alguien indique lo contrario. Este es el valor predeterminado, y una instalación nueva tiene una lista vacía, por lo que no hay nada accesible en absoluto.

Lista de denegados — todos los DocTypes son accesibles excepto los enumerados. Los permisos propios de Frappe del usuario se convierten en la frontera operativa, y la lista excluye lo que ningún agente debería tocar, haga lo que haga su usuario. Cada fila bloquea todo por defecto; desmarca Block Read para dejar un DocType legible pero no modificable.

La lista de denegados es más fácil de llevar en un ERP completo. Su coste es que un DocType nuevo llega accesible, por lo que en ese modo se aplican dos conjuntos, los enumeren o no:

• Nunca accesibles: OAuth Bearer Token, OAuth Authorization Code, OAuth Client, Token Cache, Social Login Key, Connected App, Webhook, Email Account, Integration Request, User Social Login, Access Log. Leer estos es la forma en que un lector se convierte en escritor.

• Solo lectura, siempre: DocType, DocField, DocPerm, Custom DocPerm, Custom Field, Property Setter, Server Script, Client Script, Print Format, Report, Role, Has Role, User, User Permission, System Settings, Workflow, Scheduled Job Type. Un agente que pueda editar Custom DocPerm puede concederse cualquier cosa.

En el modo de lista de permitidos no se aplica ninguno de los dos conjuntos — allí la tabla es la única autoridad.

Las tablas hijas nunca son accesibles directamente; se leen y escriben a través de su padre. La coincidencia no distingue mayúsculas y el nombre del DocType se canonicaliza contra el sitio antes de consultar la lista, de modo que salary slip no puede colarse ante una fila que diga Salary Slip.

Para rellenar una lista de permitidos grande sin marcar cientos de filas de cuadrícula:

bench --site <your-site> execute synapse.mcp_tools.allowlist.grant_all --kwargs "{'dry_run': 1}"
bench --site <your-site> execute synapse.mcp_tools.allowlist.grant_all
bench --site <your-site> execute synapse.mcp_tools.allowlist.show

grant_all por defecto es solo lectura y aplica los mismos dos conjuntos protegidos. Si quieres que todo sea accesible, el modo de lista de denegados con una lista vacía lo dice más honestamente que 700 filas de lista de permitidos.

Configuración

1. OAuth. Frappe 16 publica metadatos de servidor OAuth y admite registro dinámico de clientes, que es lo que permite que un cliente MCP se conecte sin tener que crear un registro de OAuth Client manualmente. Está desactivado por defecto. En OAuth Settings activa Show Auth Server Metadata, Show Protected Resource Metadata y Enable Dynamic Client Registration. Synapse nunca cambia estos ajustes — afectan al comportamiento OAuth de todo el sitio, no solo a MCP.

Sé claro sobre lo que concede un token: un token OAuth de Frappe no está limitado a MCP. Autoriza toda la superficie /api como ese usuario.

2. Asigna MCP Agent al usuario por el que actuará el agente. Quien se autentica es la identidad bajo la que se ejecuta cada herramienta, así que limita a ese usuario a lo que el agente debe ver en lugar de usar un Administrador.

3. Rellena MCP Settings. Marca Enable MCP Endpoint, elige Access Mode y rellena la lista que muestra. Las lecturas funcionan en este punto. Para escrituras, marca también Enable Write Tools y concede las acciones a roles específicos en Role Permissions; con esa tabla vacía, el endpoint permanece de solo lectura se configure lo que se configure.

Conexión de un cliente

claude mcp add --transport http mysite https://<your-site>/api/method/synapse.mcp.handle_mcp

Luego autentícate — se abre un navegador en el inicio de sesión del sitio. Cualquier cliente MCP que hable Streamable HTTP con OAuth funciona de la misma manera; en Claude Desktop es Settings → Connectors → Add custom connector con la misma URL.

SQL crudo: lee esto antes de habilitarlo

run_sql_query omite por completo el sistema de permisos de Frappe. Un usuario con MCP SQL Reader puede leer todas las tablas del sitio independientemente de sus permisos de DocType. Concédelo solo a usuarios que ya tengan acceso completo a la base de datos.

Está desactivado hasta que se marca Enable Read-Only SQL Tool, y no usa la lista de acceso de DocTypes — no puede, ya que nunca nombra un DocType. Prefiere get_list y get_doc; recurre a SQL solo para un join o un agregado que no puedan expresar. Si un agente recurre a SQL constantemente, a las herramientas de documentos les falta algo que necesita.

Dos capas lo respaldan:

1. Un usuario de base de datos de solo lectura, impuesto por MariaDB, de modo que una consulta que supere el filtro de texto no pueda escribir.

2. mcp_tools/guard.py — tipo de sentencia, sin comentarios, sin sentencias apiladas, una lista de bloqueo de palabras clave, una lista de bloqueo de tablas y un límite de longitud. Coincidencia de texto, así que trátalo como una medida complementaria, no como la principal.

Configura la capa 1 por sitio. Como root de MariaDB:

CREATE USER 'mcp_ro'@'localhost' IDENTIFIED BY '<STRONG_PASSWORD>';
GRANT SELECT ON `<DB_NAME>`.* TO 'mcp_ro'@'localhost';
REVOKE FILE ON *.* FROM 'mcp_ro'@'localhost';
FLUSH PRIVILEGES;

Luego en site_config.json (nunca en el repositorio):

{
  "mcp_ro_db_user": "mcp_ro",
  "mcp_ro_db_password": "<STRONG_PASSWORD>"
}

Sin esas claves, la herramienta recurre a la conexión de lectura-escritura del propio sitio, revirtiendo después de cada consulta. Funciona, pero el guard se convierte en la única frontera. En plataformas alojadas donde no es posible un segundo usuario de base de datos, ese recurso es la única opción — decide conscientemente antes de habilitar SQL allí.

Amplía la lista de bloqueo de tablas por sitio con mcp_sql_blocked_tables en site_config.json. Solo MariaDB; connection.py lanza NotImplementedError en otros backends.

Auditoría

Cada llamada escribe una fila en MCP Access Log — éxito, rechazo o error — con la herramienta, el usuario, cómo se autenticó, IP, documento tocado, recuentos de filas y tiempos. Las escrituras también registran los valores enviados y el antes/después de cada campo modificado. Las llamadas rechazadas antes de que se ejecute el cuerpo de la herramienta (herramienta desconocida, rol faltante, argumentos que no encajan) también se registran: un agente que sondea herramientas a las que no tiene derecho es exactamente para lo que sirve un registro de auditoría.

Una llamada que falta por completo en el registro nunca llegó al servidor. Si una herramienta parece bloqueada y el registro no tiene nada para ella, el bloqueo está en el cliente, casi siempre en su propio aviso de permisos de herramientas. Eso es lo primero que hay que comprobar.

Las filas se escriben con su propia confirmación después de cualquier reversión, de modo que una escritura fallida o rechazada deja igualmente su registro. Legible y reportable por System Manager, no creable ni editable desde el escritorio. reference_doctype y reference_name son campos Data en lugar de Link a propósito — una fila de auditoría nunca debe bloquear la eliminación de lo que registra. Un trabajo diario elimina las filas que superan la ventana de retención. Desmarca Log Field Values si los datos en sí no deben duplicarse en el registro; los campos similares a contraseñas se enmascaran de todos modos.

Pruebas

bench --site <your-site> run-tests --app synapse

La lista de acceso, el guard de SQL, los esquemas de herramientas y la conversión de valores no importan nada de frappe, por lo que también se ejecutan sin un sitio:

python -m unittest discover -s apps/synapse -p 'test_mcp_*.py'

Licencia

GNU Affero General Public License v3.0 o posterior. Consulta LICENSE.

AGPL es deliberado: si ejecutas un Synapse modificado como servicio de red, las personas que lo usan tienen derecho a tus cambios.