> 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/17.latest/mcp/base-mcp/hosted-mcp.md).

# Hosted MCP Server

The `@umbraco-cms/mcp-hosted` package enables AI assistants to access your Umbraco instance remotely via the Model Context Protocol (MCP) over Streamable HTTP transport. Users authenticate as backoffice users through OAuth. No API keys or API users are required.

## Local vs Hosted

**Local (stdio)** runs the MCP server on the developer's machine and communicates via stdin/stdout. This is suited to local development.

**Hosted (Cloudflare Workers)** runs the MCP server on the edge and communicates via HTTP. This enables team-wide access, remote AI assistants, and production deployments.

Both modes use the same tool collections. No code changes are required.

## Key Concepts

### Streamable HTTP

The MCP transport protocol used for hosted servers. Unlike stdio (stdin/stdout for local tools), Streamable HTTP sends MCP messages over standard HTTP requests. This enables remote access.

### Three-Tier Configuration

Tool availability is controlled by three layers. Each layer narrows the one above:

* **Admin** (env vars) sets the maximum boundary, managed by DevOps.
* **Operator** (worker.ts code) defines what is available, managed by the developer.
* **User** (consent screen) defines what they get, chosen at authorization time.

### Per-Request Server

Each MCP request creates a fresh `McpServer` instance. No state is shared between requests or clients.

## Prerequisites

* A [Cloudflare account](https://dash.cloudflare.com/sign-up)
* The [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/install-and-update/) (`npm install -g wrangler`)
* An Umbraco instance with Management API enabled
* An OAuth client registered in the Umbraco instance (see [Umbraco Setup](/umbraco-in-ai/17.latest/mcp/base-mcp/hosted-mcp/umbraco-setup.md))

## Getting Set Up

The [`create-umbraco-mcp-server`](/umbraco-in-ai/17.latest/mcp/base-mcp/create-umbraco-mcp-server.md) CLI generates the Worker entry point, `wrangler.toml`, and deployment scripts for you. See the [Development Workflow](/umbraco-in-ai/17.latest/mcp/base-mcp/create-umbraco-mcp-server/development-workflow.md) to get started.

For manual setup or to understand what the generated code does, see [Manual Setup](/umbraco-in-ai/17.latest/mcp/base-mcp/hosted-mcp/manual-setup.md).

## Routes

The Worker serves the following routes:

| Path         | Purpose                                                                  |
| ------------ | ------------------------------------------------------------------------ |
| `/`          | MCP endpoint (Streamable HTTP). Browser visits display the landing page. |
| `/authorize` | OAuth consent screen and redirect to Umbraco.                            |
| `/callback`  | Token exchange after Umbraco login.                                      |
| `/info`      | Diagnostic JSON endpoint (requires `ENABLE_INFO_ENDPOINT=true`).         |

When a browser visits `/` with no auth header, the Worker serves a landing page with server information. MCP clients send requests to `/` using POST or GET+SSE with authentication, and these are routed to the MCP protocol handler.

## Features

### Consent Screen with Tool Selection

Enable tool selection on the consent screen so users can choose which tool modes they want:

```typescript
const options = {
  name: "my-umbraco-mcp",
  version: "1.0.0",
  collections: [myCollection],
  modeRegistry: allModes,
  allModeNames,
  allSliceNames,
  enableConsentToolSelection: true, // Shows mode checkboxes + read-only toggle
};
```

See [Architecture - Three-Tier Configuration](/umbraco-in-ai/17.latest/mcp/base-mcp/hosted-mcp/architecture.md#three-tier-configuration) for how admin, operator, and user configurations interact.

### Multi-Site Support

A single Worker can serve multiple Umbraco instances. All sites share one MCP endpoint (`/`). Site selection happens during authorization via the consent screen's site picker.

See [Multi-Site Deployments](/umbraco-in-ai/17.latest/mcp/base-mcp/hosted-mcp/multi-site.md) for setup instructions, route structure, and security details.

## Documentation

### Getting Started

Read these articles in order:

1. [Umbraco Setup](/umbraco-in-ai/17.latest/mcp/base-mcp/hosted-mcp/umbraco-setup.md) - Register the Worker as an OAuth client (one-time).
2. [Deployment](/umbraco-in-ai/17.latest/mcp/base-mcp/hosted-mcp/deployment.md) - Deploy, set secrets, and verify the connection.
3. [Manual Setup](/umbraco-in-ai/17.latest/mcp/base-mcp/hosted-mcp/manual-setup.md) - Worker entry point, wrangler.toml, and secrets (reference).

### Guides

4. [Customization](/umbraco-in-ai/17.latest/mcp/base-mcp/hosted-mcp/customization.md) - Consent screen tool selection, branding, and custom rendering.
5. [Multi-Site Deployments](/umbraco-in-ai/17.latest/mcp/base-mcp/hosted-mcp/multi-site.md) - Serve multiple Umbraco instances from one Worker.

### Understanding the System

6. [Architecture](/umbraco-in-ai/17.latest/mcp/base-mcp/hosted-mcp/architecture.md) - Auth flow, three-tier configuration, component diagram.
7. [Security](/umbraco-in-ai/17.latest/mcp/base-mcp/hosted-mcp/security.md) - Token isolation, consent, CSRF protection, MCP spec compliance.

### Reference

8. [API Reference](/umbraco-in-ai/17.latest/mcp/base-mcp/hosted-mcp/api-reference.md) - All exports, types, and interfaces.
9. [Troubleshooting](/umbraco-in-ai/17.latest/mcp/base-mcp/hosted-mcp/troubleshooting.md) - Common errors and fixes.


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.umbraco.com/umbraco-in-ai/17.latest/mcp/base-mcp/hosted-mcp.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.