* fix(typescript): truncate landing page hero URL instead of overflowing past copy button (#2313)
* docs: add Scalekit provider sidebar logo (#2306)
The other first-class providers use a custom SVG. shield-halved did not
render in the Mintlify sidebar.
* fix(typescript): truncate landing page hero URL instead of overflowing past copy button
On narrow (mobile) viewports the server URL is an unbreakable string
that overflowed the pill-shaped box and reappeared beyond the copy
button. The hero .url-box now truncates with an ellipsis, keeping the
full URL available via the copy button.
---------
Co-authored-by: saif-at-scalekit <saif.shaik@scalekit.com>
* chore: enter canary prerelease mode
* chore(typescript): version packages (canary)
* feat(inspector): export connection settings form (#2318)
* chore(typescript): version packages (canary)
---------
Co-authored-by: Marcin Zajkowski <zajkowski.dev@gmail.com>
Co-authored-by: saif-at-scalekit <saif.shaik@scalekit.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
* docs: add Scalekit provider sidebar logo (#2306)
The other first-class providers use a custom SVG. shield-halved did not
render in the Mintlify sidebar.
* fix(typescript): truncate landing page hero URL instead of overflowing past copy button
On narrow (mobile) viewports the server URL is an unbreakable string
that overflowed the pill-shaped box and reappeared beyond the copy
button. The hero .url-box now truncates with an ellipsis, keeping the
full URL available via the copy button.
---------
Co-authored-by: Marcin Zajkowski <zajkowski.dev@gmail.com>
Co-authored-by: saif-at-scalekit <saif.shaik@scalekit.com>
* fix(agent): count Anthropic cache tokens and stop message_delta erasing usage (#2127)
* fix(agent): count Anthropic cache tokens and stop message_delta erasing usage
Two counting bugs on the Anthropic path, both silent.
Anthropic reports `input_tokens` net of the prompt cache and bills
`cache_read_input_tokens` and `cache_creation_input_tokens` separately, so
`input_tokens + output_tokens` is not what the call is charged on. It never sends
`total_tokens`, so the computed branch is always the one that runs. A call billed on
21,623 tokens reported 123. `cache_creation_input_tokens` was not read anywhere in the
repository, and Anthropic bills cache writes above the base rate.
OpenAI is the opposite: its `cached_tokens` sits inside `prompt_tokens`, so adding it
would double count. Only the Anthropic-shaped keys are summed, and a test pins that.
Second, `tokenUsageFromRecord` returns every key and sets the ones it did not find to
`undefined`. Anthropic's streaming `message_delta` carries `output_tokens` only, so
`usage = { ...usage, ...deltaUsage }` overwrote `inputTokens` and `cachedInputTokens`
with `undefined`, discarding what `message_start` had already reported. After any
streamed call the whole input side of the accounting was gone, with nothing raised.
`mergeTokenUsage` merges only defined values. It does not touch `totalTokens`, because
whether a cache counter is additive is a provider question and that information is gone
once usage has been normalised, so the caller owns the total.
Three of the added tests fail on main.
* fix(agent,inspector): one owner for the Anthropic total, and stop the inspector dropping cache
Follow-up on the review. Four points were raised; three were right and are fixed, one
would have introduced a bug and the reasoning is below.
The same wrong total existed in a third place. `message_stop` recomputed it as
`inputTokens + outputTokens`, so the fix at `message_delta` survived only because `??`
short-circuited on the total already set. Two places knowing how Anthropic bills is how
this drifts, so `message_stop` now owns it alone and `message_delta` just merges. Added an
end-to-end test that drives real `message_start` then `message_delta` SSE through
`streamChat`, rather than exercising `mergeTokenUsage` in isolation. On the base commit it
reports `totalTokens: undefined`, not merely a wrong number, because the input counters
were gone by the time `message_stop` ran.
The inspector was dropping more than the new field. `InspectorTokenUsage` declares
`cachedInputTokens` and `reasoningTokens`, the trace view reads them, and
`inspectorTokenUsageFromUnknown` returned only `inputTokens`, `outputTokens` and
`totalTokens`. Both have always rendered as absent whatever the provider sent. It also
repeated the same input-plus-output total. Both fixed, and `cacheCreationInputTokens` is
carried through.
The merge test now seeds `cache_creation_input_tokens` too, since cache writes are billed
above base rate and need the same protection as cache reads.
Not done, deliberately: adding `cachedInputTokens` to the computed total inside
`tokenUsageFromRecord`. On Anthropic that counter sits outside `input_tokens`; on OpenAI
`cached_tokens` sits inside `prompt_tokens`. Once usage is normalised that distinction is
gone, so summing it would double count OpenAI. Only the Anthropic-shaped keys are added,
and a test pins the OpenAI case at 14.
* style(inspector): run prettier on trace.ts
format:check fails the typescript-lint job on this one file. Prettier wraps
the cachedInputTokens call across three lines, the way the two calls below it
already are. Formatting only, no behaviour change.
* fix(inspector): aggregate cacheCreationInputTokens and stop double-counting OpenAI cache reads
Addresses @khandrew1's review on #2127.
addUsage dropped cacheCreationInputTokens: the field was parsed onto individual
usage events but never summed, so it vanished from state.usage, the LLM span's
usage, and the aggregate tokenUsage in the raw-chat payload. It is now summed
alongside the other counters.
The fallback total could also over-count. uncountedCache was built from the
provider-neutral cachedInputTokens, but on OpenAI those tokens are already inside
inputTokens, so { inputTokens: 10, outputTokens: 4, cachedInputTokens: 3 }
totalled 17 instead of 14. The total now adds only the Anthropic-shaped
cache_read_input_tokens, mirroring the provider-safe path in agent/src/llm/usage.ts.
cachedInputTokens is still parsed and returned for observability.
Two tests in trace.test.ts pin both: the OpenAI-vs-Anthropic total distinction,
and that cacheCreationInputTokens survives aggregation and the LLM span. Changesets
added for @mcp-use/agent and @mcp-use/inspector.
* chore: enter canary prerelease mode
* chore(typescript): version packages (canary)
* fix(inspector): scope loading state by chat session (#2232)
* fix(inspector): give each chat session one id and one state record
Chat state lived in hook-wide React state, so starting a new chat cleared
the values an in-flight stream was still writing to: the fresh chat
inherited the previous session's loading state and could not send.
Rework it around a single identity. A session is created with one id and
keeps it; that id is handed to ChatStorageProvider.createChat, so runtime
state, chat history and OAuth retry all name the same chat. All of a
session's state and turn machinery live in one record inside
ChatSessionStore, which notifies only the subscribers of the session that
changed, so a background turn keeps streaming into its own record.
useChatSessions owns the lifecycle: minting ids, activating a session,
reattaching to persisted chats, and reopening the session a full-page
OAuth redirect interrupted. New Chat now only switches the active id.
Closes#2217
* refactor(inspector): simplify chat session state
* fix(inspector): harden chat session recovery
---------
Co-authored-by: Andrew Khadder <andrew@manufact.com>
* chore(typescript): version packages (canary)
* fix(ci): give inspector tests the same timeout as every other package (canary) (#2290)
* fix(ci): give inspector tests the same timeout as every other package
Same one-line change as #2268, which targets main. canary carries the same
10s cap and is failing on it independently:
run 32053629834 compressed-assets.test.ts 10230ms Test timed out in 10000ms
run 32051250836 same test
main is red on it too (run 32054211669). Recent margins are 10029ms, 10230ms
and 10837ms, all just over the cap.
The inspector is the only package at 10s; agent, client, cli and server all
use 60000, and these cases mount a server and decompress the bundled app.
45 files, 217 tests still pass locally.
* chore(ci): remove timeout rationale comment
---------
Co-authored-by: Andrew Khadder <andrew@manufact.com>
* feat(oauth): add Scalekit provider (#2272)
* feat(oauth): add Scalekit provider
Add oauthScalekitProvider next to Auth0 and Clerk. The verifier accepts
both environment-root and resource-scoped issuers, binds audience to the
res_… resource id, and advertises DCR plus CIMD. No Scalekit SDK.
* fix(oauth): keep Scalekit resource-id audience with extra aud
Always verify aud includes the resource id. Optional audience is an extra
AND check, not a replacement. Drop the new v1 provider page.
* fix(oauth): drop Scalekit issuerBoundAccessTokens option
Scalekit binds tokens to the resource id. The dashboard will own
that opt-in. Keep the static oauthMetadata copy because mcp-use
requires it. Custom claims stay on ctx.auth.payload.
* docs: drop v1 and legacy skill changes
* docs: fix Scalekit environment variables
---------
Co-authored-by: Saif Shines <saifshine7@gmail.com>
Co-authored-by: Andrew Khadder <andrew@manufact.com>
* chore(typescript): version packages (canary)
* fix(inspector): add a test script so pnpm test covers this package (#2289)
* fix(inspector): add a test script so pnpm test covers this package
The root test script is `pnpm run -r test`, and the inspector only had
test:unit. pnpm skips a package with no matching script and reports nothing,
so 217 unit tests were absent from the workspace-wide run:
$ pnpm --filter @mcp-use/inspector test
(no output)
$ pnpm --filter @mcp-use/inspector test:unit
Test Files 45 passed (45)
Tests 217 passed (217)
CI is unaffected; its step calls test:unit directly. This is the documented
`pnpm test` contributors run.
Uses run mode rather than watch, matching tunnel, so a recursive run cannot
sit waiting on a watcher.
* chore(inspector): remove test-only changeset
---------
Co-authored-by: Andrew Khadder <andrew@manufact.com>
* fix(types): align pnpm workspace tooling (#2301)
* docs: update TypeScript release changelogs
* fix(inspector): use secure chat session ids
---------
Co-authored-by: Arthi Arumugam <62213284+arthi-arumugam-git@users.noreply.github.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: Mert Çetin <97505365+merttcetn@users.noreply.github.com>
Co-authored-by: Ayaan Gazali <ayaangazali.work@gmail.com>
Co-authored-by: saif-at-scalekit <saif.shaik@scalekit.com>
Co-authored-by: Saif Shines <saifshine7@gmail.com>
* docs(skills): drop baseUrl from the openapi-to-mcp server config
The skills rewrite in #2286 did not reach this one. MCPServer still rejects
baseUrl on current main:
error TS2353: Object literal may only specify known properties,
and 'baseUrl' does not exist in type 'ServerConfig<never>'.
The skill also says the scaffold provides that field; it does not, the
create-mcp-use-app template sets name, title, version and description.
Unrelated and left alone: MCPServer.fromOpenAPI() does accept baseUrl
(FromOpenAPIOptions), so the advanced-features references are correct.
* Apply suggestion from @cubic-dev-ai[bot]
Co-authored-by: cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com>
Signed-off-by: Andrew Khadder <54488379+khandrew1@users.noreply.github.com>
* Apply suggestion from @cubic-dev-ai[bot]
Co-authored-by: cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com>
Signed-off-by: Andrew Khadder <54488379+khandrew1@users.noreply.github.com>
---------
Signed-off-by: Andrew Khadder <54488379+khandrew1@users.noreply.github.com>
Co-authored-by: Andrew Khadder <54488379+khandrew1@users.noreply.github.com>
Co-authored-by: cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com>
The guide hand-rolled a verifier with jose: signature and issuer checks, sub
and exp guards, scope splitting, client_id/azp fallback, and the resource
binding. That is 33 lines of security-sensitive code for readers to copy and
get right.
#2234 exported createJwtVerifier, which is the helper the six built-in
providers already use and does all of it. Show that instead, and keep the
hand-written path documented for providers that do not issue JWTs.
The step ran `pnpm --filter mcp-use --if-present test:unit`, but the mcp-use
package has no test:unit script, so --if-present turned it into a silent pass
and 447 tests never ran.
Point it at test:run, which is the script that exists and the same one the
client step above already uses.
Two failures were hiding behind the skip:
- usage.test.ts asserted telemetry was sent, but the step sets
MCP_USE_ANONYMIZED_TELEMETRY=false, which short-circuits recordUsage. Those
cases are about identity persistence, not the opt-out, so capture() now sets
the variable itself. The file already tracks and restores it in afterEach.
- budgets/runtime-boundary.test.ts compared the builtin list with toEqual, so
it depended on module resolution order between node:process and node:http.
Sorted, which is what the case means by "loads only".
Verified with the step's own env: MCP_USE_ANONYMIZED_TELEMETRY=false
pnpm --filter mcp-use test:run gives 43 files, 447 passed, exit 0.
Closes#2203
The package has 25 vitest cases under src/__tests__, and no workflow ran
them. create-mcp-use-app-build builds and packs, and create-app-tests only
scaffolds a project with each package manager and checks the files exist.
Add the step to the build job, which already installs and builds, so the
unit tests run before the artifact is packed.
Verified: pnpm --filter create-mcp-use-app test gives 2 files, 25 passed.
The "Run Inspector Tests" step calls `--if-present test`, but
@mcp-use/inspector has no `test` script, only `test:unit`. With
--if-present a missing script is a silent success, so the step has been
passing without running anything while 159 unit tests sat unexecuted.
Points it at test:unit, matching the sibling steps for mcp-use and
@mcp-use/agent. Dropped --if-present since the script exists and a
missing one should fail rather than pass quietly.
* fix: restore Vibe apps and HMR (#2229)
* chore: enter canary prerelease mode
* chore(typescript): version packages (canary)
* fix(cli): route Vibe HMR through public origin
* chore(typescript): version packages (canary)
* fix(cli): prebundle the Vibe view runtime (#2236)
* fix(cli): prebundle the Vibe view runtime
* test(cli): update view optimizer contract
* fix(cli): skip view optimization for tool-only dev
* chore(typescript): version packages (canary)
* fix(cli): prebundle Zod for Vibe views
* chore(typescript): version packages (canary)
* fix(cli): ignore Vibe dev server logs in HMR (#2238)
* chore(typescript): version packages (canary)
* fix(oauth): restore zero-config provider environment variables (#2241)
* fix(oauth): restore v1 environment contract
* chore: add OAuth environment changeset
* chore(typescript): version packages (canary)
* fix(client): replay tool state after guest reinitializes (#2240)
* chore(typescript): version packages (canary)
* fix(ci): clear the knip findings failing canary (#2235)
* fix(ci): clear the knip findings failing canary
typescript-knip has been red on canary, so every PR against it shows the
failure. The job reports seven items.
Three exported types nothing imports. Each is used only inside its own
module, as a return type or parameter, so the export keyword was doing
nothing. Dropped it.
Four stale knip.json entries. test_app is a scaffold output directory that
no longer exists, and the three cli ignoreDependencies are detected properly
now, which is why knip asks for them to be removed.
Build passes, so nothing depended on those type exports for declaration
emit.
* fix(ci): clear the two knip findings that landed with #2216
Canary moved while this PR was open. #2216 added an inspector test that opts
into jsdom via a @vitest-environment pragma without the package declaring
jsdom, and an exported reconnect storage key that is only read inside its own
module.
Declare jsdom in the inspector devDependencies, matching the ^27.0.0 the
client package already uses, and drop the unused export.
* chore(typescript): version packages (canary)
* fix(inspector): ship embedded theme styles (#2243)
* chore(typescript): version packages (canary)
* feat(inspector): expose CSP audit to Vibe agents (#2244)
* fix(create-app): preserve canary skill channel (#2245)
* fix(release): move SDK changesets into workspace (#2246)
* chore(typescript): version packages (canary)
* feat(server): export createJwtVerifier from mcp-use/oauth (#2234)
The oauth entry point exports oauthCustomProvider so consumers can build a
custom OAuth provider, but not createJwtVerifier, so anyone doing that had to
reimplement signature, issuer, audience and expiry checking that all six
built-in providers already share.
Export it along with JwtVerifierOptions and VerifiedPayload, and drop the
@internal tags now that they are public. Documented the option properties,
which the package requires for public exports.
Closes#2215
* chore(typescript): version packages (canary)
---------
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: Andrew Khadder <54488379+khandrew1@users.noreply.github.com>
Co-authored-by: Ayaan Gazali <ayaangazali.work@gmail.com>
* feat(client): support mixed OAuth servers
* fix(inspector): pause mixed-auth tool calls
* Revert "fix(inspector): pause mixed-auth tool calls"
This reverts commit 9bac9ddfe7.
* chore: finalize mixed OAuth changeset
* docs: explain mixed OAuth client flows
* fix: bound mixed auth metadata discovery
* docs(server): add runnable mixed oauth example
* fix(inspector): recover stale local connections
* fix(inspector): resume tools after mixed auth
* fix: address mixed auth review feedback
* fix(inspector): scope mixed auth retries
* test(inspector): remove jsdom-only regressions
* chore: enter canary prerelease mode
* chore(typescript): version packages (canary)
* fix(inspector): stream v2 subscription acknowledgements
* fix(client): discover mixed auth after ready
* test(client): preserve mocked connection compatibility
* fix(client): defer mixed auth discovery until ready
* fix(client): discover mixed auth after ready paint
* perf(client): expose tools before auxiliary inventories
* fix(client): refresh mixed auth discovery after reconnect
* chore(typescript): version packages (canary)
* fix(client): make codeMode custom executor functions actually work (#2123)
* fix(client): make codeMode custom executor functions actually work
`_ensureCodeExecutor()` handled a function-valued `codeMode.executor` by
assigning `this._customCodeExecutor` and then throwing
"Custom executor function should be handled in executeCode". Since
`executeCode()` read that field *before* calling `_ensureCodeExecutor()`,
and only `_ensureCodeExecutor()` ever populated it, the first
`executeCode()` call always rejected and only the second succeeded.
`searchTools()` had no such fallback, so it rejected on every call --
including via the `search_tools` meta tool on `CodeModeConnector`. Because
`_codeExecutor` stayed null, `close()` also skipped executor cleanup.
Route function executors through a new `FunctionCodeExecutor` adapter so
they participate in the normal executor lifecycle, and drop the now-unused
`_customCodeExecutor` field and its pre-check in `executeCode()`.
Also fix `detail_level` validation in `CodeModeConnector.callTool`: it
used `detailLevel in ["names", "descriptions", "full"]`, and `in` tests
property keys, so an array literal only has `"0"`/`"1"`/`"2"`/`"length"`.
Every valid detail level failed the guard and was silently rewritten to
`"full"`, so an agent requesting `"names"` received full input schemas for
every tool. Replaced with a `Set` membership test.
Adds 10 unit tests: first-call success, timeout forwarding, `searchTools`,
`close()` cleanup, the `BaseCodeExecutor` instance path, each valid
`detail_level`, and the unknown/omitted fallbacks.
Closes#2122
* fix(client): preserve `this` for custom executors, tighten tests, document the contract
Addresses review feedback on the code-mode custom-executor fix.
The `this` binding regression is real -- I measured it both ways. On the
pre-fix code the executor function was invoked as
`this._customCodeExecutor(code, timeout)`, so a non-arrow function saw the
`MCPClient` as its `this`; through the new adapter it saw the
`FunctionCodeExecutor`. `FunctionCodeExecutor.execute` now calls
`this.fn.call(this.client, ...)` so a `function`-form executor keeps the same
context it had before, and a test asserts it.
Two tests were weaker than their titles claimed:
- the `searchTools` test ran against an empty client, so it only proved the
call did not throw. It now registers a stub session with one tool and
asserts the full `{ meta, results }` payload, including the namespace and
the tool's `input_schema`.
- the `close()` test only asserted the promise resolved, which would pass
even if cleanup were skipped. It now spies on the resolved executor's
`cleanup()` and asserts it ran exactly once.
Documentation: the API reference listed one "Custom" executor row saying to
implement `execute()` + `cleanup()`, which is only true for the
`BaseCodeExecutor` subclass form. Split it into separate class and function
rows, add the `CodeExecutorFunction` signature to the types block, and add a
worked example to the code-mode guide (current and v2) stating the `this`
context and that the function owns its runtime cleanup.
* docs(client): use a non-arrow custom executor in the code-mode example
The example demonstrated the documented `this` context with an arrow function,
which has lexical `this` and therefore cannot observe it. Switched to
`async function (this: MCPClient, code, timeout)` and had it actually call
`this.getServerNames()`, so the snippet exercises the contract it describes.
Type-checked the snippet shape against the real `MCPClient` type with
`tsc --noEmit` before committing.
Also reworded the surrounding paragraph: the `this` binding is specific to the
non-arrow form, whereas the cleanup-ownership rule applies to every custom
function.
* docs(client): drop v1 code-mode custom executor docs
This change is v2-only; keep the custom-executor contract on the v2 docs path.
* chore(typescript): version packages (canary)
* fix(create-app): sanitize the npm name for named projects, not just "." (#2209)
deriveProjectInfo only ran sanitizePackageName on the "." branch. A named
project passed the raw argument straight through as packageName, which is
then written into package.json and substituted into the template's index.ts.
The CLI rejects path separators, ".." and a few protected names, but not
spaces, quotes or capitals, so `create-mcp-use-app 'My "App"'` emitted
`name: "My "App""` in index.ts, which is not valid TypeScript.
Sanitize on both branches. The directory still uses the name as typed.
* chore(typescript): version packages (canary)
* fix: enable skills tab after HMR (#2220)
* chore(typescript): version packages (canary)
* fix(create-app): strip leading underscores when sanitizing a package name (#2221)
sanitizePackageName removed leading dots and dashes but not underscores, so
create-mcp-use-app _foo wrote "name": "_foo" into package.json.
npm publish rejects that outright:
npm error code EINVALIDPACKAGENAME
npm error Invalid package name "_foo": name cannot start with an underscore.
Widen the leading-character class to [._-] and cover both the sanitizer and a
named project starting with an underscore.
Closes#2219
* chore(typescript): version packages (canary)
* fix(client): surface auth for protected operations
* fix(inspector): resume mixed-auth chat tools (#2226)
* chore(typescript): version packages (canary)
* fix: harden stable mixed-auth flows
---------
Co-authored-by: Enrico <2827496+tonxxd@users.noreply.github.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: LHMQ878 <72402929@cityu-dg.edu.cn>
Co-authored-by: Ayaan Gazali <ayaangazali.work@gmail.com>
The skills auth references pointed at
libraries/typescript/packages/mcp-use/examples/server/oauth/<provider>,
which is the deleted v1 package path. Those examples live at
libraries/typescript/packages/server/examples/auth/<provider> in v2.
README.md and packages/server/README.md both linked the self-hosting guide
to a Mintlify preview deployment, mcpuse-codex-v1-v2-docs-split.mintlify.site,
which 404s. The server README ships with the published package.
Reported in #2210.
github-actions[bot]