Synapse

"Разрешительный" (permission-aware) MCP сервер для Frappe и ERPNext. Он позволяет LLM-клиенту читать и записывать данные сайта как реальный пользователь, с правами этого пользователя, через OAuth, при этом каждый вызов попадает в журнал аудита.

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

Зачем ещё один

Большинство Frappe MCP-серверов работают с привилегиями и отдают модели сырой SQL или доступ к документам через ignore_permissions. Для личной песочницы это нормально, для бизнес-системы — неприемлемо. Synapse занимает противоположную позицию:

• Никаких ignore_permissions — нигде. Каждый инструмент работает от имени вызывающего пользователя. Действуют разрешения DocType, User Permissions, share-правила и права на submit/cancel, а запись идёт через Document.insert/save/submit/cancel, поэтому валидации, хуки и рабочие процессы срабатывают точно так же, как в интерфейсе (desk).

• Вторая граница поверх разрешений, потому что «этот пользователь может редактировать Sales Invoice в интерфейсе» и «агент, владеющий токеном этого пользователя, может редактировать Sales Invoice» — это разные решения.

• Логируется всё, в том числе вызовы, отклонённые ещё до того, как дошли до инструмента.

• Нет зависимостей. MCP-сервер встроен и поставляется с исходным кодом приложения, поэтому bench install-app — это вся установка целиком, а bench update остаётся безопасным.

Related MCP server: Frappe Assistant Core

Установка

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

Затем в любой момент можно проверить, на какой стадии находится сайт:

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

Команда печатает, что уже настроено и чего не хватает, в порядке, в котором это нужно исправлять. Свежая установка полностью закрыта: ничего не доступно, пока вы сами не разрешите.

Инструменты

Даты возвращаются в формате, заданном в месте с настройками MCP Settings; по умолчанию — ISO. При записи принимаются как ISO, так и ДД-ММ-ГГГГ, так что при цикле «прочитать — изменить — записать» день и месяц не могут поменяться местами.

Преднамеренно не представлены: frappe.db.set_value (пропускает валидации и хуки — инструмент set_value вместо этого загружает и сохраняет документ), произвольное выполнение любого whitelisted Метода, переименование и amend-документы.

Четыре уровня защиты

Каждый вызов проходит через все четыре. Они независимы, и побеждает самый узкий уровень:

1. Аутентификация. Конечная точка закрыта для гостей, поэтому не аутентифицированный POST отклоняется фреймворком ещё до выполнения какого-либо кода инструменты.

2. Роль на инструмент. Документные инструменты требуют роль MCP Agent, и инструмент SQL требует MCP SQL Reader . Без роли этот инструмент даже не появится в списке.

3. Список доступа MCP (MCP Settings) — разрешающий (allowlist) или запрещающий (denylist) список. Для любых действий, кроме чтения, вызывающая сторона должна также обладать ролью, которой сайт предоставил соответствующее право.

4. Собственные разрешения Frappe, как описано выше.

For Administrator no исключений. Она обладает всеми ролями, поэтому проверка ролей на барьерах 2 и 3 пройдена, that, but список DocType по-прежнему действует/остаётся ограничением.

Мода доступа

Allowlist (разрешающий список) — доступно только перечисленные DocTypes, each with clearance. Действует принцип закрытого по умолчанию: новый DocType остаётся недоступным, пока кто-то не изменит branding. Это режим по умолчанию, и в only fresh installed there still empty list, so ничего не accessible at all.

Denylist (запрещаемый список) — доступен каждый DocType, кроме those explicitly listed. The basis is the user's own Frappe permissions, and the list is a carve-out of what nobody should touch the agent, whatever his user is allowed to. Each line blocks everything by default; turn off Block Read, и тогда DocType останется в правом чтения, но не изменен.

Denylist удобнее в полном ERP. His price - a new DocType — appears already reachable himself, this mode enforces two additional rules sets, independent of whether they are in the access list:

• Никогда not меня are: OAuth Bearer Token, OAuth Authorization Code, OAuth Client, Token Cache, Social Login Key, Connected App, Webhook, Email Account, Email Integration Request, User Social Login, Access Log. Reading data is possible to read from reader becoming author.

• Только чтение — всегда: DocType, DocField, DocPerm, Custom DocPerm, Special Custom: DocType, DocCrypt... Wait; list must be same: DocType, DocPerm, Custom DocPerm, Custom Field, Property Setter, Server Script, Client Script, Print Format, ReportOn regulation , Role, Has Role, User, User Permission, System Settings, Workflow, Scheduled Job Type. An agent that can edit Custom DocPerm can grant itself whatever you want.

In allowlist mode, neither of these sets applies — the table is the only authority in that mode.

Дочерние таблицы никогда не доступны напрямую; they are read and written through their parent. Matching is case-insensitive, and the DocType name is canonicalised against the site before consulting the list, so salary slip мимо строчки will not pass Salary Slip.

To fill a large allowlist without hundreds of grid rows:

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 defaults to read-only and obeys these two same protected sets. If you want to make everything accessible, denylist with empty list says it more honestly than 700 allowlist rows.

Setup

1. OAuth. Fraun 16 publishes OAuth server metadata and supports dynamic client registration — about this MFP-client can connect without the open, manual card OAuth Client. By default, Proсеянное the firewall? on by default. In OAuth Settings turn on Show Auth Server Metadata, Show Protected Resource Metadata и Enable Dynamic Client Registration. Synapse never touches this — these are globally affect the whole site's OAuth, not only MCP.

Let's clarify what token power gives: Frapp OAuth token is not limited to the MCP; it is no more than authorisation of the whole /api as that user.

2. Give the role MCP Agent to the user on behalf of what the agent will act. Whoever authenticates is exactly the identity under which all tools are executed, so limitэто до того, что агент должен видеть, rather than giving Administrator.

3. Fill the MCP Settings. Mark the point Enable MCP Endpoint, choose Access Mode and fill in what is displayed. From this point Readings work. For recording copies, additionally turn on Enable Write Tools and give actions to specific roles in Role Permissions; if this table is empty, the endpoint stays read-only anything else.

Подключение клиента

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

Then, authenticate — the browser opens the site login page. Any MCP client that speaks Streamable HTTP with OAuth works the same way; in Claude Desktop this is: Settings → Connectoren → Add custom connector with same URL afterwards.

Raw SQL — прочитайте before you enable it

run_sql_query bypasses Fraun permissions system. A user with MCP SQL Reader can read every table the site has, regardless of their DocType rights. Give out this role only to those who already have full access to the database.

The tool is turned off, until the flag Enable Read-Only SQL Tool always. She does not use the DocType access list – she can't, Yes she never refers to a DocType. Use with preference get_list and get_doc; take SQL only for a join or aggregate, which they cannot express. If an agent constantly will go into SQL, the tools for documents do not enough.

Behind it two layers:

1. Only DB user permission. Write enforced by MariaDB, so the query, which will slip past the text filter, cannot still write.

2. mcp_tools/guard.py — type of operation, no comments, no stacked queries, keyword blocklist, table blocklist and length cap. This is text-based matching, so treat it as a fallback, and not as a comprehensive protection itself.

Set up layer 1 for each site. With MariaDB root rights:

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;

And then in site_config.json (never in the repo):

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

Without these keys, the tool falls back to the site's own “read-write connection”, and after each query makes a rollback. It works, but this only means the guard is the only boundary. On hosted platforms that do not allow creating a second database user — that's the only option; decide this consciously before you turn SQL enable there.

Extend the per-site table blocklist with mcp_sql_blocked_tables in site_config.json. MariaDB only; connection.py will raise NotImplementedError on other DBs.

Аудит

Every call writes the MCP Access Log row — success, refusal, or error — with the tool, user, authentication method, IP, document that means inn, row counts and время. If the writes succeed, their values and the changed/tracked data are also recorded to the log; before and after the change. Calls that are rejected before executing the tool's body (unknown tool, missing role, argument mismatch) are also logged: an agent checks accesses to itself that it doesn't have — that's exactly what an audit trail is for.

When the call goes without log entirely, it never reached the location. If the tool seems blocked but the log is silent — then the blocking is performed by the client side of the tool, most likely right in its when authorizing the tool's use. Check that before any other.

Rows are created with their own commit after any rollback, so a failed or rejected write still leaves behind a record. For System Manager — readable and reportable, not creatable or editигру from the interface. reference_doctype and reference_name are object and Data, not Link — deliberately: an audit line should never block the deletion of what it describes. Daily job deletes inbox lines older than of the retention window. Remove the tick with Log Field Values, if the data itself should not be copied into the journal; password fields in any case are masked.

Tests

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

The access list, the SQL guard, the tool markers and the value conversion do not depend on imp* into frappe, so they also run without a site:

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

License

AGPL v3.0 (GNU Affero General Public License) or new. See LICENSE.

AGPL is a deliberate choice: if you run modified Synapse as a network service, the users of it have the right to your changes.