Skip to content

MCP Server Configuration

The server is configured with environment variables, set in the assistant’s MCP configuration (its env), or in a file whose full path UMBSOCIAL_ENV_FILE gives. It never reads a .env file from the folder it starts in, which is usually your project: an assistant that can write files there could otherwise change the server’s settings.

Variable Meaning
UMBRACO_BASE_URL The site’s address, such as https://www.example.com. It must use https; plain http is allowed only for localhost, 127.0.0.1 and [::1]. It can’t contain a user name or password.
UMBRACO_CLIENT_ID The API user’s client ID.
UMBRACO_CLIENT_SECRET The API user’s client secret.

If one is missing or invalid, the server stops at once with a message naming the variable. The message never contains the value.

Variable Meaning
UMBSOCIAL_ENV_FILE The full path of a file holding these variables, read when the server starts. The file’s values win over the same variables set in env. Keep it outside your project folder.
UMBSOCIAL_ENABLE_SLICES Turns on tools that are off by default: approve, resolve or both, separated by commas. Any other name stops the server.
DISABLE_MCP_CHAINING true to leave out the chained CMS server and its cms-- tools.
UMBRACO_EXPECTED_MAJOR The Umbraco major version the server expects, 17 unless set. When the site runs another major, the first tool call is held back with a warning; calling it again goes ahead.

When it starts, the server reads the API user and the site’s edition, then registers a tool only when all of these hold:

  1. The UmbSocial section. Without it, only get-social-edition is registered, and it says how to fix that.
  2. A permission that can use it. Each tool needs one of the UmbSocial permissions listed for it in MCP tools. A tool the API user’s group can’t use isn’t registered.
  3. The edition. Pro’s tools are registered only when the site’s UmbSocial Pro licence is valid.
  4. Its slice is on. approve and resolve are off unless UMBSOCIAL_ENABLE_SLICES names them.
  5. The filters below allow it.

The server reads these once. Restart the assistant after changing the API user’s group, the licence or a setting.

The site checks every call again, whatever the server registered.

The server uses the filters of Umbraco’s MCP server SDK.

  • Modes group the tools: social (every site) and social-pro (UmbSocial Pro). Both are on unless UMBRACO_TOOL_MODES names one.
  • Slices say what a tool does: read, list, create, update, delete, and UmbSocial’s own approve and resolve. MCP tools gives each tool’s slice.
Variable Meaning
UMBRACO_TOOL_MODES Only these modes, such as social.
UMBRACO_INCLUDE_TOOL_COLLECTIONS, UMBRACO_EXCLUDE_TOOL_COLLECTIONS Only, or every but, these collections: social, social-pro.
UMBRACO_INCLUDE_SLICES Only tools in these slices, such as read,list. It can’t turn on approve or resolve.
UMBRACO_EXCLUDE_SLICES Leave out tools in these slices, such as delete.
UMBRACO_INCLUDE_TOOLS Only these tools, by name. A tool in approve or resolve still needs UMBSOCIAL_ENABLE_SLICES.
UMBRACO_EXCLUDE_TOOLS Leave out these tools, by name.
UMBRACO_READONLY true for only the tools that read: nothing is created, changed or deleted.

Every list is separated by commas. The filters can only take tools away: none of them gives the API user a tool its permissions don’t allow.

For example, to let an assistant read the calendar and write drafts, but not delete them:

"env": {
"UMBRACO_BASE_URL": "https://www.example.com",
"UMBRACO_CLIENT_ID": "umbraco-back-office-social-assistant",
"UMBRACO_CLIENT_SECRET": "${UMBSOCIAL_CLIENT_SECRET}",
"UMBRACO_EXCLUDE_SLICES": "delete"
}

Two slices are off until UMBSOCIAL_ENABLE_SLICES names them, even for an API user with the permission:

Slice Tools Permission Why it is off
approve approve-post, return-post (Pro) Approve Approving is a person’s review: it puts a post on the calendar, and Now publishes it at once. The site refuses an API user approving a post written with AI, and every post an API user writes counts as that, so this can only approve a post a person wrote. Review in the backoffice instead (Approvals).
resolve retry-post-target, mark-post-target-published Resolve Both act on live networks. Retrying a channel whose post did go out posts it twice, and marking a channel as published tells your webhooks and handlers that it is live. Only someone who has checked the network should decide either.

Turn one on only for a trusted person’s own API user, and only if they want their assistant to do it.

approve-post, retry-post-target, mark-post-target-published and delete-post are marked destructive. When the assistant’s client can ask, they ask the person to confirm first. When it can’t, they run only with confirm: true, which the assistant should pass only after the person has said yes; otherwise they’re refused with confirmation.required.

A host that loads the server’s tools in process (@umbhost/umbsocial-mcp/collections) gets the same rule: the approve and resolve tools are left out unless UMBSOCIAL_ENABLE_SLICES names their slice.

Posts refer to Umbraco images and pages by key. To find those keys, the server starts Umbraco’s own CMS Developer MCP beside it, with the same API user, and adds its tools with a cms-- prefix:

  • media: cms--get-media-root, cms--get-media-children, cms--get-collection-media and cms--get-media-by-id;
  • pages: cms--search-document, cms--get-document-root, cms--get-document-children and cms--get-item-document.

It runs read-only and sees only the API user’s start nodes. The server registers only those eight tools, whatever the CMS Developer MCP lists, and logs the name of any other tool it leaves out. The filters above don’t apply to it. It is a dependency of the server, pinned to an exact version, and the server’s published npm-shrinkwrap.json fixes every package beneath it, so you install the versions the release was tested with. It runs with Node.js from where it was installed: nothing is downloaded when the server starts. If it can’t start, the UmbSocial tools still work.

DISABLE_MCP_CHAINING=true leaves it out. The assistant then needs image and page keys from you.

Variable Meaning
NODE_EXTRA_CA_CERTS A certificate (PEM) for Node.js to trust, such as a local site’s development certificate.
NODE_OPTIONS=--use-system-ca Trust the certificates your operating system trusts. Needs Node.js 22.15 or later.

Never set NODE_TLS_REJECT_UNAUTHORIZED=0. See A local site with a self-signed certificate.