The server never calls your plugin’s data for the agent — it only describes how to. Three tools do all the work: list_apis (what exists), how_to_call (how to invoke it) and get_token (a credential to invoke it with). The agent takes the descriptor how_to_call returns and makes the real HTTP request itself, directly against your plugin’s own endpoint.

The split is deliberate: a descriptor answers "how do I call this" and is worth keeping, while a token is worth seconds. Were the token baked into the descriptor, its clock would start when the agent asked how to call something — and an agent that reasons, or asks its user, before actually calling would find it already expired.

This means RESTHeart’s existing ACL applies exactly as it does to any other client — an action the agent’s credentials can’t perform still fails with a normal 403, the same way it would for a human hitting the same endpoint.

Your describeMcp does not filter by principal, and should not: describe everything your plugin exposes. The MCP server filters the catalog itself, per caller, hiding from list_apis, resources/list and how_to_call anything whose read that caller’s ACL would refuse. Discovery therefore follows the same boundary as access, and you get that without writing any authorization code of your own.

Filtering by scope is the one exception, and it is yours to do — see ctx.scope().

Two ways to implement it, depending on whether your plugin exposes one fixed thing or many dynamic ones.

how_to_call composes a descriptor, it never executes it. For an action backed by a body_schema, the actual body goes under an args.body key — not as top-level args:

Any other top-level args entries become the query string instead — this applies uniformly across HTTP, SSE, and WebSocket transports.

If the action has a body_schema and the body does not satisfy it, how_to_call refuses to compose the request and reports which property failed and why, by JSON pointer:

For a schema whose top level is a oneOf, each alternative is reported separately — alternative 'offer' does not match: …​ — so it is clear which shape you were aiming at rather than being handed the union of every alternative’s requirements.

The descriptor’s Authorization header holds the literal placeholder Bearer <token_from_get_token> — it never carries a credential, which is what makes it stable and reusable. The agent calls get_token when it is about to send the request and substitutes the value:

Same field names as RESTHeart’s own /token endpoint, so an agent that has seen either recognises this one. The token carries the identity and roles of the MCP session and nothing more — it can do exactly what that session can do — and expires within expires_in seconds. That short life is the point: the agent never handles a password or a long-lived API key, and a token that leaks is worthless almost immediately.

Read access_token from the response and put it in the descriptor’s Authorization header as Bearer <token>.

Requires the jwtIssuer provider (enabled by default) and an authenticated session; the tool returns an explanatory error rather than a weaker credential when either is missing.

list_apis/how_to_call only ever describe a request — for a plugin whose data agents should be able to read directly (loaded straight into context, or picked from a host UI’s resource list), implement the resources primitive’s read side too. Mark a safe, idempotent, GET-shaped action readable, and override readResource() to actually produce the data, in-process — no HttpServerExchange, no self-directed HTTP call:

Declare the resource subscribable as well if changes to it can be watched, and clients can call resources/subscribe on it; the framework refuses a subscription to any resource that does not declare it, rather than accepting one that would never fire.

resources/read always means "here is real data" — a resource with no readable action is simply never registered with the resources primitive at all (resources/list/resources/templates/list); it stays discoverable through list_apis/how_to_call only. There is no "context" fallback to fall back to. If your default action needs an argument with no sensible default, the framework surfaces it as a Resource Template instead of a plain resource, so a client knows to fill it in before reading — see the "Reading data directly" section of MCP for MongoDB & GraphQL for a concrete example (aggregations with a required $var).

One RESTHeart process can serve several isolated callers, each seeing only its own slice of the catalogue. ctx.scope() tells you which slice you are describing.

It is an opaque token: a name for which partition, never a description of what a partition is. What it means is yours to decide — MongoService reads it as a database name, a plugin backed by something else maps it onto whatever its own content is organised by.

If your plugin’s content is the same for every caller, ignore it. Ignoring it is already correct: the same resources are contributed to every partition, each carrying that partition’s own base URL. There is nothing to write.

If your plugin’s content depends on the caller, you must filter by it. RESTHeart cannot do this for you: a plugin that returns identical resources in every partition looks exactly like one that forgot to check.

Most deployments never partition anything. With no McpScopeProvider registered every request resolves to McpScopeProvider.UNPARTITIONED and ctx.unpartitioned() is always true, so the branch above is all you need to stay correct in both cases.

Any McpAware plugin is exposed by default; set mcp: false in its own configuration to opt out entirely — the same override mechanism as enabled/uri:

list_apis/how_to_call read from a cache, not from every McpAware implementation’s describeMcp() on every call — refreshed at most every catalog-ttl-seconds. Change what your plugin exposes and an agent may see the old state for up to that long; there’s no live invalidation watching your plugin’s own data source. When a cache entry expires, already-connected agents get a notifications/tools/list_changed push telling them to refetch.

This is a deliberate trade-off: instant, source-specific invalidation would mean different wiring per McpAware implementation (a MongoDB write, a config reload, …​); a single TTL is one uniform mechanism for all of them, at the cost of a bounded staleness window.