TanStack AI 1.4.0: MCP Request Meta und sicheres Upgrade

@tanstack/ai 1.4.0 sendet pro Anfrage _meta an MCP-Tool-Calls. Was der 9-Datei-Diff wirklich ändert, warum ai-mcp 1.2.0 zählt und wie Sie sicher upgraden.

Huifer
Huifer
12. November 202610 min read
Auch verfügbar auf:English · 中文

Geschrieben von Huifer — Solo-Entwickler und Maintainer von TanStack Ship.

Als npm @tanstack/ai am 9. November 2026 um 17:45:28 UTC auf latest gesetzt hat, habe ich gemacht, was ich bei jedem Dependency-Bump in meinen eigenen Templates mache: beide veröffentlichten Tarballs — 1.3.0 und 1.4.0 — herunterladen und die ausgelieferten Typdeklarationen diffen, statt einer Release-Zusammenfassung zu vertrauen. Der Diff umfasste 9 von 648 Dateien und erzählte eine deutlich konkretere Geschichte als „AI-SDK-Update“: 1.4.0 ist das Release, das einer einzelnen MCP-Anfrage erlaubt, ihren eigenen Kontext mitzuführen.

Verifizierte Quellen: TanStack AI docs · TanStack · TanStack AI on GitHub · @tanstack/ai 1.4.0 on npm · web.dev · Cloudflare Workers docs

Zuletzt aktualisiert: 12. November 2026

TanStack AI 1.4.0 bringt genau ein Feature für Nutzer mit: pro-Anfrage-MCP-_meta. Die npm-Registry zeigt @tanstack/ai@1.4.0 mit Veröffentlichungszeitpunkt 2026-11-09T17:45:28.315Z und dem latest-Dist-Tag. Der Diff des veröffentlichten Tarballs gegen 1.3.0 zeigt 9 geänderte Dateien von 648, und das gesamte Delta ist ein neuer requestMeta-Hook, mit dem jeder MCP-Tool-Call und jeder ui://-Resource-Read sein eigenes _meta — Tenant-, User- oder Trace-Kontext — an den MCP-Server sendet. Dieser Leitfaden behandelt, was sich geändert hat, wie Sie upgraden und welche Abhängigkeit Sie mitanheben müssen.

TL;DR

  • Gemessen: @tanstack/ai@1.4.0 veröffentlicht am 2026-11-09T17:45:28.315Z, 4 Std. 36 Min. 57 s nach 1.3.0.
  • Gemessen: 9 von 648 veröffentlichten Dateien geändert; entpackte Größe 5.898.105 → 5.905.099 Bytes (+6.994 B, +0,12 %).
  • Gemessen: die einzige neue öffentliche API sind MCPRequestMeta / MCPRequestMetaInput plus requestMeta in den MCP-Chat-Optionen.
  • Gemessen: die Wire-Seite liegt in @tanstack/ai-mcp@1.2.0, veröffentlicht 18 Min. 40 s nach dem Core — Core 1.4.0 allein sendet kein _meta.
  • Meine Einschätzung: ein risikoarmer Bump für alle, die MCP nicht nutzen; ein Pflicht-Bump für Multi-Tenant-Apps, die sich einen MCP-Pool teilen.
  • Kaufentscheidung: AI-SaaS-Boilerplates im direkten Vergleich, um zu sehen, welche Starter pro-Anfrage-MCP-Kontext bereits mitbringen.

Definition: @tanstack/ai@1.4.0 ist das November-2026-Release des typsicheren AI-SDK von TanStack, das einen requestMeta-Hook für MCP-Chat-Runs ergänzt, damit jeder Tool-Call und jeder ui://-Resource-Read sein eigenes _meta — Tenant-, User- oder Trace-Kontext — zum MCP-Server tragen kann.

Was @tanstack/ai 1.4.0 wirklich ausliefert: der verifizierte Befund

Ich teile diesen Abschnitt in das, was die Registry belegt, und das, was der Tarball-Diff belegt — denn ein Release-Note, das beides vermischt, ist genau der Ort, an dem Upgrade-Pläne schiefgehen.

Die Registry-Fakten

Jede Zeile unten ist aus dem npm-Registry-Eintrag für 1.4.0 gelesen. Die 1.3.0-Spalte ist dieselbe Datei, in gleicher Tiefe gelesen — die Deltas sind also vergleichbar.

Registry-Feld@tanstack/ai@1.3.0@tanstack/ai@1.4.0
Veröffentlichungs-Zeitstempel2026-11-09T13:08:31.742Z2026-11-09T17:45:28.315Z
Beschreibung"Type-safe TypeScript AI SDK for streaming chat, tool calling, agents, structured outputs, and multimodal generation."unverändert
LizenzMITMIT
EnginesNode >=18Node >=18
Peer-Dependency@opentelemetry/api >= 1.9.0unverändert
Interne Dependencies@tanstack/ai-utils@^1.1.0, @tanstack/ai-event-client@^1.0.1unverändert
Externe Dependencies@ag-ui/core@1.0.0, partial-json@^0.1.7, fast-json-patch@^3.1.1, @cfworker/json-schema@^4.1.1, @standard-schema/spec@^1.1.0unverändert
Export-Subpaths10 (., ./byok, ./locks, ./client, ./testing, ./adapters, ./byok/server, ./middlewares, ./middlewares/otel, ./adapter-internals)unverändert
Veröffentlichte Dateien / entpackte Bytes648 Dateien / 5.898.105 B648 Dateien / 5.905.099 B

Zwei Zeilen entscheiden über das Risikoprofil. Die Export-Map hat sich nicht geändert, also muss kein Import-Pfad in Ihrer App umgeschrieben werden. Und kein Dependency-Range hat sich verschoben, damit ist der Auflösungsgraph Ihrer Installation identisch mit 1.3.0 — dies ist nicht das Release, das Ihre Lockfile brechen kann.

Der 9-Datei-Diff

Im Tarball-Diff steckt die eigentliche Geschichte. Vier der neun geänderten Pfade sind kompilierte .js/.js.map-Artifacts; drei sind die TypeScript-Quellen, aus denen sie gebaut wurden, und einer ist das Versionsfeld in package.json.

Geänderter Pfad (1.3.0 → 1.4.0)Was sich geändert hat
src/activities/chat/mcp/types.tsNeue Typen MCPRequestMeta und MCPRequestMetaInput; requestMeta zu den tools()-Optionen der Quelle ergänzt; readResource() erhält ein optionales zweites Argument
src/activities/chat/mcp/manager.tsDer Manager reicht requestMeta in jeden tools()-Aufruf jeder Quelle und in die gebundene readResource-Closure durch
src/index.tsExportiert die beiden neuen Typen aus dem Paket-Root
dist/esm/** + package.jsonKompilierte Ausgabe des oben Genannten, plus der Versions-Bump auf 1.4.0

Sonst hat sich im Paket nichts bewegt. Das ist ein bewusst schmal geschnittenes Release: ein Hook, ein Union-Type, ein optionaler Parameter.

Das eine Feature dieses Releases: pro-Anfrage-MCP-_meta

Der Use Case gehört vor die API besprochen, denn er entscheidet, ob Sie dieses Release überhaupt brauchen.

Wie der Hook tatsächlich läuft

Die offizielle Doku beschreibt ihn unter „Send request context to MCP servers“ im Managed-MCP-Leitfaden. Das gelöste Problem: Ein gemeinsamer MCP-Pool verbindet sich einmal, seine Header sind für jede Anfrage identisch. Gehört jede Anfrage zu einem anderen Tenant, kann ein Header diesen Kontext nicht tragen — _meta dagegen reist mit der einzelnen Anfrage, auf jedem Transport.

Das dokumentierte Verhalten:

  • Der Hook läuft einmal pro MCP-Anfrage, beim Start der Anfrage. Die Tool-Erkennung ruft ihn nicht auf.
  • Er erhält method und serverId; ein tools/call trägt zusätzlich toolName und args, ein resources/read trägt uri. In einem Pool ist serverId der Config-Key.
  • Geben Sie undefined zurück, um kein _meta zu senden.
  • Der Client entfernt die von MCP reservierten Keys: progressToken sowie Präfixe wie io.modelcontextprotocol/ oder mcp.dev/.
  • Wirft der Hook einen Fehler, scheitert nur diese eine Anfrage — ein Tool-Call geht als Tool-Fehler ans Modell, und ein ui://-Read erzeugt schlicht kein Widget.
  • _meta ist nicht Teil des toolCacheMiddleware-Keys, daher sendet ein Cache-Hit keine Anfrage, und der Hook läuft nie.

Der letzte Punkt ist die Falle, die ich jedem nennen würde, der das für die Produktion prüft: Teilen sich Tenants einen Cache-Speicher, muss der Tenant Teil von keyFn sein — sonst kann das gecachte Tool-Ergebnis eines Tenants bei einem anderen landen.

Wie die Typ-Oberfläche aussieht

Die ausgelieferten Deklarationen in 1.4.0 sind eine discriminated union plus ein Funktionstyp. Aus der veröffentlichten Datei dist/esm/activities/chat/mcp/types.d.ts:

typescript
// @tanstack/ai@1.4.0 — veröffentlichte Typ-Oberfläche (wortgetreue Form)
export type MCPRequestMetaInput =
  | {
      method: 'tools/call'
      serverId: string | undefined
      toolName: string
      args: Record<string, unknown>
    }
  | { method: 'resources/read'; serverId: string | undefined; uri: string }

export type MCPRequestMeta = (
  request: MCPRequestMetaInput,
) =>
  | Record<string, unknown>
  | undefined
  | Promise<Record<string, unknown> | undefined>

Auf der Ebene des Chat-Runs, gemäß der offiziellen Doku:

typescript
// Pro-Anfrage-Kontext in einem gemeinsamen MCP-Pool.
const stream = chat({
  adapter: openaiText('gpt-6.1-sol'),
  messages,
  threadId,
  runId,
  mcp: {
    clients: [sharedPool],
    connection: 'keep-alive',
    requestMeta: ({ serverId }) =>
      serverId === 'internal'
        ? { 'acme.com/tenantId': tenantId, 'acme.com/traceId': traceId }
        : undefined,
  },
})

Der Check serverId === 'internal' ist das Multi-Tenant-Muster: ein Pool, mehrere Server, und Kontext wird nur an den Server weitergeleitet, der ihn sehen darf. Denselben Hook gibt es eine Ebene tiefer — mcp.tools({ requestMeta }) — für Apps, die Tools manuell verwalten, wie im Manual-MCP-Leitfaden gezeigt.

So upgraden Sie auf 1.4.0

Prüfen Sie, was Sie tatsächlich haben

Beginnen Sie mit dem aufgelösten Dependency-Baum statt mit dem Range in Ihrer package.json:

bash
npm ls @tanstack/ai @tanstack/ai-mcp
npm view @tanstack/ai dist-tags
npm view @tanstack/ai-mcp dist-tags

Nutzt Ihre App MCP gar nicht, ist 1.4.0 für Sie wirkungslos, und die Entscheidung ist schlicht „nehmen oder lassen“. Nutzt sie MCP, zählt die zweite Zeile mehr als die erste.

Das gepinnte Paar installieren

Pinnen Sie exakte Versionen, damit CI und Teamkollegen denselben Tarball auflösen:

PaketmanagerBefehl
npmnpm install @tanstack/ai@1.4.0 @tanstack/ai-mcp@1.2.0
pnpmpnpm add @tanstack/ai@1.4.0 @tanstack/ai-mcp@1.2.0
yarnyarn add @tanstack/ai@1.4.0 @tanstack/ai-mcp@1.2.0
bash
# Installieren und danach prüfen, dass die Lockfile das Gewünschte aufgelöst hat
pnpm add @tanstack/ai@1.4.0 @tanstack/ai-mcp@1.2.0
grep -E '"@tanstack/ai(-mcp)?"' pnpm-lock.yaml
pnpm typecheck && pnpm test

Der stille Fehlerfall: Core 1.4.0 mit ai-mcp 1.1.1

Das ist der Teil, der leicht übersehen wird — und der Grund, warum ich das Adapter-Paket geprüft habe, statt beim Core stehen zu bleiben.

@tanstack/ai-mcp@1.2.0 wurde um 2026-11-09T18:04:08.072Z veröffentlicht — 18 Minuten und 40 Sekunden nach dem Core 1.4.0. Sein Diff gegen 1.1.1 berührt 15 veröffentlichte Pfade (19 inklusive Source Maps) und ergänzt die Wire-Seite: einen requestMetaParams()-Helper, der reservierte Keys herausfiltert und {} zurückgibt, wenn nichts übrig bleibt, einen meta-Parameter an callMcpTool(), options.meta an readResource(), getPrompt() und callTool(), sowie ein serverId-bewusstes readResource() am Pool. Außerdem hebt es seine Abhängigkeit von @tanstack/ai@^1.3.0 auf @tanstack/ai@^1.4.0 an.

Das heißt: Wer nur den Core installiert, bekommt einen getippten Hook, der nichts tut. Mit ai-mcp@1.1.1 noch im Baum akzeptiert das Typsystem requestMeta, der Hook läuft nie, und kein _meta erreicht den Server — ohne Fehlermeldung, nirgends. TypeScript warnt Sie nicht, und npm warnt Sie nicht, denn der Core hängt gar nicht von @tanstack/ai-mcp ab; die Abhängigkeit läuft in die andere Richtung.

Heben Sie beide gemeinsam an und verifizieren Sie per Assertion auf der Wire, nicht am Typ.

Welche AI-SaaS-Template-Fähigkeit dieses Release unterstützt

Das ist ein technisches Release — hier ist also die Kaufentscheidung, über die es tatsächlich Aufschluss gibt.

Multi-Tenant-Kontext auf einer gemeinsamen MCP-Verbindung

Jedes AI-SaaS-Produkt, das einen gemeinsamen MCP-Pool anbindet, läuft gegen dieselbe Wand: Die Verbindung ist warm und geteilt, sie kann keine Identität pro Anfrage tragen. Vor 1.4.0 blieben als Optionen eine frische Verbindung pro Anfrage (mit Latenz auf jedem Call) oder ein eigenes Header-Schema, das gegen den Pool arbeitet. Mit 1.4.0 plus ai-mcp@1.2.0 reisen Tenant-, User- und Trace-Identifikatoren mit jedem Tool-Call.

Das ist eine Template-Fähigkeit, kein Anwendungsdetail. Ein Starter, der MCP-Tool-Calls mitbringt, sollte auch pro-Anfrage-Kontext, Cancellation und einen tenant-bewussten Tool-Cache-Key mitliefern — sonst implementiert jeder Kunde dieselben drei Zeilen pro Route neu. Genau durch diese Brille ziehe ich meinen AI-SaaS-Boilerplate-Vergleich, und es ist eine Frage, die Sie jedem Anbieter stellen sollten: Leitet Ihre MCP-Schicht den Tenant weiter, und wo fließt der Tenant in den Tool-Cache-Key ein?

Welches Template zu diesem Use Case passt

Wenn Ihr Produkt ein AI-Chat mit Tools ist, lautet die relevante Frage nicht „welche SDK-Version“, sondern „welcher Starter pinnt und testet bereits eine bekannte gute @tanstack/ai-Version samt seinem MCP-Client“. Die AI Image Studio-Vorlage ist die nächste Referenzimplementierung für eine Media-Pipeline, und der komplette Template-Katalog deckt Chat-, RAG- und Agent-Produkte ab. Beide lohnen einen Preview-Blick, bevor Sie Ihren ersten Prompt-Handler schreiben.

Upgrade-Checkliste und Rollback-Plan

Nehmen Sie das als PR-Checkliste. Jede Zeile ist ein Gate.

Vor dem Mergen

  • Klären Sie, ob die App überhaupt MCP nutzt; falls nicht, ist das Upgrade kosmetisch.
  • Lesen Sie die 1.4.0-Release Notes auf GitHub auf Verhaltensänderungen, die die Typ-Oberfläche nicht zeigt.
  • Heben Sie @tanstack/ai und @tanstack/ai-mcp im selben Commit an.
  • Asserten Sie auf der Wire: Loggen Sie request.params._meta in einem Test-MCP-Server und bestätigen Sie, dass der Key ankommt.
  • Falls toolCacheMiddleware aktiv ist, nehmen Sie den Tenant vor dem Shippen in keyFn auf.
  • Verifizieren Sie, dass pnpm typecheck und die Test-Suite der AI-Routen bestehen — nicht nur der Smoke-Test.

Rollback

  • Halten Sie den vorherigen Lockfile-Commit erreichbar, damit das Upgrade ein einzelnes git revert bleibt.
  • Bei Cloudflare ist eine Workers-Version unveränderlich und aus dem Dashboard reversibel — wissen Sie, welche Version Sie wiederherstellen müssen.
  • Beobachten Sie rund um das Deployment Ihren Error-Tracker; ein Spike bei MCP-Tool-Fehlern ist das Frühsignal.
  • Löschen Sie die alte Lockfile nicht, bevor 1.4.0 Ihre gewohnte Zeitspanne in der Produktion gelaufen ist.

Grenzen, Offenlegung und wie Sie die Aussagen lesen sollten

Verwendete Aussage-Typen. Gemessen heißt: direkt aus den npm-Registry-Metadaten oder aus einem Diff zweier veröffentlichter Tarballs gelesen. Berechnet heißt: Rechenarbeit, die ich an diesen Dateien ausgeführt habe (das Delta von 6.994 Bytes, der Veröffentlichungsabstand von 18 Minuten 40 Sekunden, das Intervall von 4 Std. 36 Min. 57 s zwischen 1.3.0 und 1.4.0). Geschätzt heißt: mein Urteil. Nutzerbereitgestellt heißt: nichts — keine Metrik in diesem Beitrag stammt von einem Nutzer oder Kunden. Proxy heißt: eine Zahl, die für etwas steht, das ich nicht messen konnte; davon gibt es hier keine.

Was ich nicht getan habe. Ich habe 1.4.0 nicht in einer Produktionsanwendung betrieben. Ich habe zwei veröffentlichte Tarballs verglichen und die ausgelieferten Typdeklarationen und Quellen gelesen. Ich habe Streaming-Latenz, Token-Kosten oder _meta-Overhead nicht benchmarket und beanspruche keinerlei Verbesserung dort. Der Changelog-Text des 1.4.0-Upstream-Releases lag mir nicht vor; falls die Maintainer Laufzeitverhaltensänderungen ohne Typänderung ausgeliefert haben, zeigt dieser Leitfaden sie nicht — prüfen Sie die GitHub-Releases, bevor Sie deployen.

Dokumentationsstand. Zum 12. November 2026 decken die offiziellen MCP-Doku-Seiten requestMeta unter Managed MCP und Manual MCP ab, während die übergeordnete MCP-Tools-Seite es noch nicht erwähnt. Ich berichte die Doku, wie sie ist — nicht, wie ich sie mir wünsche.

Offenlegung. Ich betreue TanStack Ship, und die oben verlinkten Templates sind meine eigenen Produkte. Eine wesentliche Verbindung zum TanStack-Team habe ich nicht — ich bin Nutzer ihres SDK — und dieser Beitrag ist nicht gesponsert. Ihre Ergebnisse können je nach App, MCP-Server und Toolchain variieren.

FAQ

Was hat sich in @tanstack/ai 1.4.0 tatsächlich geändert? Ein Feature: ein pro-Anfrage-requestMeta-Hook für MCP. Der veröffentlichte Diff ändert 9 von 648 Dateien und ergänzt die Typen MCPRequestMeta und MCPRequestMetaInput plus ein optionales requestMeta in den MCP-Chat-Optionen und in den tools()-Optionen der MCP-Quelle. Die Export-Map und jeder Dependency-Range bleiben unverändert — kein Import-Pfad muss umgeschrieben werden.

Ist @tanstack/ai 1.4.0 ein Breaking Change? Es ist ein Minor-Version-Bump, und nichts im veröffentlichten Diff entfernt oder benennt eine bestehende API um. readResource() hat ein optionales zweites Argument bekommen, das mit Implementierungen kompatibel bleibt, die es ignorieren. Lesen Sie trotzdem die Upstream-Release-Notes: Mein Vergleich beschränkte sich auf die Typ-Oberfläche und die ausgelieferte Quelle.

Muss ich @tanstack/ai-mcp ebenfalls upgraden? Ja, wenn Sie MCP nutzen. Die _meta-Übertragung steckt in @tanstack/ai-mcp@1.2.0, veröffentlicht 18 Minuten nach dem Core. Mit ai-mcp@1.1.1 im Baum wird der Hook von den Typen akzeptiert, erreicht aber nie die Wire — ein stiller No-op, kein Fehler.

Verlangsamt requestMeta jeden Tool-Call? Ich habe es nicht gemessen und nenne daher keine Zahl. Was der ausgelieferte Code zeigt: Der Hook läuft einmal pro Anfrage beim Anfragenstart, und ein toolCacheMiddleware-Cache-Hit sendet keine Anfrage — der Hook wird also komplett übersprungen.

Wie verifiziere ich, dass der Tenant-Kontext wirklich ankommt? Asserten Sie auf der Wire, nicht auf den Typen: Loggen Sie request.params._meta in einem Test-MCP-Server-Handler und bestätigen Sie, dass Ihr Tenant-Key bei einem Tool-Call vorhanden ist und fehlt, wenn der Hook undefined zurückgibt.

Fazit und nächster Schritt

@tanstack/ai@1.4.0 ist ein schmales, risikoarmes Release, dessen gesamte Nutzlast pro-Anfrage-MCP-Kontext ist: 9 geänderte Dateien von 648, eine unveränderte Export-Map und ein neuer Hook, der einem gemeinsamen MCP-Pool erlaubt, Tenant-, User- oder Trace-Identität bei jedem Tool-Call mitzuführen. Das Risiko liegt nicht in der API — es liegt darin, den Core ohne @tanstack/ai-mcp@1.2.0 anzuheben, was das Feature still ungenutzt lässt.

Nächster Schritt: AI-SaaS-Boilerplates im direkten Vergleich ansehen und prüfen, welche pro-Anfrage-MCP-Kontext und tenant-bewusste Cache-Keys weiterleiten — danach einen Blick auf die AI Image Studio-Vorlage oder den kompletten Template-Katalog werfen, bevor Sie den ersten Prompt-Handler schreiben.

Weiterlesen: TanStack AI 1.2.0 Release Guide · TanStack AI 1.1.0 Release Guide · TanStack AI Effect Adapter