crackish/mcp-creatio repository overview

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

⁠Contents

• What it does⁠
• Quick start⁠
• Authentication⁠
• Configuration⁠
• CRUD backend⁠
• Tools⁠
• Docker⁠

⁠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 — 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.

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",
		],
	},
}

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

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

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.

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

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

⁠client_credentials / legacy

CREATIO_CLIENT_ID=your_client_id          # client_credentials
CREATIO_CLIENT_SECRET=your_client_secret

CREATIO_LOGIN=YourLogin                   # legacy
CREATIO_PASSWORD=YourPassword

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

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

⁠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, te