Local stdio setup
Use Node.js 24.11.1 or later. Install the CLI in the host project before using itsmdcms binary through npx:
mdcms.config.ts. Configure a stdio-capable agent to launch:
--config with the config location. Server, project and environment resolve from CLI flags, then MDCMS_SERVER_URL, MDCMS_PROJECT, MDCMS_ENVIRONMENT, then config. API keys resolve from --api-key, then MDCMS_API_KEY, then the stored login profile for that server/project/environment. The CLI loads .env* before config; existing shell variables win. Use --no-env-file to disable this. Keep credentials out of committed agent configuration.
The bridge fixes its connection at startup. Restart it to change server, project, environment or credentials. It relays the 27-tool remote catalog and adds two local tools. sync_schema reloads local config and imported modules and syncs the schema to that fixed target. get_credentials_info reads capabilities for the fixed target and reports capability-derived scopes, publishing-key guidance, and scope requirements for common content/schema tools. Its allowed flags do not guarantee path access or describe the complete remote inventory; remote discovery and execution remain authoritative. These two local tools are unavailable through remote MCP alone. stdout carries protocol messages; diagnostics use stderr. Closing stdin stops the bridge.
Remote OAuth setup
In an agent supporting Streamable HTTP and OAuth, add your server endpoint, for example:Authorization: Bearer <api-key>, X-MDCMS-Project and X-MDCMS-Environment explicitly. Keep keys in a secret store. Every call remains constrained by credential scopes and the user’s current grants.
Read, edit and publish
- Call
get_schemaand inspect the content type and returnedschemaHash. - Read the document with
get_documentbefore editing. - Pass that exact hash to
create_document,update_document,duplicate_documentorcreate_translation. For example:
content:read:draft. Draft writing requires content:write; creation and update also require schema access. Publishing and unpublishing require the separate content:publish scope. Writing a draft does not publish it. Restore defaults to draft; restoring to published also requires publish permission.
create_document requires an explicit locale. Use a configured locale for localized types and __mdcms_default__ for non-localized types. The server does not infer a locale from the signed-in user.
After server-side changes, run npx mdcms pull to refresh local files. For schema changes, edit local config, run sync_schema (or npx mdcms schema sync), then read and explicitly acknowledge the new hash before writing.
Remote tools
Discovery returns only tools available to your credential and current permissions. The remote catalog contains these 27 tools:upload_media accepts filename, mimeType and canonical base64, with a decoded limit of 10 MiB or the configured media limit, whichever is lower. It cannot fetch a URL or read a local file. Media type and storage validation still apply.
list_environments requires an issued environments:read scope and current global Admin/Owner privileges. Request that scope when issuing an API key or during OAuth consent; a project Admin role alone is insufficient. It lists visible environment metadata only in the authenticated project. Discovery does not grant access to another environment’s content or change the connection target.
Clone and promote check both source and destination permissions. API-key context allowlists must include both project/environment tuples. With OAuth, the destination must equal the connection’s fixed target, and the granting user must still have source permissions. Clone with content needs source content:read and schema:read, plus content:read:draft when copying drafts. Settings copy requires source schema:read and destination schema:write. Promote always requires source content:read:draft and schema:read, including published-only promotion.
Attribution and recovery
MDCMS records the authenticated actor and verified MCP channel. App names are reported, unverified metadata, never proof of identity or permission. Remote clients can repeat{name, version} in each tool call’s params._meta["ai.mdcms/clientInfo"]. An initialize name alone does not carry over to later stateless requests. The local bridge forwards its downstream client’s reported identity per call.
A transport failure can leave a mutation’s outcome unknown. Inspect server state before retrying. Tool failures return
isError: true with a code, message and status; do not treat a received protocol response as proof that a write succeeded.
Client configuration varies by host. SDK, browser and packed Node checks do not establish compatibility with a particular ChatGPT or Claude host version; validate read, write and permission-denial behavior in your chosen host before relying on it.