# @olykov/node-red-contrib-mcp-server-readonly

Generic [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server nodes for
Node-RED: expose any flow as an MCP tool behind an OAuth-protected endpoint, with optional
read-only Node-RED admin flow inspection. No home-automation or other domain coupling — this
is a bare building block for turning Node-RED flows into MCP tools that AI assistants
(Claude, Codex, etc.) can call.

> **Breaking change in 0.5.0 — public client (PKCE) only.** Client secrets and the
> node-side redirect URI allowlist are gone: the open client-registration endpoint handed
> any configured secret to every caller, and redirect URIs are validated by the identity
> provider at `/authorize` anyway. **Migration:** switch the IdP client to **public with
> PKCE** (a still-confidential client fails token exchange with `invalid_client`), make
> sure the MCP client callback URLs are whitelisted at the IdP, and if the node warns
> about a stored secret, open its config, click **Done**, and deploy to delete it. MCP
> clients connected before the upgrade may have cached the old registration — remove and
> re-add the server in the client if sign-in misbehaves.

## Nodes

- **`mcp-server`** (config node) — hosts a standalone MCP JSON-RPC endpoint at
  `POST /mcp/<path>`, OAuth 2.0 protected-resource discovery (RFC 9728), authorization-server
  discovery (RFC 8414) proxying a real OIDC identity provider, and a dynamic client
  registration shim, so OAuth-aware MCP clients (e.g. Claude.ai) can self-register and
  authenticate. Multiple `mcp-server` nodes can coexist, each with its own path and its own
  independent auth configuration.
- **`mcp-in`** — defines one MCP tool (name, description, JSON-Schema parameters, and an
  optional per-tool access gate). When an MCP client calls the tool, the node emits a message
  carrying the call arguments; wire the rest of the flow to do the actual work. The arguments
  in `msg.payload` are **untrusted caller input** — the JSON schema is documentation for the
  model, not validation — so the flow must validate and escape them before use in shell
  commands, file paths, URLs or queries.
- **`mcp-out`** — resolves a pending tool call. Wire the end of your flow here with
  `msg._mcpCallId` intact (from the originating `mcp-in` message) and `msg.payload` set to
  the result.

A single `mcp-in` → ... → `mcp-out` chain is one MCP tool. Build as many chains as you want
against the same `mcp-server` node to expose a whole toolset.

## Admin read-only API tools

Enable **Admin read-only API tools** on an `mcp-server` node to additionally expose one tool that operates
on Node-RED's own Admin HTTP API, gated by a configurable JWT claim (default: `groups`
contains `admin`):

- **`get_flow`** — lists all flow tabs (id, label, node count), or returns the full JSON of
  one tab when called with an `id`.

## Configuring an `mcp-server` node

- **General**: name, `path` (→ registers `POST /mcp/<path>`), the public `Server URL` this
  Node-RED instance is reachable at, optional server name/instructions shown to the model, and
  an optional **hostname filter** (see below).
- **Auth**: an OIDC `Identity provider` issuer URL (**required** — endpoints auto-discovered
  from `/.well-known/openid-configuration`, with PocketID-style fallback paths; leaving this
  empty produces a broken OAuth discovery document with relative-path endpoints and no working
  auth, so the editor won't let you deploy without it), a client id (the IdP client must be
  **public with PKCE** — client secrets are no longer supported, and redirect URIs are
  configured and validated at the IdP only), scopes, token audience, an optional local debug token that bypasses
  the IdP entirely for local testing (put any placeholder URL in Identity provider and rely on
  the debug token — it's never contacted when the debug token matches; the `groups` claim the
  debug user gets is configurable so the access gates can be tested locally too), and the
  `Access claim` / `Server access` gate (see below).
- **Admin**: enable/disable admin read-only API tools, admin token (for the Node-RED Admin API),
  admin API port, and the `Read-only access` gate that additionally restricts just the
  read-only admin tools.

### Access control

**One claim name, many value lists.** `Access claim` on the Auth tab (default `groups`) names the
single JWT claim every gate matches against. Every other authorization field is a comma-separated
**any-of** list of that claim's values — `media, ops` passes if the claim contains at least one of
them. An empty list imposes no restriction.

**Nested claims** are addressed with a dotted path, for providers that don't put roles at the top
level of the token: `realm_access.roles` reads Keycloak's realm roles, and any depth works. A key
that exists literally always wins, so a claim genuinely named with a dot in it still resolves to
itself. Only strings and arrays of strings match — pointing the claim at a container object grants
nothing rather than matching by accident.

| Field | Where | Restricts |
|---|---|---|
| `Server access` | mcp-server, Auth tab | every tool on this server |
| `Tool access` | mcp-in | that one tool, additionally |
| `Read-only access` | mcp-server, Admin tab | `get_flow`, additionally |

**The lists are combined with AND.** Reaching a tool means clearing the server's list *and* that
tool's own list. Admin read-only API tools are not a special case — their field is simply the
tool list for `get_flow`.

```
Access claim: groups     Server access: staff
tool A: (empty)   tool B: media   Admin access: admin

groups=[staff]         → A
groups=[staff, media]  → A, B
groups=[staff, admin]  → A + get_flow
groups=[media]         → nothing            (server list not cleared)
groups=[guest]         → nothing

Server access empty:
groups=[media]         → A, B
groups=[guest]         → A
```

Everyone with a valid token still connects — `initialize` always succeeds — but tools a caller
can't reach are hidden from `tools/list` and from the `initialize` instructions. A direct
`tools/call` on one of them is refused as an MCP tool result with `isError: true` and an
explanatory message (not a raw JSON-RPC protocol error), so the reason reaches the calling model
instead of being collapsed into a generic "tool execution failed".

### The client axis: required scope

The lists above answer *what may this user do*. `Required scope` answers a
different question — *what was this client authorized to do on the user's behalf* — and the two
are checked with **AND**.

They are not interchangeable. A group says who is at the keyboard; a scope says how much of that
person's authority was delegated to the software holding the token. Collapse them into one field
and only one gets consulted: a client granted a read-only scope, driven by someone who may write,
would write. The client's grant has to bound the user's rights, not be ignored.

The required scope is added to `scopes_supported` automatically, so there is nothing to repeat in the scopes field, and it is named in the `WWW-Authenticate` challenge on a 401.

The scope claim is read the way OAuth defines it
([RFC 6749 §3.3](https://datatracker.ietf.org/doc/html/rfc6749#section-3.3)): a space-delimited
string, or an array if your provider sends one. The claim name is not configurable because it is standardised; `scp` is read as a fallback for
Microsoft Entra and Okta. The field itself is a comma-separated any-of list. Empty means no constraint, so an install that
never fills it in is unaffected; a configured scope the token does not carry is refused,
including when the token has no scope claim at all.

> **Upgrading:** the admin gate no longer has its own claim-name field — it matches against the
> Auth tab's `Access claim` like everything else. If you had set a *different* claim name for
> admin tools, move that value to the Auth tab or adjust the admin list accordingly. A value that
> literally contains a comma is now read as a list rather than one literal string. The gate fields
> were also relabelled (`Required claim`/`Required value` → `Access claim`/`Server access`/`Admin
> access`); the underlying settings are unchanged, so existing flows keep working untouched.

### Protocol

The endpoint speaks MCP protocol version `2024-11-05` over plain HTTP POST — every request is
one JSON-RPC message, every response one JSON body. `initialize`, `tools/list`, `tools/call`, `resources/list`, `resources/read` and
`ping` are supported; there is no SSE/streaming `GET` channel and no server-initiated messages.
This is the subset today's OAuth-capable MCP clients (e.g. Claude) actually use against a tools-only
server. The advertised version is intentionally pinned rather than echoing the client's offer.

### Hostname filtering

Off by default. When **Only serve requests for this hostname** is enabled, the node only answers
requests whose `Host` header matches the hostname in its `Server URL`. This lets several
`mcp-server` nodes share the *same* `path` on one Node-RED instance, each answering only its own
virtual host — useful behind a reverse proxy that fronts multiple hostnames for one Node-RED
backend. Leave it off for a single server, or when a reverse proxy rewrites the `Host` header.

### Reverse proxy

Each `mcp-server` node is its own OAuth resource — unlike a single shared MCP endpoint, every
instance registers **its own** discovery and registration routes, scoped under its `path`. For
a node with `path: docker` and `Server URL: https://mcp.example.com`, these six routes exist:

| Method & path | Purpose |
|---|---|
| `POST /mcp/docker` | The JSON-RPC MCP endpoint (bearer-token protected) |
| `GET /mcp/docker/.well-known/oauth-protected-resource` | Resource metadata (RFC 9728), path-inserted form |
| `GET /.well-known/oauth-protected-resource/mcp/docker` | Resource metadata (RFC 9728), RFC 8414 form |
| `GET /mcp/docker/.well-known/oauth-authorization-server` | Auth-server metadata (RFC 8414), path-inserted form |
| `GET /.well-known/oauth-authorization-server/mcp/docker` | Auth-server metadata (RFC 8414), RFC 8414 form |
| `POST /mcp/docker/oauth/register` | Dynamic client registration shim |

**Client ID Metadata Documents (CIMD).** MCP 2026-07-28 deprecates dynamic client registration in favour of [CIMD](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-client-id-metadata-document-01), where a client's id is the HTTPS URL of a metadata document it hosts itself. This node advertises `client_id_metadata_document_supported` by mirroring what your IdP's discovery document says — it is never configured here, because it is the IdP that resolves the client id, and this server is in no position to promise support the IdP doesn't have. Discovery is fetched once and cached for the lifetime of the node, so enabling or disabling CIMD on the IdP is picked up at the next Node-RED restart or deploy — not live.

**The DCR shim is off by default and should stay off.** It exists for one situation: a client that cannot use CIMD, talking to an IdP that cannot do DCR itself. When it is on, this server advertises *itself* as the authorization server so that the registration endpoint is discoverable — which also means the `iss` your IdP returns will not match the issuer the client recorded, and a client enforcing [RFC 9207](https://datatracker.ietf.org/doc/html/rfc9207) (required by MCP 2026-07-28) will refuse to finish the flow. With it off, clients are sent straight to the IdP and must use CIMD or a pre-registered client ID. A node configured before this switch existed keeps the shim on, since that is what it has been doing.

Both mechanisms stay available on purpose. Clients pick in the spec's order — pre-registered, then CIMD, then DCR — so a client without CIMD support keeps using the registration shim exactly as before. Which mechanism each client took is readable from the log: `MCP CIMD client authenticated: <url>` the first time a CIMD client is seen after a restart, and `MCP DCR fallback` for a client that registered even though the IdP advertises CIMD. Between them the two lines account for every client that reaches the server.

Tokens from a CIMD client carry that document URL as their audience rather than your pre-registered client id, and they are accepted whenever the IdP advertises CIMD. This node keeps no second allowlist of its own, so the IdP's list of accepted metadata documents is the boundary — any CIMD client on it can reach this server, with the claim gate as the remaining check.

Both well-known forms are advertised because different MCP clients probe different ones —
expose both. Since every instance's routes share the `/mcp/<path>` and `/.well-known/*/mcp/<path>`
shapes, **one set of wildcard rules covers every current and future `mcp-server` node** (as long
as they're all reachable through the same domain/upstream) — no reverse-proxy change needed when
adding a new `path`. Example, using
[Caddy](https://caddyserver.com/) via [caddy-docker-proxy](https://github.com/lucaslorentz/caddy-docker-proxy)
labels:

```yaml
labels:
  caddy_1: mcp.example.com
  caddy_1.reverse_proxy_0: /mcp/* "{{upstreams 1880}}"
  caddy_1.reverse_proxy_1: /.well-known/oauth-protected-resource/mcp/* "{{upstreams 1880}}"
  caddy_1.reverse_proxy_2: /.well-known/oauth-authorization-server/mcp/* "{{upstreams 1880}}"
```

Node-RED itself 404s any path that isn't an actual registered route, so the wildcard doesn't
expose anything beyond what each deployed `mcp-server` node already registers. If a `path`
needs to be reachable on a *different* domain than the others, give it its own `caddy_N` site
block (or combine with [hostname filtering](#hostname-filtering) above).

**What the identity provider needs to support** (same requirements as `lib/mcp-auth.js`):

- An **OIDC provider with discovery** — endpoints are read from
  `‹issuerUrl›/.well-known/openid-configuration`, falling back to PocketID's path layout if
  discovery is unavailable.
- **JWT access tokens** signed with a key published on the provider's **JWKS** (tokens are
  verified locally; opaque/introspection-only access tokens are not supported).
- A **public client** with **PKCE (S256)**, grant types `authorization_code` +
  `refresh_token`, and the MCP client's **redirect URI(s)** whitelisted (for Claude.ai:
  `https://claude.ai/api/mcp/auth_callback`). Redirect URIs are configured and validated at
  the identity provider only — the node no longer keeps its own allowlist, so IdP wildcard
  support (e.g. PocketID's) works as-is. Client secrets are no longer supported: the open
  client-registration endpoint handed any configured secret to every caller, so it could
  never actually be secret. If a secret is still stored from an earlier version it is
  ignored with a warning — switch the IdP client to public, then open the node's config,
  click Done, and deploy to delete the stored secret and clear the warning.

> Tested with **Caddy** (reverse proxy) + **PocketID** (identity provider) + **Claude.ai** and
> **Hermes** (MCP clients). Any spec-compliant OIDC provider issuing JWT access tokens, behind
> any reverse proxy that forwards the routes above, should work the same way.

## Interactive MCP Apps picker

The MCP endpoint uses **Streamable HTTP** and advertises the standard MCP Apps extension
`io.modelcontextprotocol/ui`. A Node-RED flow can return a generic inline picker by sending
`msg.mcpResult` to `mcp-out` with `structuredContent.options` and the picker UI resource metadata.

The picker is intentionally **text-only**. It does not render, accept, proxy, persist, or pass image
fields. If a flow accidentally includes `image`, `images`, `src`, or other visual fields inside
options, the server-side sanitizer drops them before the result reaches the app.

```js
msg.mcpResult = {
  content: [{ type: 'text', text: 'Choose an option in the picker.' }],
  structuredContent: {
    title: 'Choose an option',
    description: 'Select the direction to continue with.',
    selectionMode: 'single', // or 'multiple'
    options: [
      {
        id: 'option_a',
        label: 'Option A',
        description: 'Short note for the user'
      }
    ]
  },
  _meta: {
    ui: { resourceUri: 'ui://picker/v4/options.html' },
    'ui/resourceUri': 'ui://picker/v4/options.html'
  }
};
return msg;
```

The app-only helper tool `picker_submit` validates a picker selection submitted from the HTML app
and returns `structuredContent.type = 'picker_selection'` with `selectedIds` and optional
`otherOption`. `selectedIds` may be an empty array when the user enters only an other option.

Legacy `msg.mcpElicitation`, `openai/form`, and `openai/imagePicker` compatibility is not supported.
Flows must return the MCP Apps `msg.mcpResult` shape above.

## Examples

See [`examples/`](examples/) for nine ready-to-import flows (Jellyfin, Calibre, Docker,
Music Assistant, Radarr, iRobot/rest980, Overseerr, Sonarr, Spotify), each with its own
`mcp-server` node (server description pre-filled, `Server URL`/`Identity provider` left
blank for you to fill in) and `mcp-in`/`mcp-out` tools — a good reference for wiring up
your own tools.

## Development

```
npm install
npm test
```

## License

ISC