Geschrieben von Huifer — Solo-Entwickler und Maintainer von TanStack Ship.
Als npm
@tanstack/aiam 9. November 2026 um 17:45:28 UTC auflatestgesetzt 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/ai1.4.0 on npm · web.dev · Cloudflare Workers docsZuletzt 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.0veröffentlicht am2026-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/MCPRequestMetaInputplusrequestMetain 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-Zeitstempel | 2026-11-09T13:08:31.742Z | 2026-11-09T17:45:28.315Z |
| Beschreibung | "Type-safe TypeScript AI SDK for streaming chat, tool calling, agents, structured outputs, and multimodal generation." | unverändert |
| Lizenz | MIT | MIT |
| Engines | Node >=18 | Node >=18 |
| Peer-Dependency | @opentelemetry/api >= 1.9.0 | unverändert |
| Interne Dependencies | @tanstack/ai-utils@^1.1.0, @tanstack/ai-event-client@^1.0.1 | unverä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.0 | unverändert |
| Export-Subpaths | 10 (., ./byok, ./locks, ./client, ./testing, ./adapters, ./byok/server, ./middlewares, ./middlewares/otel, ./adapter-internals) | unverändert |
| Veröffentlichte Dateien / entpackte Bytes | 648 Dateien / 5.898.105 B | 648 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.ts | Neue 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.ts | Der Manager reicht requestMeta in jeden tools()-Aufruf jeder Quelle und in die gebundene readResource-Closure durch |
src/index.ts | Exportiert die beiden neuen Typen aus dem Paket-Root |
dist/esm/** + package.json | Kompilierte 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
methodundserverId; eintools/callträgt zusätzlichtoolNameundargs, einresources/readträgturi. In einem Pool istserverIdder Config-Key. - Geben Sie
undefinedzurück, um kein_metazu senden. - Der Client entfernt die von MCP reservierten Keys:
progressTokensowie Präfixe wieio.modelcontextprotocol/odermcp.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. _metaist nicht Teil destoolCacheMiddleware-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:
// @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:
// 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:
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:
| Paketmanager | Befehl |
|---|---|
| npm | npm install @tanstack/ai@1.4.0 @tanstack/ai-mcp@1.2.0 |
| pnpm | pnpm add @tanstack/ai@1.4.0 @tanstack/ai-mcp@1.2.0 |
| yarn | yarn add @tanstack/ai@1.4.0 @tanstack/ai-mcp@1.2.0 |
# 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/aiund@tanstack/ai-mcpim selben Commit an. - Asserten Sie auf der Wire: Loggen Sie
request.params._metain einem Test-MCP-Server und bestätigen Sie, dass der Key ankommt. - Falls
toolCacheMiddlewareaktiv ist, nehmen Sie den Tenant vor dem Shippen inkeyFnauf. - Verifizieren Sie, dass
pnpm typecheckund 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 revertbleibt. - 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