> For the complete documentation index, see [llms.txt](https://docs.umbraco.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.umbraco.com/umbraco-in-ai/mcp/setup-a-hosted-mcp-server/self-hosted-quickstart.md).

# Self-Hosted Quick Start

Deploy any Umbraco MCP server — pre-built or your own — to your own Cloudflare account, step by step.

This guide deploys an Umbraco MCP server to your own Cloudflare account and connects it to your Umbraco site. It works for any Umbraco MCP Worker — a pre-built Editor or Developer MCP server, or a custom server you've built yourself.

It uses the Editor MCP as the running example.

{% hint style="info" %}
Deploying the Developer MCP instead? Clone [`umbraco/Umbraco-CMS-MCP-Dev`](https://github.com/umbraco/Umbraco-CMS-MCP-Dev) in step 1 and use a different `ClientId` in step 5. Deploying your own custom MCP server? Clone your own repository in step 1 instead — everything else here still applies.
{% endhint %}

## Prerequisites

* Node.js 22+
* A [Cloudflare account](https://dash.cloudflare.com/sign-up)
* The [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/install-and-update/), logged in (`npx wrangler login`)
* Admin access to your Umbraco project's source code (Umbraco 18.x)

## 1. Get the Source

Clone the Editor MCP repository and install its dependencies. Deploying a different server? Clone that repository instead — see the hint above.

```bash
git clone https://github.com/umbraco/Umbraco-CMS-MCP-Editor.git
cd Umbraco-CMS-MCP-Editor
npm install
```

## 2. Create a KV Namespace

The Worker stores OAuth tokens in a Cloudflare KV namespace:

```bash
npx wrangler kv namespace create OAUTH_KV
```

Copy the returned namespace ID into `wrangler.toml`:

```toml
[[kv_namespaces]]
binding = "OAUTH_KV"
id = "YOUR_KV_NAMESPACE_ID"
```

{% hint style="warning" %}
Only replace `YOUR_KV_NAMESPACE_ID`. Leave `binding = "OAUTH_KV"` exactly as it is — the Worker code reads this KV namespace as `env.OAUTH_KV`, so renaming the binding breaks token storage.
{% endhint %}

## 3. Set Secrets

```bash
npx wrangler secret put UMBRACO_BASE_URL
# e.g. https://my-umbraco.example.com

npx wrangler secret put UMBRACO_OAUTH_CLIENT_ID
# Pick any value, e.g. umbraco-cms-editor-mcp-hosted — you'll reuse it in step 5

npx wrangler secret put COOKIE_ENCRYPTION_KEY
# Generate with: openssl rand -hex 32
```

{% hint style="info" %}
No client secret is needed. The OAuth client registered by `Umbraco.Mcp.HostedAuth` in step 5 is a **public** client using PKCE.
{% endhint %}

{% hint style="info" %}
This guide connects one Worker to one Umbraco site (`UMBRACO_BASE_URL` above). Want one Worker to serve multiple Umbraco instances instead? See [Multi-Site Deployments](https://docs.umbraco.com/umbraco-in-ai/mcp/custom-mcp-server/hosted-mcp/deployment/multi-site.md).
{% endhint %}

## 4. Deploy

```bash
npx wrangler deploy
```

Note the Worker's URL from the deploy output, for example `https://my-umbraco-mcp.<your-subdomain>.workers.dev`.

## 5. Wire It Into Umbraco

Install [`Umbraco.Mcp.HostedAuth`](https://www.nuget.org/packages/Umbraco.Mcp.HostedAuth) in your Umbraco project. The package is versioned to match your Umbraco major, so pin it to the `18.x` line:

```bash
dotnet add package Umbraco.Mcp.HostedAuth --version "18.*"
```

List the Worker under `HostedMcp:Clients` in `appsettings.json`:

```jsonc
{
  "HostedMcp": {
    "Clients": [
      {
        "ClientId": "umbraco-cms-editor-mcp-hosted", // must match step 3
        "Origins": [ "https://my-umbraco-mcp.<your-subdomain>.workers.dev" ]
      }
    ]
  }
}
```

Restart Umbraco. The package detects there's no `umbraco-cloud.json` file and resolves to **self-hosted mode** automatically. It registers the OAuth client on startup — no `Mode` setting needed unless you want to force it explicitly.

## 6. Verify the Connection

1. Visit your Worker's URL in a browser — you should see the landing page.
2. Connect an MCP client using that URL — see the [Setup Guides](https://docs.umbraco.com/umbraco-in-ai/mcp/connect-to-an-mcp-server/hosted-mcp-setup.md#setup-guides).
3. The client should trigger the OAuth flow: consent screen, then Umbraco login, then connected.

## Beyond the Quick Start

This guide covers the imperative `wrangler` path to a single environment. For a custom domain, multiple environments, tool filtering, or a repeatable Infrastructure as Code setup, see:

* [Deployment](https://docs.umbraco.com/umbraco-in-ai/mcp/custom-mcp-server/hosted-mcp/deployment.md) — custom domains, environment-specific config, monitoring.
* [Infrastructure as Code](https://docs.umbraco.com/umbraco-in-ai/mcp/custom-mcp-server/hosted-mcp/deployment/infrastructure-as-code.md) — provision with OpenTofu or Terraform.

These guides describe building a custom MCP server from the SDK, but the same Worker mechanics — KV, secrets, deployment — apply here too.

## Troubleshooting

See [Hosted MCP Troubleshooting](https://docs.umbraco.com/umbraco-in-ai/mcp/custom-mcp-server/hosted-mcp/troubleshooting.md) for common connection and deployment errors.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.umbraco.com/umbraco-in-ai/mcp/setup-a-hosted-mcp-server/self-hosted-quickstart.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
