feat(mcp): scope custom tool queries to a tenant from a verified token claim

[vishal-bala]

Motivation

When tenants share one index, separated by a field such as org_id, exposing search-records makes the tenant boundary depend on the model remembering to pass a filter. One forgotten filter is a cross-tenant read, and no prompt closes that gap. This PR lets a custom tool profile take the tenant from the caller's verified token instead: every query the profile runs is AND-scoped to the value of a named claim, and the model can neither see nor set it. It builds on the security core merged in #738 and wires it into configuration, the profile wrapper and server startup.

The guarantee is narrow and stated exactly: a client presenting a validly signed token cannot make the model widen or escape the tenant scope carried in that token. The trust boundary is the identity provider, not the MCP client.

Changes

Configuration

A profile declares injection under lock:

custom_tools:
  - name: search-customer-kb
    index: customer_kb
    description: Search this customer's knowledge base.
    lock:
      inject:
        - field: org_id                      # a tag field in the index schema
          from: claim
          claim: "https://acme.example/org"  # the claim name the identity provider emits
          required: true

field and claim are independent names, because the index and the identity provider each choose their own. from must be stated and must be claim, and required accepts only true, because optional injection is unscoped injection. Config load rejects an empty list, a field injected twice, and a field that lock.filter also constrains, since a static lock and an injected value on one field are two answers to the same question.

Enforcement on every call

The wrapper resolves the claim per request and folds the result into the profile's locked filter instead of passing it alongside. That matters because merge_locked_filter returns the caller's filter untouched when nothing is locked: only a non-empty locked side forces the caller's filter through the escape backstop. A profile with injection and no static lock would otherwise AND the tenant clause and skip that check. The rendered query for a caller filtering on another tenant shows the effect:

(@org_id:{acme} @org_id:{victim})     # unsatisfiable, so nothing leaks

The injected field is absent from the advertised input schema, and FastMCP rejects a tools/call that names it before the wrapper runs. It is also left out of the description's field hints, which keeps the rest of the hints rather than suppressing them wholesale.

The claim reader

A claim must be a single, non-empty, unpadded string, and anything else refuses the request with forbidden before any query runs. A list is refused on type, because Tag(f) == ["a", "b"] renders @f:{a|b}, a genuine union that no inspection of the finished query could tell from a legitimate one.

This PR also corrects two things in the reader merged in #738. Measured on Redis 8.4, the query parser splits a tag term on every control character and on the backtick, so a claim such as \x01acme matched the tenant acme and acme\tcorp matched acme corp. A sweep of U+0000–U+024F, the general punctuation block, and parts of the CJK symbol and fullwidth blocks found exactly 33 such code points, U+0001–U+001F, U+007F and U+0060, and the reader now refuses them. Conversely, the reader no longer refuses |: Tag escapes it within a single value and Redis matches the escaped form literally, so the refusal guarded nothing and turned away real identifiers such as an Auth0 subject, auth0|64f1c2.

Startup refusals

Startup refuses an injecting profile wherever the configuration alone shows the guarantee cannot hold:

Refused when	Why
Authentication is not enabled, on any transport	There is no verified token to read. This covers an unauthenticated loopback bind and any --allow-unauthenticated bind, not only stdio.
Authentication is configured but the server runs over stdio	FastMCP never authenticates stdio, so every call would be refused. run_async now records the transport, resolving an omitted one the way FastMCP does.
search-records, upsert-records on a writable index, or a profile whose lock.inject differs can reach the same index	Each is an unscoped route past the profile. The scope belongs to the index, so every profile on it must inject the same (field, claim) entries: one scoped by another field, or by the same field from another claim, reads across the tenants the first separates. A write is worse than it looks: hash storage merges a partial record into the existing key, so one tenant could retag another's document as its own.
The injected field is absent, is not a tag, or is NOINDEX	A NOINDEX filter matches nothing without an error, which looks like correct scoping. Text fields are excluded because a phrase match over tokenised text lets acme-corp also match acme-corp-eu.

The first three depend only on configuration, so they run before any binding connects and report even with Redis unreachable. A non-case-sensitive injected field warns instead of failing, because Redis folds tag case Unicode-wide unless the field is CASESENSITIVE, and only the operator knows whether their identity provider emits one canonical form.

A changed tool surface after an in-process restart stays a warning, except when injection is configured on either side of the change, where startup now fails. Adding injection to a profile registered without it would otherwise leave that tool serving every tenant while the config says otherwise.

Smaller changes

• The server's _validate_custom_tools becomes _validate_custom_tools_against_schema, ending its name collision with MCPConfig._validate_custom_tools.
• The JSON filter DSL clause walker moves from the profile module into config, where load-time validation now needs it.
• build_injected_filter drops its schema parameter, along with a request-time field re-check that read the schema captured at registration and so could never fire. Startup re-validates the freshly inspected schema on every start.
• The clause-containment check merged in feat(mcp): add the security core for auth-claim tenant injection #738 gains the test it lacked.
• A refusal is logged once: FastMCP already logs the raised error.
• The concepts page, the MCP how-to guide and the authentication guide document the feature, its startup checks and its threat model, and drop three statements that RedisVL never maps token claims to query filters.

Notes

The stdio refusal applies when the server starts through rvl mcp or run_async, the only points that know the transport. An embedder that calls startup() directly and serves stdio is not refused at startup, but every call is still refused at request time for lack of a token, so the failure is closed either way.

The injected field is withheld from the schema and the hints, not hidden outright. Unless lock.return_fields excludes it, results carry the field, and list-indexes describes the whole schema. The value shown is only ever the caller's own tenant.

The guarantee rests on preconditions the operator owns, and the threat model states them: a genuinely verified token with an asymmetric algorithm, a claim the identity provider assigns, trusted ingestion, and documents stamped with exactly their tenant. The last is subtler than it sounds, because Redis normalises the stored value rather than the claim: it splits on the field's separator, trims surrounding whitespace, and indexes every element of a JSON array, so a document stamped acme,victim belongs to both tenants.

Release Notes

Custom tool profiles can scope every query to a tenant read from the caller's verified token, with lock.inject. The injected field is never offered to the model, and the server refuses to start an injecting profile when authentication is off, when it runs over stdio, or when another tool can reach the same index without the tenant scope.

Next Steps

Python code tools, planned for the next phase, will receive verified claims through their tool context. They can reuse build_injected_filter and validate_inject_against_schema, which take a plain spec list rather than a configuration model, but composing the result with a caller filter currently lives inline in the profile wrapper. A single composition function, extracted when code tools land, would give them the escape backstop without re-deriving it.

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 0b8848b. Configure here.}