mcp-creatio 0.6.2 → 0.6.4

package/README.md

@@ -4,62 +4,63 @@
 [![Docker pulls](https://img.shields.io/docker/pulls/crackish/mcp-creatio)](https://hub.docker.com/r/crackish/mcp-creatio)
 [![License](https://img.shields.io/github/license/CRACKISH/mcp-creatio)](LICENSE)
 
-Model Context Protocol (MCP) server for Creatio (https://www.creatio.com/) to connect Claude Desktop, ChatGPT, GitHub Copilot, and other AI tools to Creatio data.
+Model Context Protocol (MCP) server for [Creatio](https://www.creatio.com/) — connect Claude
+Desktop, ChatGPT, GitHub Copilot, and other AI tools to your Creatio data, schema, and processes.
 
-Also discoverable as:
+> Also discoverable as: _Creatio MCP server_ · _MCP server for Creatio CRM_ · _Model Context
+> Protocol for Creatio_.
 
-- Creatio MCP server
-- MCP server for Creatio CRM
-- Model Context Protocol for Creatio
+---
 
-## Overview
+## Contents
 
-- Exposes Creatio data as MCP tools for MCP-compatible clients (Claude Desktop, ChatGPT Connectors, GitHub Copilot)
-- Supports reading, creating, updating, deleting records and inspecting schema
-- Execute Creatio business processes with parameters
-- Selectable data backend: Creatio DataService (default) or OData v4 (`CREATIO_CRUD_BACKEND`)
+- [What it does](#what-it-does)
+- [Quick start](#quick-start)
+- [Authentication](#authentication)
+- [Configuration](#configuration)
+- [CRUD backend](#crud-backend)
+- [Tools](#tools)
+- [Docker](#docker)
 
-## Features
+---
 
-- **CRUD operations**: read, create, update, delete Creatio records
-- **Schema discovery**: list entity sets and inspect entity schemas
-- **Business processes**: run Creatio workflows with parameters
-- **System settings**: read, write, and manage system setting metadata
-- **Feature toggles**: manage `Feature` / `AdminUnitFeatureState` and refresh the feature cache. ⚠️ Only DB-backed features are reachable — features defined exclusively in `web.config` or other non-DB providers are invisible to MCP.
-- **System operations**: manage `SysAdminOperation` and per-user/role grants (Creatio blocks these tables for OData modifications, so dedicated tools are provided)
-- **Custom services**: invoke any configuration-package REST service (`/0/rest/<service>/<method>`) when no dedicated tool fits
-- **AI assistant compatibility**: Claude Desktop, ChatGPT Connectors, GitHub Copilot
-- **Three authentication modes**: Legacy login/password, OAuth2 client credentials, OAuth2 authorization code
-- **Built-in OAuth server**: Automatic MCP client authentication
-- **Docker ready**: Multi-arch images available
+## What it does
 
-## Run Modes
+- **CRUD + schema** — read, create, update, delete records; list entity sets; inspect schemas.
+- **Business processes** — run Creatio workflows with parameters.
+- **System settings** — read, write, and manage system-setting metadata.
+- **Feature toggles** — manage `Feature` / `AdminUnitFeatureState` and refresh the feature cache.
+  ⚠️ Only DB-backed features are reachable (those defined solely in `web.config` are invisible).
+- **System operations** — manage `SysAdminOperation` and per-user/role grants (OData blocks these
+  tables, so dedicated tools are provided).
+- **Custom services** — invoke any configuration-package REST service (`/0/rest/<service>/<method>`)
+  when no dedicated tool fits.
+- **Selectable data backend** — Creatio DataService (default) or OData v4 (`CREATIO_MCP_CRUD_BACKEND`).
+- **Optional semantic layers** — DataForge and Global Search tools auto-register when the instance
+  supports them.
 
-This project supports two runtime modes:
+Works with Claude Desktop, ChatGPT Connectors, GitHub Copilot, and any MCP-compatible client.
 
-### 1. CLI Mode (`stdio`)
+---
 
-Use this mode for MCP clients that launch a command directly (VS Code MCP, Claude Desktop, etc.).
+## Quick start
 
-- No HTTP endpoint needed
-- Easiest local setup
-- Supports Legacy auth and OAuth2 Client Credentials
-- OAuth2 Authorization Code is **not** supported in `stdio` mode
+The server runs in one of two transports. **Pick by how your client connects**, then pick an
+[authentication](#authentication) method.
 
-Run directly from npm:
+### stdio (single-user, local)
+
+For clients that launch a command directly (VS Code MCP, Claude Desktop). Single Creatio identity
+per process; authenticate with **client credentials** or **legacy** login.
 
 ```bash
 npx -y mcp-creatio@latest \
   --base-url https://your-creatio.com \
-  --login your_login \
-  --password your_password
+  --login your_login --password your_password
 ```
 
-`stdio` logs are disabled by default. To enable them, set `MCP_CREATIO_LOG_LEVEL` or pass `--log-level info`.
-
-VS Code MCP config (command-based):
-
-```json
+```jsonc
+// VS Code / Claude Desktop (command-based)
 {
 	"creatio": {
 		"command": "npx",
@@ -71,162 +72,252 @@ VS Code MCP config (command-based):
 			"--login",
 			"your_login",
 			"--password",
-			"your_password"
-		]
-	}
+			"your_password",
+		],
+	},
 }
 ```
 
-Local repo command (without publishing):
+> stdio logs are silent by default — enable with `--log-level info` or `CREATIO_MCP_LOG_LEVEL`.
+
+### HTTP (multi-user, hosted)
+
+For clients that connect by URL, and for multi-user / hosted deployments. This transport serves the
+`broker`, `delegated`, and `gateway` auth modes (see [Authentication](#authentication)).
 
 ```bash
-npm run start:stdio -- --base-url https://your-creatio.com --login your_login --password your_password
+npm start                     # serves http://localhost:3000/mcp
 ```
 
-### 2. Server Mode (`http`)
+```jsonc
+{ "creatio": { "type": "http", "url": "http://localhost:3000/mcp" } }
+```
+
+---
+
+## Authentication
+
+One unified selector — `CREATIO_MCP_AUTH_MODE` — picks how a request proves its Creatio identity.
+When unset it is inferred from the credentials you provide. The HTTP modes are multi-user; stdio is
+single-user.
 
-Use this mode when your client connects by URL (for example `http://localhost:3000/mcp`).
+| Mode                     | Transport    | How identity is established                                                                     | When to use                                                                                  |
+| ------------------------ | ------------ | ----------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| **`broker`**             | HTTP         | The MCP is its own OAuth server: it walks the user through Creatio login and holds their tokens | **Standalone direct clients** (Claude Desktop / ChatGPT) — connect → authorize → work as you |
+| **`delegated`**          | HTTP         | The client brings a Creatio token; the MCP validates expiry and passes it through               | Clients that obtain a Creatio token themselves / behind an external AS                       |
+| **`gateway`**            | HTTP         | A trusted Control-Plane injects the token per request                                           | Behind the Creatio.ai Control-Plane (multi-tenant)                                           |
+| **`client_credentials`** | stdio / HTTP | One service account (`client_id` / `secret`)                                                    | M2M / single service identity                                                                |
+| **`legacy`**             | stdio / HTTP | One user (login / password)                                                                     | Local / legacy instances                                                                     |
 
-- Exposes HTTP endpoint: `/mcp`
-- Required for OAuth2 Authorization Code flow
-- Works well with Docker and remote deployments
+> The MCP issues Creatio tokens of its own only in `broker` mode (where it must, to drive the
+> login). `delegated`/`gateway` pass tokens through; `client_credentials`/`legacy` use a single
+> server-side identity.
 
-Start server:
+> **Trust model.** `delegated` and `gateway` are **fully-trusted-environment** modes: the MCP does
+> NOT cryptographically verify the incoming Bearer — Creatio remains the authority and rejects bad
+> tokens on the API call — so the request's `userKey` is an unverified, logging-only identity. Run
+> them only where the caller is trusted (`gateway`: behind the Creatio.ai Control-Plane;
+> `delegated`: a trusted client on a trusted network / your own proxy). For an **untrusted direct
+> external client** that needs the MCP itself to verify identity, use `broker` — there the MCP
+> issues and verifies its own audience-bound (`aud`/`iss`) tokens.
+
+### `broker` — the "connect & authorize" UX for direct clients
+
+The MCP acts as an OAuth 2.1 authorization server for its clients (dynamic registration, authorize,
+token) and brokers the actual login to Creatio via authorization_code with PKCE. The client only
+ever talks to the MCP, so this works even though Creatio offers no dynamic client registration — and
+the client never needs to reach Creatio's TLS endpoint directly.
+
+The tokens the MCP issues to clients are **audience-bound** (`aud` = this deployment's `/mcp`
+resource, `iss` = its origin), so a token minted by one deployment is rejected by another even when
+they share a secret. The MCP also supports the **`refresh_token` grant** (rotating), so a client
+gets a fresh access token without re-running the browser flow every hour — for as long as the MCP
+still holds that user's Creatio tokens.
 
 ```bash
-npm start
+CREATIO_MCP_AUTH_MODE=broker
+CREATIO_CLIENT_ID=your_creatio_oauth_app_client_id   # the Creatio "On behalf of a user" app
+CREATIO_MCP_JWT_SECRET=a-long-random-secret-min-32   # signs the tokens the MCP issues to clients
+# CREATIO_CLIENT_SECRET=...                            # only for a confidential Creatio app (omit for public/PKCE)
 ```
 
-Then connect using URL:
+> **`CREATIO_MCP_JWT_SECRET`** must be **at least 32 characters** (HS256 security rests entirely on
+> its entropy — a shorter value is rejected at startup). In **production** (`NODE_ENV=production`) it
+> is **required** (the server fails closed if unset). Outside production an unset secret yields a
+> random one so a local run needs no setup — but the tokens the MCP issues are then invalidated on
+> every restart and are not valid across multiple instances, so **set a stable secret for production
+> or any horizontally-scaled deployment.**
+
+**Persistence / horizontal scaling (broker holds users' Creatio tokens).** By default those tokens
+live in-process — fine for a single instance, but lost on restart and not shared across replicas.
+For production set a **Redis** token store: tokens are encrypted at rest (AES-256-GCM) and survive
+restarts, so the broker becomes stateless and horizontally scalable.
+
+```bash
+CREATIO_MCP_TOKEN_STORE=redis
+CREATIO_MCP_REDIS_URL=redis://your-redis:6379
+# CREATIO_MCP_TOKEN_ENC_KEY=...   # optional; encryption key, else derived from CREATIO_MCP_JWT_SECRET
+```
+
+**Logout / revocation.** The broker exposes an **RFC 7009** `POST /revoke` endpoint (advertised as
+`revocation_endpoint` in the AS metadata): presenting an issued token revokes the user's Creatio
+token upstream (`/connect/revocation`, best-effort) and purges the server-side Creatio tokens and
+issued refresh tokens. It always answers `200` (no token-validity oracle).
+
+Register the Creatio app in System Designer → _OAuth 2.0 applications_ → _On behalf of a user_, and
+add the MCP callback (`http://localhost:3000/oauth/callback` for a local run) to its redirect URIs.
 
-```json
+### `delegated` (default when nothing else is set)
+
+Pure resource server: each `/mcp` request must carry a Creatio access token; the MCP advertises the
+authorization server (Creatio Identity) via **RFC 9728** and challenges unauthenticated requests, so
+the client logs in directly against Creatio. Needs no server-side credentials. The token is passed
+through unverified (Creatio is the authority) — a **trusted-environment** mode (see the trust note
+above).
+
+**What the client sends.** The MCP **client** attaches the Creatio access token as a Bearer header
+on every `/mcp` request. In a client that supports static headers:
+
+```jsonc
 {
 	"creatio": {
 		"type": "http",
-		"url": "http://localhost:3000/mcp"
-	}
+		"url": "http://localhost:3000/mcp",
+		"headers": { "Authorization": "Bearer <CREATIO_ACCESS_TOKEN>" },
+	},
 }
 ```
 
-## Configuration
+Server side, just select the mode (no credentials needed):
 
-| Variable                     | Description                                                          |
-| ---------------------------- | -------------------------------------------------------------------- |
-| `CREATIO_BASE_URL`           | **Required**. Creatio instance URL (e.g. `https://your-creatio.com`) |
-| `CREATIO_LOGIN`              | Username for legacy auth                                             |
-| `CREATIO_PASSWORD`           | Password for legacy auth                                             |
-| `CREATIO_CLIENT_ID`          | OAuth2 client credentials ID                                         |
-| `CREATIO_CLIENT_SECRET`      | OAuth2 client credentials secret                                     |
-| `CREATIO_ID_BASE_URL`        | Identity Service URL (if separate from main Creatio instance)        |
-| `CREATIO_CODE_CLIENT_ID`     | OAuth2 authorization code client ID                                  |
-| `CREATIO_CODE_CLIENT_SECRET` | OAuth2 authorization code client secret                              |
-| `CREATIO_CODE_REDIRECT_URI`  | OAuth2 redirect URI (e.g. `http://localhost:3000/oauth/callback`)    |
-| `CREATIO_CODE_SCOPE`         | OAuth2 scope (e.g. `offline_access ApplicationAccess_yourappguid`)   |
-| `CREATIO_CRUD_BACKEND`       | CRUD data API: `dataservice` (default) or `odata`                    |
-| `READONLY_MODE`              | Set `true` to disable create/update/delete operations                |
-| `DISABLE_DATAFORGE`          | Set `true` to never probe/register DataForge tools (even if available) |
-| `DISABLE_GLOBAL_SEARCH`      | Set `true` to never probe/register the Global Search tool            |
-| `MCP_TRANSPORT`              | Docker only: `http` (default) or `stdio` — selects the run mode      |
-| `PORT`                       | HTTP mode listen port (default `3000`)                               |
-| `MCP_CREATIO_LOG_LEVEL`      | Log verbosity: `silent` (default), `error`, `warn`, `info`           |
-
-> **Disabling optional capabilities.** DataForge and Global Search are auto-detected at
-> startup and their tools registered only when the environment supports them. Set
-> `DISABLE_DATAFORGE=true` / `DISABLE_GLOBAL_SEARCH=true` to skip the probe **and** the tools
-> entirely — useful when a capability exists on the instance but you don't want to expose it
-> (e.g. to keep the tool surface small / avoid spending tokens on it).
-
-### CRUD backend
+```bash
+CREATIO_MCP_AUTH_MODE=delegated
+CREATIO_BASE_URL=https://your-creatio.com
+```
 
-CRUD tools (`read`, `create`, `update`, `delete`, `list-entities`, `describe-entity`) run on a
-selectable data API, chosen once per deployment via `CREATIO_CRUD_BACKEND`:
+A request with **no** `Authorization` header gets `401` with a `WWW-Authenticate` challenge pointing
+at Creatio Identity (RFC 9728), so a compliant client knows where to log in.
 
-- **`dataservice`** (default) — Creatio's native DataService.
-- **`odata`** — Creatio OData v4. Also enables the OData-only `read` extras (`filter` raw
-  `$filter` string, `expand`).
+### `gateway`
 
-Either way you query through the same tool surface: prefer the structured `filters` parameter —
-it works unchanged on both backends.
+A trusted fronting service (Creatio.ai Control-Plane) injects the Bearer; the MCP trusts and uses
+it. The optional `X-Creatio-Base-Url` header routes a request to a specific Creatio instance
+(multi-tenant) — honored only in this mode. Because that override decides where the request's Bearer
+is sent, it is validated: set **`CREATIO_MCP_ALLOWED_BASE_URLS`** (comma-separated origins) to
+restrict it to your tenants. When unset, any `http(s)` host is accepted (trusting the gateway) except
+the cloud-metadata link-local address, which is always blocked (SSRF guard).
 
-## Authentication Modes
+**Who sends what.** Unlike `delegated`, the end client talks to the **gateway**, not to the MCP — so
+the **gateway** is what injects the per-request headers. On each forwarded `/mcp` call it sends:
 
-Choose one of three ways to authenticate with Creatio:
+```http
+POST /mcp HTTP/1.1
+Authorization: Bearer <CREATIO_ACCESS_TOKEN>     # required — the tenant's Creatio token
+X-Creatio-Base-Url: https://tenant-a.creatio.com  # optional — pick the tenant's instance (multi-tenant)
+```
 
-### 1. Legacy (Username/Password)
+Server side:
 
 ```bash
-CREATIO_LOGIN=YourLogin
-CREATIO_PASSWORD=YourPassword
+CREATIO_MCP_AUTH_MODE=gateway
+CREATIO_BASE_URL=https://default-creatio.com                          # fallback when no X-Creatio-Base-Url
+CREATIO_MCP_ALLOWED_BASE_URLS=https://tenant-a.creatio.com,https://tenant-b.creatio.com  # SSRF allowlist
 ```
 
-### 2. OAuth2 Client Credentials
-
-For server-to-server authentication. [Setup guide →](https://academy.creatio.com/docs/8.x/dev/development-on-creatio-platform/integrations-and-api/authentication/oauth-2-0-authorization/identity-service-overview)
+Smoke-test it directly with `curl` (mint a token out-of-band first):
 
 ```bash
-CREATIO_CLIENT_ID=your_client_id
-CREATIO_CLIENT_SECRET=your_client_secret
+curl -sS http://localhost:3000/mcp \
+  -H "Authorization: Bearer $CREATIO_ACCESS_TOKEN" \
+  -H "X-Creatio-Base-Url: https://tenant-a.creatio.com" \
+  -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
+  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get-current-user-info","arguments":{}}}'
 ```
 
-### 3. OAuth2 Authorization Code
+> **Only the Bearer token is injected** — not arbitrary credentials. The gateway owns auth: it should
+> exchange whatever it holds (SSO, cookie, etc.) into a Creatio OAuth access token **before** calling
+> the MCP. (Injecting other credential shapes, e.g. cookie/basic per tenant, is intentionally out of
+> scope for now.)
 
-For user-delegated access with web authorization. [Setup guide →](https://academy.creatio.com/docs/8.x/dev/development-on-creatio-platform/integrations-and-api/authentication/oauth-2-0-authorization/authorization-code-grant)
+### `client_credentials` / `legacy`
 
 ```bash
-CREATIO_CODE_CLIENT_ID=your_client_id
-CREATIO_CODE_CLIENT_SECRET=your_client_secret
-CREATIO_CODE_REDIRECT_URI=http://localhost:3000/oauth/callback
-CREATIO_CODE_SCOPE="offline_access ApplicationAccess_yourappguid"
+CREATIO_CLIENT_ID=your_client_id          # client_credentials
+CREATIO_CLIENT_SECRET=your_client_secret
+
+CREATIO_LOGIN=YourLogin                   # legacy
+CREATIO_PASSWORD=YourPassword
 ```
 
-**Note**: Currently uses in-memory storage for OAuth tokens. Tokens will be lost on server restart.
+> **Precedence:** an explicit `CREATIO_MCP_AUTH_MODE` always wins. When unset, the mode is inferred:
+> legacy (login+password) → client_credentials (id+secret) → delegated. `broker`, `delegated` and
+> `gateway` require HTTP transport (stdio has no incoming web request to authenticate).
 
-**Important**: OAuth2 Authorization Code requires **Server Mode (`http`)**.
+---
 
-**Priority**: Authorization Code > Client Credentials > Legacy
+## Configuration
 
-## MCP Client Authentication (HTTP Mode)
+Grouped from essential to optional. **`CREATIO_BASE_URL` is the only always-required value** —
+nothing works without it; the rest depend on the auth method and the features you enable.
 
-The server includes OAuth 2.1 Authorization Server for MCP clients (Claude Desktop, etc.). No additional setup required - clients authenticate automatically through standard OAuth flow.
+### Connection (required)
 
-## Examples
+| Variable           | Description                                                          |
+| ------------------ | -------------------------------------------------------------------- |
+| `CREATIO_BASE_URL` | **Required.** Creatio instance URL (e.g. `https://your-creatio.com`) |
 
-### Node.js (Legacy Auth)
+### Authentication (pick one method — see [Authentication](#authentication))
 
-```bash
-export CREATIO_BASE_URL="https://your-creatio.com"
-export CREATIO_LOGIN="YourLogin"
-export CREATIO_PASSWORD="YourPassword"
-npm start
-```
+| Variable                             | Mode          | Description                                                                                                                                                                |
+| ------------------------------------ | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `CREATIO_MCP_AUTH_MODE`              | any           | `broker` \| `delegated` \| `gateway` \| `client_credentials` \| `legacy`. Unset ⇒ inferred (legacy → client_credentials → delegated)                                       |
+| `CREATIO_CLIENT_ID`                  | broker / M2M  | Creatio OAuth app client id (the brokered app, or the M2M account)                                                                                                         |
+| `CREATIO_CLIENT_SECRET`              | broker? / M2M | Required for client_credentials; optional for a confidential broker app (omit for public/PKCE)                                                                             |
+| `CREATIO_MCP_JWT_SECRET`             | broker        | Secret signing the tokens the MCP issues to clients. **Min 32 chars; required in production.** Random if unset outside prod (set a stable value for prod / multi-instance) |
+| `CREATIO_MCP_ALLOWED_BASE_URLS`      | gateway       | _Optional_ — comma-separated allowlist of Creatio origins the `X-Creatio-Base-Url` override may target (SSRF guard). Unset ⇒ any http(s) host except cloud-metadata        |
+| `CREATIO_LOGIN` / `CREATIO_PASSWORD` | legacy        | Username / password                                                                                                                                                        |
+| `CREATIO_ID_BASE_URL`                | any           | _Optional_ — Identity Service URL; defaults to deriving from `CREATIO_BASE_URL`                                                                                            |
 
-### Docker
+### Data & behavior (optional)
 
-The image supports both transports, selected by `MCP_TRANSPORT` (default `http`).
+| Variable                            | Description                                       |
+| ----------------------------------- | ------------------------------------------------- |
+| `CREATIO_MCP_CRUD_BACKEND`          | CRUD data API: `dataservice` (default) or `odata` |
+| `CREATIO_MCP_READONLY`              | `true` disables create/update/delete operations   |
+| `CREATIO_MCP_DISABLE_DATAFORGE`     | `true` skips the DataForge probe **and** tools    |
+| `CREATIO_MCP_DISABLE_GLOBAL_SEARCH` | `true` skips the Global Search probe **and** tool |
 
-**HTTP web service** (default — for remote/hosted/multi-client; required for the OAuth2
-authorization-code flow):
+### Transport & runtime (optional)
 
-```bash
-docker run --rm -p 3000:3000 \
-  -e CREATIO_BASE_URL="https://your-creatio.com" \
-  -e CREATIO_LOGIN="YourLogin" \
-  -e CREATIO_PASSWORD="YourPassword" \
-  crackish/mcp-creatio
-```
+| Variable                        | Description                                                                                                                                                                                                                                                                                        |
+| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `CREATIO_MCP_TRANSPORT`         | Docker only: `http` (default) or `stdio`                                                                                                                                                                                                                                                           |
+| `CREATIO_MCP_PORT`              | HTTP listen port (default `3000`; `PORT` also accepted)                                                                                                                                                                                                                                            |
+| `CREATIO_MCP_LOG_LEVEL`         | Log verbosity: `silent` (default), `error`, `warn`, `info`                                                                                                                                                                                                                                         |
+| `CREATIO_MCP_KEEPALIVE_SECONDS` | _Optional_ — proactive session keep-alive interval (seconds) for `legacy` / `client_credentials`, to avoid first-call re-login latency after an idle period. **Defaults to `300` (5 min)**; set `0` to disable. Keep it below the Creatio idle-session timeout                                     |
+| `CREATIO_MCP_PUBLIC_URL`        | _Optional_ — the deployment's public origin (e.g. `https://mcp.example.com`). Set it when behind a TLS-terminating proxy/ingress so the broker's issuer/audience, redirect URIs, and discovery metadata use the external URL (not the internal `http://host:port`). Defaults to the request origin |
 
-**stdio** (for a local client like Claude Desktop that spawns the process — note `-i`):
+> **Disabling optional capabilities.** DataForge and Global Search are auto-detected at startup and
+> registered only when supported. Set `CREATIO_MCP_DISABLE_DATAFORGE=true` /
+> `CREATIO_MCP_DISABLE_GLOBAL_SEARCH=true` to skip the probe and the tools — useful to keep the tool
+> surface small even when the capability exists.
 
-```bash
-docker run -i --rm \
-  -e MCP_TRANSPORT=stdio \
-  -e CREATIO_BASE_URL="https://your-creatio.com" \
-  -e CREATIO_LOGIN="YourLogin" \
-  -e CREATIO_PASSWORD="YourPassword" \
-  crackish/mcp-creatio
-```
+---
+
+## CRUD backend
 
-## Available Tools
+CRUD tools (`read`, `create`, `update`, `delete`, `list-entities`, `describe-entity`) run on a
+selectable data API, chosen once per deployment via `CREATIO_MCP_CRUD_BACKEND`:
+
+- **`dataservice`** (default) — Creatio's native DataService.
+- **`odata`** — Creatio OData v4. Also enables the OData-only `read` extras (raw `$filter`, `expand`).
+
+Either way you query through the same tool surface: prefer the structured `filters` parameter — it
+works unchanged on both backends.
+
+---
+
+## Tools
 
 | Tool                             | Description                                                                                                                                              |
 | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -249,22 +340,22 @@ docker run -i --rm \
 | `delete-admin-operation-grantee` | Remove specific grant rows by Id. Prefer `set-admin-operation-grantee` to flip allow ↔ deny                                                              |
 | `call-configuration-service`     | Escape hatch: invoke any configuration-package REST service method by name. Use only when no dedicated tool covers the operation                         |
 
-> **Note**: Previously documented `search`/`fetch` helper tools (for a specific connector workflow) have been removed as they are no longer required.
-
 ### Querying data with `read`
 
 Ask for exactly the data you need — the AI doesn't have to know OData:
 
-- **Filter any way** — equals / not-equals, ranges (`>`, `>=`, `<`, `<=`), text match (`contains`, `starts/ends with`), `AND` / `OR` groups, and "in this list".
-- **Filter by related records naturally** — by name (`Contact/Name = "Andrew Baker"`) or by id; lookups just work, no special syntax to remember.
-- **Sort** by any column, ascending or descending.
-- **Paginate** with page size + offset, so large datasets come back in clean pages.
-- **Count** — get the total number of matches in one call (e.g. "how many open cases does this account have?"), with or without the rows.
-- **Pull in related data** in a single request (e.g. an order together with its account and contact).
+- **Filter any way** — equals / not-equals, ranges, text match (`contains`, `starts/ends with`),
+  `AND` / `OR` groups, and "in this list".
+- **Filter by related records naturally** — by name (`Contact/Name = "Andrew Baker"`) or by id.
+- **Sort**, **paginate** (page size + offset), and **count** matches in one call.
+- **Pull in related data** in a single request (e.g. an order with its account and contact).
 
 ### DataForge tools (registered only when DataForge is enabled)
 
-DataForge is Creatio's AI-oriented semantic layer over the data model. These tools are **probed once at startup** and registered **only when the environment has DataForge configured** (a non-empty `DataForgeServiceUrl` system setting). When DataForge is absent the tools are not exposed at all, and `describe-entity` silently uses OData metadata — no wasted remote calls.
+DataForge is Creatio's AI-oriented semantic layer over the data model. These tools are **probed once**
+and registered **only when the environment has DataForge configured** (a non-empty
+`DataForgeServiceUrl` system setting). When DataForge is absent the tools are not exposed, and
+`describe-entity` silently uses OData metadata.
 
 | Tool                            | Description                                                                                       |
 | ------------------------------- | ------------------------------------------------------------------------------------------------- |
@@ -274,18 +365,51 @@ DataForge is Creatio's AI-oriented semantic layer over the data model. These too
 | `dataforge-lookup-values`       | Fuzzy/semantic search for lookup values (resolve a phrase to the right lookup record Id)          |
 | `dataforge-status`              | Report whether DataForge is online and whether the data model / lookups are synced                |
 
-**Discovery → confirm → act:** use `dataforge-similar-tables` to find the right entity, then `describe-entity` for the authoritative field list, then `read`/`create`.
+**Discovery → confirm → act:** use `dataforge-similar-tables` to find the right entity, then
+`describe-entity` for the authoritative field list, then `read`/`create`.
 
-**Enabling DataForge** requires (on the Creatio side): the `DataForgeServiceUrl` system setting plus IdentityServer settings (`IdentityServerUrl`, `IdentityServerClientId`/`Secret`), the `DataForge*` feature toggles, and the `CanReadDataStructureColumnDetails` operation granted to the MCP user. Restart the app pool (or run the `DataStructureTransferFromCreatio` / `LookupsTransferFromCreatio` processes) to sync the model.
+**Enabling DataForge** (Creatio side): the `DataForgeServiceUrl` system setting plus IdentityServer
+settings (`IdentityServerUrl`, `IdentityServerClientId`/`Secret`), the `DataForge*` feature toggles,
+and the `CanReadDataStructureColumnDetails` operation granted to the MCP user. Restart the app pool
+(or run `DataStructureTransferFromCreatio` / `LookupsTransferFromCreatio`) to sync the model.
 
 ### Global Search tool (registered only when Global Search is enabled)
 
-Global Search is Creatio's cross-entity, Elasticsearch-backed record search — the engine behind the UI search box. The tool is **probed once at startup** and registered **only when the environment has Global Search configured** (a non-empty `GlobalSearchUrl` system setting).
+Global Search is Creatio's cross-entity, Elasticsearch-backed record search — the engine behind the
+UI search box. Probed once, registered only when `GlobalSearchUrl` is configured.
 
-| Tool            | Description                                                                                                                                                                                                                                   |
-| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `global-search` | Full-text search across all indexed entities (like the UI search). Input: `query`, optional `entities[]`/`limit`/`from`. Returns matched records with `entityName`, `id`, `columnValues`, highlighted `foundColumns`, plus `total`/`nextFrom` |
+| Tool            | Description                                                                                                                                                                             |
+| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `global-search` | Full-text search across all indexed entities. Input: `query`, optional `entities[]`/`limit`/`from`. Returns matched records with `entityName`, `id`, `columnValues`, `total`/`nextFrom` |
 
-Differs from `read`: `read` needs an exact entity + OData filter; `global-search` is fuzzy and cross-entity — use it to locate a record when you don't know the entity. Calls `GlobalSearchService.Search`.
+Differs from `read`: `read` needs an exact entity + filter; `global-search` is fuzzy and
+cross-entity — use it to locate a record when you don't know the entity.
 
-**Enabling Global Search** requires the `GlobalSearchUrl` (+ `GlobalSearchConfigServiceUrl`, `GlobalSearchIndexingApiUrl`) system settings and the `GlobalSearch` / `GlobalSearch_V2` feature toggles, with the section index built (Elasticsearch reachable).
+**Enabling Global Search** requires the `GlobalSearchUrl` (+ `GlobalSearchConfigServiceUrl`,
+`GlobalSearchIndexingApiUrl`) system settings and the `GlobalSearch` / `GlobalSearch_V2` feature
+toggles, with the section index built (Elasticsearch reachable).
+
+---
+
+## Docker
+
+The image supports both transports, selected by `CREATIO_MCP_TRANSPORT` (default `http`).
+
+**HTTP** (remote / hosted / multi-client — defaults to delegated Bearer auth):
+
+```bash
+docker run --rm -p 3000:3000 \
+  -e CREATIO_BASE_URL="https://your-creatio.com" \
+  -e CREATIO_MCP_AUTH_MODE=delegated \
+  crackish/mcp-creatio
+```
+
+**stdio** (local client that spawns the process — note `-i`; use client-credentials or legacy auth):
+
+```bash
+docker run -i --rm \
+  -e CREATIO_MCP_TRANSPORT=stdio \
+  -e CREATIO_BASE_URL="https://your-creatio.com" \
+  -e CREATIO_LOGIN="YourLogin" -e CREATIO_PASSWORD="YourPassword" \
+  crackish/mcp-creatio
+```

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAUA,KAAK,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAMzC,wBAAgB,SAAS,IAAI,IAAI,CAwBhC;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU,CAoCpD;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAIlE;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI,CASlD"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAUA,KAAK,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAOzC,wBAAgB,SAAS,IAAI,IAAI,CAwBhC;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU,CAoCpD;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAIlE;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI,CASlD"}

package/dist/cli.js

@@ -83,13 +83,16 @@ function applyCliEnv(opts) {
     setEnvIfDefined('CREATIO_CLIENT_ID', opts['client-id']);
     setEnvIfDefined('CREATIO_CLIENT_SECRET', opts['client-secret']);
     setEnvIfDefined('CREATIO_ID_BASE_URL', opts['id-base-url']);
-    setEnvIfDefined('READONLY_MODE', opts.readonly);
-    setEnvIfDefined('MCP_CREATIO_LOG_LEVEL', opts['log-level']);
+    setEnvIfDefined('CREATIO_MCP_READONLY', opts.readonly);
+    setEnvIfDefined('CREATIO_MCP_LOG_LEVEL', opts['log-level']);
 }
 async function startStdio(server) {
-    const mcp = await server.startMcp();
+    const mcp = server.createSessionServer();
     const transport = new stdio_js_1.StdioServerTransport();
     await mcp.connect(transport);
+    // stdio uses a single-user provider (legacy/client_credentials) that carries its own
+    // credentials, so the probe needs no request context here.
+    server.ensureCapabilitiesProbed();
     log_1.default.info('stdio.server.start');
 }
 let shuttingDown = false;
@@ -100,7 +103,8 @@ async function shutdown(signal, state) {
     shuttingDown = true;
     log_1.default.appStop({ reason: signal || 'shutdown' });
     try {
-        await state.server?.stopMcp();
+        state.keepAlive?.stop();
+        await state.server?.stopAll();
     }
     catch (err) {
         log_1.default.error('shutdown.error', { error: String(err) });
@@ -113,20 +117,33 @@ async function main() {
         return;
     }
     log_1.default.useStderrOnlyLogs();
+    (0, server_1.installHttpAgent)();
     applyCliEnv(opts);
     const cfg = (0, config_builder_1.getCreatioClientConfig)();
-    if (cfg.auth.kind === creatio_1.AuthProviderType.OAuth2Code) {
-        throw new Error('oauth2_code_requires_http_server: use "npm start" (HTTP /mcp mode) for OAuth2 authorization-code flow');
+    // stdio is a single-process, single-user transport. The multi-user HTTP auth modes
+    // (delegated/gateway/broker) have no incoming web request to authenticate here.
+    if (cfg.auth.kind === creatio_1.AuthProviderType.OAuth2Bearer ||
+        cfg.auth.kind === creatio_1.AuthProviderType.Broker) {
+        throw new Error(`auth_mode_requires_http_server: CREATIO_MCP_AUTH_MODE=${cfg.auth.kind === creatio_1.AuthProviderType.Broker ? 'broker' : 'delegated/gateway'} needs the HTTP /mcp server — use "npm start". stdio supports client-credentials or legacy auth.`);
     }
     const provider = new creatio_1.CreatioServiceContext(cfg);
-    const readonlyMode = (0, utils_1.envBool)('READONLY_MODE', false);
+    const readonlyMode = (0, utils_1.envBool)('CREATIO_MCP_READONLY', false);
     const engines = new creatio_1.CreatioEngineManager(provider, { readonly: readonlyMode });
     const server = new server_1.Server(engines, {
         readonlyMode,
-        disableDataForge: (0, utils_1.envBool)('DISABLE_DATAFORGE', false),
-        disableGlobalSearch: (0, utils_1.envBool)('DISABLE_GLOBAL_SEARCH', false),
+        disableDataForge: (0, utils_1.envBool)('CREATIO_MCP_DISABLE_DATAFORGE', false),
+        disableGlobalSearch: (0, utils_1.envBool)('CREATIO_MCP_DISABLE_GLOBAL_SEARCH', false),
     });
-    const state = { server };
+    // Proactive keep-alive applies only to the single-session modes (legacy / client_credentials),
+    // which is exactly what stdio runs; it is opt-in via CREATIO_MCP_KEEPALIVE_SECONDS.
+    const keepAlive = new server_1.SessionKeepAlive((0, server_1.keepAliveIntervalMs)(), async () => {
+        await engines.user.getCurrentUserInfo();
+        // Reuse the periodic ping to also refresh the schema-freshness snapshot, so it isn't a
+        // wasted round-trip — the next schema read starts from a warm, validated cache.
+        await engines.warmSchemaCache();
+    });
+    keepAlive.start();
+    const state = { server, keepAlive };
     process.on('SIGINT', () => {
         void shutdown('SIGINT', state).finally(() => process.exit(0));
     });