MCP Creatio Server

Model Context Protocol (MCP) server for Creatio — connect Claude Desktop, ChatGPT, GitHub Copilot, and other AI tools to your Creatio data, schema, and processes.

Also discoverable as: Creatio MCP server · MCP server for Creatio CRM · Model Context Protocol for Creatio.

Contents

• What it does

• Quick start

• Authentication

• Configuration

• CRUD backend

• Tools

• Docker

Related MCP server: Microsoft Business Central MCP Server

What it does

• 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 — list, inspect and switch features from every source (DB, web.config, metadata, GlobalAppSettings), by default or per user/role, like the Creatio feature page (DataService backend). On the OData backend only DB-backed Feature rows are reachable.

• 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.

Works with Claude Desktop, ChatGPT Connectors, GitHub Copilot, and any MCP-compatible client.

Quick start

The server runs in one of two transports. Pick by how your client connects, then pick an authentication method.

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.

npx -y mcp-creatio@latest \
  --base-url https://your-creatio.com \
  --login your_login --password your_password

// VS Code / Claude Desktop (command-based)
{
	"creatio": {
		"command": "npx",
		"args": [
			"-y",
			"mcp-creatio@latest",
			"--base-url",
			"https://your-creatio.com",
			"--login",
			"your_login",
			"--password",
			"your_password",
		],
	},
}

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).

npm start                     # serves http://localhost:3000/mcp

{ "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.

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.

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.

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)

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.

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.

OAuth scope (older Creatio versions)

If the login succeeds but every tool call (e.g. get-current-user-info) returns 401, your Creatio predates the AddApplicationAccessScopeAutomatically feature: tokens are only usable when the request explicitly asks for the app's resource scope. Find it in the OAuth resource lookup (ApplicationAccess_<id>) and set:

CREATIO_OAUTH_SCOPE=ApplicationAccess_<id>   # space/comma-separated; offline_access is always added

It applies to every OAuth mode: broker requests it on login and refresh, delegated advertises it in its RFC 9728 metadata (so the client requests it), and client_credentials sends it on the token request. An invalid scope value fails at startup.

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:

{
	"creatio": {
		"type": "http",
		"url": "http://localhost:3000/mcp",
		"headers": { "Authorization": "Bearer <CREATIO_ACCESS_TOKEN>" },
	},
}

Server side, just select the mode (no credentials needed):

CREATIO_MCP_AUTH_MODE=delegated
CREATIO_BASE_URL=https://your-creatio.com

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.

Forwarding a Creatio session cookie instead of a Bearer. A client that authenticated to Creatio the classic way holds a Forms-auth session (cookie + BPMCSRF), not an OAuth token. It can forward that session instead of a Bearer by sending the cookie in X-Creatio-Cookie (and, optionally, the anti-forgery token in X-Creatio-Bpmcsrf — otherwise it is read from the cookie). The MCP attaches Cookie + BPMCSRF + ForceUseSession statelessly and lets Creatio validate it. Authorization: Bearer takes precedence when both are present.

gateway

A trusted fronting service (Creatio.ai Control-Plane) injects the credential; 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 credential 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).

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 a Creatio credential — either a Bearer token, or a forwarded Forms-auth session:

POST /mcp HTTP/1.1
Authorization: Bearer <CREATIO_ACCESS_TOKEN>     # a Bearer token …
X-Creatio-Cookie: BPMCSRF=<csrf>; .ASPXAUTH=<s>   # … OR forward a Forms-auth session instead
X-Creatio-Base-Url: https://tenant-a.creatio.com  # optional — pick the tenant's instance (multi-tenant)

Server side:

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

Smoke-test it directly with curl (mint a token out-of-band first):

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":{}}}'

Bearer or session cookie — nothing else. The gateway injects either a Creatio OAuth Bearer token or a forwarded Forms-auth session (X-Creatio-Cookie + BPMCSRF); the MCP forwards it statelessly (no cookie jar, no per-credential pool) and Creatio validates it. The gateway owns auth — it should hold a ready Creatio credential of one of those two shapes. Other shapes (Basic, API key) are intentionally out of scope.

Per-tenant tool isolation. A single MCP deployment serving many instances keeps each tenant's tool surface separate, keyed by the effective base URL (X-Creatio-Base-Url, else CREATIO_BASE_URL). Optional capabilities are probed per tenant and the tools they expose (DataForge, Global Search, and any dynamically discovered per-instance tools) are registered only for the tenant they were discovered on. Tenant A's tools or DataForge verdict never leak into tenant B's session, even though both share one process. The per-tenant state is pooled with idle-TTL + LRU eviction, so memory stays bounded as the number of distinct instances grows. Single-tenant modes (everything except gateway with an override) all map to one bucket, so their behavior is unchanged.

client_credentials / legacy

CREATIO_CLIENT_ID=your_client_id          # client_credentials
CREATIO_CLIENT_SECRET=your_client_secret

CREATIO_LOGIN=YourLogin                   # legacy
CREATIO_PASSWORD=YourPassword

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).

Configuration

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.

Connection (required)

Authentication (pick one method — see Authentication)

Data & behavior (optional)

Transport & runtime (optional)

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.

CRUD backend

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.

Dates and time zones

Record dates work in the user's Creatio time zone, exactly as the Creatio UI shows them, on both backends. A date/time is read as that zone's wall clock labelled with its offset ("2026-11-10T15:00:00+02:00"); a value sent without an offset ("2026-11-10T15:00:00") means that wall clock, and one with Z or an offset is that exact instant. Date columns (BirthDate) read and write as YYYY-MM-DD and are never shifted. The zone comes from the user's Creatio profile (daylight saving is applied per date), get-current-user-info returns it as timeZone / utcOffset, and the server tells the model this on connect (MCP instructions).

Tools

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.

• 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).

• Readable results — an empty value is null, a lookup reads as { value, displayValue }, and a mistyped entity or column comes back with "Did you mean …?".

Guidance for the model. On connect the server sends MCP instructions (the date contract, which id a person field takes, when to confirm, which guide to read). The guides — querying, creating activities, dates, people, tagging, system settings, feature toggles, system operations — are both prompts the user can invoke (/query-guide, …) and a get-guide tool the model calls itself (most clients never let the model open prompts). Every tool also carries MCP annotations (read-only / destructive / idempotent) so clients can run reads without asking and confirm destructive calls.

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 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 uses the active backend's schema.

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 (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. Probed once, registered only when GlobalSearchUrl is configured.

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).

Docker

The image supports both transports, selected by CREATIO_MCP_TRANSPORT (default http).

HTTP (remote / hosted / multi-client — defaults to delegated Bearer auth):

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):

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