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.
Required
Section titled “Required”| 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.
UmbSocial’s settings
Section titled “UmbSocial’s settings”| 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. |
Which tools are registered
Section titled “Which tools are registered”When it starts, the server reads the API user and the site’s edition, then registers a tool only when all of these hold:
- The UmbSocial section. Without it, only
get-social-editionis registered, and it says how to fix that. - 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.
- The edition. Pro’s tools are registered only when the site’s UmbSocial Pro licence is valid.
- Its slice is on.
approveandresolveare off unlessUMBSOCIAL_ENABLE_SLICESnames them. - 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.
Modes, slices and filters
Section titled “Modes, slices and filters”The server uses the filters of Umbraco’s MCP server SDK.
- Modes group the tools:
social(every site) andsocial-pro(UmbSocial Pro). Both are on unlessUMBRACO_TOOL_MODESnames one. - Slices say what a tool does:
read,list,create,update,delete, and UmbSocial’s ownapproveandresolve. 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"}Tools that are off by default
Section titled “Tools that are off by default”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.
The chained CMS server
Section titled “The chained CMS server”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-mediaandcms--get-media-by-id; - pages:
cms--search-document,cms--get-document-root,cms--get-document-childrenandcms--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.
Other settings
Section titled “Other settings”| 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.