Written by Huifer — solo developer and maintainer of TanStack Ship.
When npm moved
@tanstack/aitolatestat 17:45:28Z on 2026-11-09, I did what I do for every dependency bump in my own templates: pull both published tarballs — 1.3.0 and 1.4.0 — and diff the shipped type declarations instead of trusting a release summary. The diff was 9 files out of 648, and it told a far more specific story than "AI SDK update": 1.4.0 is the release that lets a single MCP request carry its own context.Verified sources: TanStack AI docs · TanStack · TanStack AI on GitHub ·
@tanstack/ai1.4.0 on npm · web.dev · Cloudflare Workers docsLast updated: 2026-11-12
TanStack AI 1.4.0 shipped one user-facing feature: per-request MCP _meta. The npm registry shows @tanstack/ai@1.4.0 published at 2026-11-09T17:45:28.315Z and carrying the latest dist-tag. Diffing the published tarball against 1.3.0 shows 9 changed files out of 648, and the entire delta is a new requestMeta hook that lets each MCP tool call and each ui:// resource read send its own _meta — tenant, user, or trace context — to the MCP server. This guide covers what changed, how to upgrade, and the one dependency you must bump with it.
TL;DR
- Measured:
@tanstack/ai@1.4.0published 2026-11-09T17:45:28.315Z, 4 h 36 min 57 s after 1.3.0.- Measured: 9 of 648 published files changed; unpacked size moved 5,898,105 → 5,905,099 bytes (+6,994 B, +0.12%).
- Measured: the only new public API is
MCPRequestMeta/MCPRequestMetaInputplusrequestMetaon the MCP chat options.- Measured: the wire side lives in
@tanstack/ai-mcp@1.2.0, published 18 min 40 s after the core — core 1.4.0 alone sends no_meta.- My call: a low-risk bump for anyone not using MCP; a required bump for multi-tenant apps that share one MCP pool.
- Buyer decision: compare AI SaaS boilerplates side by side to see which starters already ship per-request MCP context.
Definition: @tanstack/ai@1.4.0 is the November 2026 release of TanStack's type-safe AI SDK that adds a requestMeta hook to MCP chat runs, so each tool call and ui:// resource read can carry its own _meta — tenant, user, or trace context — to the MCP server.
What @tanstack/ai 1.4.0 actually ships: the verified record
I split this section into what the registry proves and what the tarball diff proves, because a release note that mixes the two is where upgrade plans go wrong.
The registry facts
Every row below is read from the npm registry record for 1.4.0. The 1.3.0 column is the same file read at the same depth, so the deltas are comparable.
| Registry field | @tanstack/ai@1.3.0 | @tanstack/ai@1.4.0 |
|---|---|---|
| Publish timestamp | 2026-11-09T13:08:31.742Z | 2026-11-09T17:45:28.315Z |
| Description | "Type-safe TypeScript AI SDK for streaming chat, tool calling, agents, structured outputs, and multimodal generation." | unchanged |
| License | MIT | MIT |
| Engines | Node >=18 | Node >=18 |
| Peer dependency | @opentelemetry/api >= 1.9.0 | unchanged |
| Internal deps | @tanstack/ai-utils@^1.1.0, @tanstack/ai-event-client@^1.0.1 | unchanged |
| External deps | @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 | unchanged |
| Export subpaths | 10 (., ./byok, ./locks, ./client, ./testing, ./adapters, ./byok/server, ./middlewares, ./middlewares/otel, ./adapter-internals) | unchanged |
| Published files / unpacked bytes | 648 files / 5,898,105 B | 648 files / 5,905,099 B |
Two rows decide the risk profile. The export map did not change, so no import path in your app needs rewriting. And no dependency range moved, so the resolution graph of your install is identical to 1.3.0 — this is not the release that can break your lockfile.
The 9-file diff
The tarball diff is where the actual story is. Four of the nine changed paths are compiled .js/.js.map artifacts; three are the TypeScript sources they were built from, and one is the version field in package.json.
| Changed path (1.3.0 → 1.4.0) | What changed |
|---|---|
src/activities/chat/mcp/types.ts | New MCPRequestMeta and MCPRequestMetaInput types; requestMeta added to the source tools() options; readResource() gains an optional second argument |
src/activities/chat/mcp/manager.ts | The manager threads requestMeta into every source's tools() call and into the bound readResource closure |
src/index.ts | Exports the two new types from the package root |
dist/esm/** + package.json | Compiled output of the above, plus the version bump to 1.4.0 |
Nothing else in the package moved. That is a deliberately narrow release: one hook, one union type, one optional parameter.
The one feature that shipped: per-request MCP _meta
The use case is worth stating before the API, because it determines whether you need this release at all.
How the hook actually runs
The official docs describe it under "Send request context to MCP servers" in the managed MCP guide. The problem it solves: a shared MCP pool connects once, so its headers are identical for every request. If each request belongs to a different tenant, a header cannot carry that context — but _meta travels with the individual request, on every transport.
The documented behaviour:
- The hook runs once per MCP request, when the request starts. Tool discovery does not call it.
- It receives
methodandserverId; atools/callalso carriestoolNameandargs, aresources/readcarriesuri. In a pool,serverIdis the config key. - Return
undefinedto send no_meta. - The client strips the keys MCP reserves:
progressToken, and prefixes likeio.modelcontextprotocol/ormcp.dev/. - If the hook throws, only that request fails — a tool call is sent to the model as a tool error, and a
ui://read simply produces no widget. _metais not part of thetoolCacheMiddlewarekey, so a cache hit sends no request and the hook never runs.
That last point is the trap I would flag to anyone reviewing this in production: if tenants share one cache storage, the tenant has to be part of keyFn, or one tenant's cached tool result can be served to another.
What the type surface looks like
The shipped declarations in 1.4.0 are a discriminated union plus a function type. From the published dist/esm/activities/chat/mcp/types.d.ts:
// @tanstack/ai@1.4.0 — published type surface (verbatim shape)
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>
Used at the chat run level, per the official docs:
// Per-request context on a shared 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,
},
})
The serverId === 'internal' check is the multi-tenant pattern: one pool, several servers, and context forwarded only to the server that is allowed to see it. The same hook is available one level down — mcp.tools({ requestMeta }) — for apps that manage tools manually, as shown in the manual MCP guide.
How to upgrade to 1.4.0
Check what you actually have
Start by looking at the resolved tree rather than your package.json range:
npm ls @tanstack/ai @tanstack/ai-mcp
npm view @tanstack/ai dist-tags
npm view @tanstack/ai-mcp dist-tags
If your app does not use MCP at all, 1.4.0 is inert for you and the decision is simply "take it or leave it". If it does use MCP, the second line matters more than the first.
Install the pinned pair
Pin exact versions so CI and teammates resolve the same tarball:
| Package manager | Command |
|---|---|
| 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 |
# Install, then confirm the lockfile resolved what you meant
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
The silent-failure case: core 1.4.0 with ai-mcp 1.1.1
This is the part that is easy to miss, and it is why I checked the adapter package instead of stopping at the core.
@tanstack/ai-mcp@1.2.0 was published at 2026-11-09T18:04:08.072Z — 18 minutes and 40 seconds after the core 1.4.0. Its diff against 1.1.1 touches 15 published paths (19 including source maps) and adds the wire side: a requestMetaParams() helper that filters reserved keys and returns {} when nothing survives, a meta parameter on callMcpTool(), options.meta on readResource(), getPrompt() and callTool(), and a serverId-aware readResource() on the pool. It also moves its dependency from @tanstack/ai@^1.3.0 to @tanstack/ai@^1.4.0.
So: installing the core alone gives you a typed hook that does nothing. With ai-mcp@1.1.1 still in the tree, requestMeta is accepted by the type system, the hook never runs, and no _meta reaches the server — with no error anywhere. TypeScript will not warn you, and npm will not warn you, because the core does not depend on @tanstack/ai-mcp at all; the dependency runs the other way.
Bump them together, and verify by asserting on the wire, not on the type.
Which AI SaaS template capability this release supports
This is a technical release, so here is the buyer decision it actually informs.
Multi-tenant context on a shared MCP connection
Every AI SaaS product that connects a shared MCP pool hits the same wall: the connection is warm and shared, so it cannot carry per-request identity. Before 1.4.0, the options were a fresh connection per request (paying latency on every call) or a custom header scheme that fights the pool. With 1.4.0 plus ai-mcp@1.2.0, the tenant, user, and trace identifiers travel with each tool call.
That is a template capability, not an application detail. A starter that ships MCP tool calling should also ship per-request context, cancellation, and a tenant-aware tool cache key — otherwise every customer re-implements the same three lines per route. That is the specific lens I use when I compare AI SaaS boilerplates side by side, and it is a question worth asking any seller: does your MCP layer forward the tenant, and where does the tenant enter the tool cache key?
Which template fits this use case
If your product is an AI chat with tools, the relevant question is not "which SDK version" but "which starter already pins and tests a known-good @tanstack/ai version with its MCP client". The AI Image Studio template is the closest reference implementation for a media-style pipeline, and the full template catalog covers the chat, RAG, and agent-shaped products. Both are worth previewing before you write your first prompt handler.
Upgrade checklist and rollback plan
Use this as the PR checklist. Each line is a gate.
Before merging
- Confirm whether the app uses MCP at all; if not, the upgrade is cosmetic.
- Read the 1.4.0 release notes on GitHub for behaviour changes the type surface does not show.
- Bump
@tanstack/aiand@tanstack/ai-mcpin the same commit. - Assert on the wire: log
request.params._metain a test MCP server and confirm the key arrives. - If
toolCacheMiddlewareis enabled, put the tenant inkeyFnbefore shipping. - Verify
pnpm typecheckand the AI route test suite pass, not just the smoke test.
Rollback
- Keep the previous lockfile commit reachable so the upgrade is one
git revert. - On Cloudflare, a Workers version is immutable and reversible from the dashboard — know which version to restore.
- Watch your error tracker around the deploy; a spike in MCP tool errors is the early signal.
- Do not delete the old lockfile until 1.4.0 has soaked in production for your usual window.
Limitations, disclosure, and how to read the claims
Claim types used here. Measured means read directly from the npm registry metadata or from a diff of two published tarballs. Calculated means arithmetic I performed on those files (the 6,994-byte delta, the 18-minute-40-second publish gap, the 4 h 36 min 57 s gap between 1.3.0 and 1.4.0). Estimated means my judgment. User-provided means nothing — no metric in this post came from a user or a customer. Proxy means a number standing in for something I could not measure; there are none here.
What I did not do. I did not run 1.4.0 in a production application. I compared two published tarballs and read the shipped type declarations and source. I did not benchmark streaming latency, token cost, or _meta overhead, and I claim no improvement in those. The upstream 1.4.0 changelog body was not available to me, so if the maintainers shipped runtime behaviour changes with no type change, this guide will not show them — check the GitHub releases before you ship.
Documentation state. As of 2026-11-12 the official MCP docs pages cover requestMeta under managed MCP and manual MCP, while the top-level MCP tools page does not mention it yet. I am reporting the docs as they are, not as I wish they were.
Disclosure. I maintain TanStack Ship, and the templates linked above are my own products. I have no material connection to the TanStack team beyond being a user of their SDK, and this post is not sponsored. Your results may vary with your app, your MCP server, and your toolchain.
FAQ
What actually changed in @tanstack/ai 1.4.0? One feature: a per-request requestMeta hook for MCP. The published diff changes 9 of 648 files and adds the MCPRequestMeta and MCPRequestMetaInput types, plus an optional requestMeta on the MCP chat options and on the MCP source tools() options. The export map and every dependency range are unchanged, so no import path needs rewriting.
Is @tanstack/ai 1.4.0 a breaking change? It is a minor version bump, and nothing in the published diff removes or renames an existing API. readResource() gained an optional second argument, which stays compatible with implementations that ignore it. Read the upstream release notes anyway: my comparison was limited to the type surface and shipped source.
Do I need to upgrade @tanstack/ai-mcp as well? Yes, if you use MCP. The _meta transmission is implemented in @tanstack/ai-mcp@1.2.0, published 18 minutes after the core. With ai-mcp@1.1.1 in the tree, the hook is accepted by the types but never reaches the wire — a silent no-op, not an error.
Does requestMeta slow down each tool call? I did not measure it, so I will not put a number on it. What the shipped code shows is that the hook runs once per request when the request starts, and that a toolCacheMiddleware cache hit sends no request and therefore skips the hook entirely.
How do I verify the tenant context actually arrives? Assert on the wire, not on the types: log request.params._meta inside a test MCP server handler and confirm your tenant key is present for a tool call, and absent when the hook returns undefined.
Conclusion and next step
@tanstack/ai@1.4.0 is a narrow, low-risk release whose entire payload is per-request MCP context: 9 files changed out of 648, an unchanged export map, and one new hook that lets a shared MCP pool carry tenant, user, or trace identity on every tool call. The risk is not in the API — it is in bumping the core without @tanstack/ai-mcp@1.2.0, which leaves the feature silently inert.
Next step: compare AI SaaS boilerplates side by side and check which ones forward per-request MCP context and tenant-aware cache keys — then preview the AI Image Studio template or browse all templates before you write the first prompt handler.
Related reading: TanStack AI 1.2.0 Release Guide · TanStack AI 1.1.0 Release Guide · TanStack AI Effect Adapter