mcp-fetch-worker

Универсальный MCP-коннектор для ботов и агентов, которым нужно вызывать ваши self-hosted API, не передавая им долгоживущие учётные данные.

Поместите Cloudflare Access перед этим Worker с включённым Managed OAuth, и боты вроде Grok Bot или OpenClaw смогут подключаться через Dynamic Client Registration (DCR). Вы одобряете доступ при первом подключен бота и можете отозвать его в любой моментего из Access. Бот получает ограниченный токен, связанный с коннектором, а не общий API-ключ, который можно использовать где-то ещё.

Production MCP URL: https://<your-domain>/mcp

Зачем это нужно

Управлямые боты хорошо работают с вызовами инструментов, но большинство homelab- и self-hosted-приложений не имеют встроенного MCP-сервера. Можно было бы:

• Использовать сервисные токены: постоянный доступ через пользовательские заголовки. Нормально для скриптов; рискованно для ботов, которым вы не полностью доверяете.

• Дать боту Chrome: он открывает вашь веб-интерфейс, вы проходите SSO, и так каждыйраз. Работает, но сжигает токены and не масштабируется.

• Создавать MCP-сервер для каждо приложения: правильно, но для Home Assistant API или случайного внутреннегодашборда это слишком много работы.

Этот Worker — середина пути: тонкий MCP-коннектор, который предоставляет один-единственный инструмент http_fetch. Укажите его на API того же оригисходящего (уже за Access), и бот сможет делатGET/POST-запросы с одобренным вами OAuth-токеном. На другой стороне не нужен отдельный MCP-сервер.

Подробное описание — в стате First World Problem: How do I grant my bots access to my stuff without it wrecking everything?.

Related MCP server: ToolBridge

Как это работает

Bot (Grok Bot, OpenClaw, Cursor, …)
  → OAuth via Cloudflare Access Managed OAuth (you approve)
  → MCP at /mcp (this Worker)
  → http_fetch to allowed origins on your domain
  → Access JWT forwarded on outbound requests

1. Access обрабатвает аутентифкацию: Managed OAuth + DCR. Этот Worker не являето OAuth-серверам; он проверяет Cf-Acess-Jwt-Assertion, который передаёт Access.

2. Этот Worker предоставляет Streamable HTTP MCP с одним инструментом: http_fetch.

3. Ваши API находяться на той же origin и стоят за Access. Создайте политики Linked App Token, чтобы передаваемый JWT принимался ниже по цепочке.

Исходящие запросы по умолчанию ограничены origin самого Worker (ALLOWED_ORIGINS переопределяет это).

Что он делает

• Предоставляет MCP на /mcp (и /sse как устаревший алиас) через Agents SDK createMcpHandler

• Раскрывает один инструмент, http_fetch, для GET/POST-запросов к разрешённым origins

• Проверяет Cf-Access-Jwt-Assertion против JWKS вашей команды, когда заданы CF_ACCESS_TEAM_DOMAIN и CF_ACCESS_AUD

• Передаёт токен доступа вызывающего на исходящих запросах (Cf-Access-Jwt-Assertion, Cf-Access-Token, Authorization: Bearer)

Деплой

npm install
npm run cf-typegen   # regenerate Env types from wrangler.jsonc
npx wrangler deploy

Конфигурация находится в wrangler.jsonc. Журналы Workers Logs и трассировки включены по умолчанию через блок observability.

Кастомный домен (Custom domain route)

Добавьте route Worker в wrangler.jsonc (или в панели управления):

"routes": [
  {
    "pattern": "example.com/mcp*",
    "zone_name": "example.com"
  }
]

Затем передеплойте. MCP-эндпойн — https://<иоur-domain>/mcp.

Convenient environment variables

Задайте в wrangler.jsonc vars, в качестве secrets (wrangler secret put), или в .dev.vars — в .dev для локальной разработки. см. .dev.vars.example):

Когда CF_ACCESS_* не заданы, Worker продолжаer обслуживать MCP (полезно для wrangler dev), но не проверяет Access JWT. В проде задайте обе переменные.

Стандартные заголовки для API-ключей

Храните дополнительные исходящие заголовки как секрет Worker, чтобы http_fetch мог вызывать API, требования ключ, не передавая секреты в чат и не зашивая один API в Worker:

wrangler secret put DEFAULT_HEADERS
# paste: {"X-Api-Key":"your-key-here"}

Для локальной разработки задайте непустое значение в wrangler.jsonc vars, передайте --var DEFAULT_HEADERS='{"X-Api-Key":"..."}' в wrangler dev или используйте wrangler secret put на задеплоенном Worker. Когда настроено secrets.required, .dev.vars загружает только указанные имена секретов, поэтому поместите DEFAULT_HEADERS в vars или используйте --var локально.

DEFAULT_HEADERS должен быть JSON-объектом со строковыми значениями, например {"X-Api-Key":"..."}. При каждом вызове http_fetch эти заголовки объединяются с исходящим запросом. Заголовки из tool-вызова переопределяют значения по умолчанию при конфликте имен. Передача JWT Access (Cf-Access-Jwt-Assertion, Cf-Access-Token, Authorization) всегда приоритетна и не может быть переопределена значениями по умолчанию.

Пустой или не заданный DEFAULT_HEADERS не добавляет никаких заголовков.

Настройка Cloudflare Access

1. Добавьте self-hosted приложение Access для вашего MCP URL (например, https://<егоome>/mcp или путь, покрывающий /mcp*)

2. Включите Managed OAuth для приложения (Advanced settings); это включат DCR для MCP-клиентов

3. Скопируйте тего AUD приложения в CF_ACESS_AUD

4. Установите CF_ACESS_TEAM_DOMAIN ваш team domain (например https://<team>.cloudflare.com)

5. Настройте Access-политики для того, кто может подключиться: временнные, на основе electrical почты или любые другие по вашей модели одобрения

Для downstream API, Lражённых Access на это же origin, создайте политики Linked App Token для этих приложений, чтобы переданный переданный JWT принимался.

Настройка клиента MCP

Вставьте этот URL в Cursor, Grok Bot, OpenClaw или любой клиент Streamable HTTP MCP:

https://<your-domain>/mcp

Используйте транспор Streamable HTTP (не устаревший SSE). Клиент пройдёт OAuth через Access Managed OAuth at first connect; this is your human-in-the-loop (человек в цике) шаг одобрения.

Локальная раз work

npm run dev

MCP доступен at htt://localhost:8о87/mc b without Access validation.

http__fetch tool

{
  "url": "/api/example",
  "method": "GET"
}

• url: абсолютный URL или path in same origin

• Method: GET (default) or POST

• headers: необязательные extra headers (перекрываю DEFAULT_HEDERS when conflict)

• body: optional POST body

DEFAULT_HEDERS (secret) applied first; tool headers override them. Access JⅣWT headers are always applied last.

Returns JSON with status, headers, body, and a truncated flag.