* 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>
* fix(cli): report success from mcp-use typecheck (#2099)
`tsc --noEmit` prints nothing on a clean project, so `mcp-use typecheck`
exited 0 with no output at all, which is indistinguishable from the
command hanging or silently failing.
Print `[mcp-use] no type errors (<duration>ms)` on exit code 0, matching
the existing `[mcp-use] built ... (<duration>ms)` line from `build`.
Failing runs are untouched and still show only the compiler's own
diagnostics.
Closes#2083
* chore: enter canary prerelease mode
* chore(typescript): version packages (canary)
* chore: sync main into canary (#2119)
* chore(release): exit prerelease mode and publish npm README hotfix
Publishes mcp-use 2.0.1 and @mcp-use/inspector 20.0.1 with the repository README included in the mcp-use package tarball.
* chore(release): exit prerelease mode and publish npm README metadata hotfix
Publishes mcp-use 2.0.2 and @mcp-use/inspector 20.0.2 after preparing README metadata before npm publication.
* chore(release): exit prerelease mode and commit npm package README
Publishes mcp-use 2.0.3 and @mcp-use/inspector 20.0.3 with a committed package-root README.
* chore(release): exit prerelease mode and fix npm README assets
Fix npm README asset and repository links, publish mcp-use 2.0.4, and keep Inspector aligned at 20.0.4.
* Update libraries/typescript/packages/server/README.md
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>
* docs: sync migration guide link
---------
Signed-off-by: Andrew Khadder <54488379+khandrew1@users.noreply.github.com>
Co-authored-by: Enrico Toniato <2827496+tonxxd@users.noreply.github.com>
Co-authored-by: cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com>
* fix(cli): say whether `start` mounted the inspector (#2100)
* fix(cli): say whether start mounted the inspector
`mcp-use dev` advertises the inspector in its banner, but `mcp-use start`
says nothing about it and `${basePath}/inspector` 404s unless
`--with-inspector` was passed. With no hint, that reads as a broken
production build rather than an opt-in.
Plain `start` now prints that the inspector is not mounted and how to
mount it, and `--with-inspector` prints the URL it was mounted at, which
was previously silent too.
Closes#2084
* fix(cli): drop the inspector-not-mounted line from start
Per review: most people running start do not want the inspector, so
announcing its absence is noise. Plain start is now silent about the
inspector again, and only the --with-inspector path prints its URL.
Updates the spec, the changeset, and swaps the test to pin the silence
instead of the message.
* chore(typescript): version packages (canary)
* chore: upgrade changesets cli to 2.31.1 (#2121)
* fix(ci): pin pnpm in the docs workflow so the job can start (#2116)
The docs job fails in "Set up pnpm" before it generates anything:
Error: No pnpm version is specified.
pnpm/action-setup@v4 was used with no version:, so it falls back to
reading packageManager from package_json_file, which defaults to the
repository root. This repo has no root package.json, so the step could
never succeed and the check was red on every branch including main.
Pins 11.13.1, matching all nine action-setup uses in ci.yml and the
packageManager field in libraries/typescript/package.json.
* fix(cli): support package-manager dev arg forwarding (#2124)
* fix(cli): support package-manager dev arg forwarding (MCP-2549)
* chore: add MCP-2549 changeset
* fix(cli): normalize forwarded arguments across commands
* chore(typescript): version packages (canary)
* docs: fix TypeScript README links into the removed mcp-use package (#2114)
The v2 merge deleted libraries/typescript/packages/mcp-use, but the
TypeScript README still pointed at it in four places: the three logo
sources at the top of the page, and the documentation link at the bottom.
The logo now uses the absolute raw.githubusercontent.com URL that every
sibling package README already uses, and the docs link points at
packages/server, which is where the mcp-use package lives in v2 and what
the create-mcp-use-app and inspector READMEs already link to.
* fix(create-mcp-use-app): drop stale main field and give templates distinct descriptions (#2085)
* fix(create-mcp-use-app): drop stale main field and give templates distinct descriptions
Two small things in the scaffolded package.json, both visible as soon as
you generate a project.
main pointed at dist/index.js. v2 builds emit .mcp-use/build instead, so
that path never exists and main never resolves. These templates are apps
you run with mcp-use start, not packages anyone imports, and .mcp-use is
gitignored build output, so the field is dropped rather than repointed.
All three templates also carried the description 'an mcp-use server'.
--list-templates reads that field, so the three were indistinguishable
from the CLI, and every generated project inherited the same string.
Each now says what it actually gives you.
Closes#2080Closes#2081
* chore: add changeset for the template package.json fixes
* fix(create-mcp-use-app): stop discarding the template description
updatePackageJson overwrote description with a generic
"<name>: an mcp-use server" on every scaffold, so the per-template
descriptions only ever reached --list-templates and never the generated
project. It now fills that in only when the template has no description
of its own, which keeps the previous behaviour for templates without one.
* chore(typescript): version packages (canary)
* fix(client): stop leaking parent env to stdio servers (#2125)
Port the security fix from #1949 to the v2 client package and verify the child process receives only safe defaults plus explicitly configured variables.
Co-authored-by: VihaanAgarwal <72850668+VihaanAgarwal@users.noreply.github.com>
* chore(typescript): version packages (canary)
* fix(client): bound conformance auth scenarios (#2126)
* fix(client): make stdio errlog actually receive the child's stderr (#2086)
* fix(client): make stdio errlog actually receive the child's stderr
StdioConnectionManager takes an errlog stream and documents that the
child server's stderr is piped to it, but the transport was created
without stderr: "pipe". The SDK defaults to "inherit", which leaves
transport.stderr null, so the forwarding block guarding on it never
ran and the child's stderr always went to the parent instead.
Spawn with stderr: "pipe" by default, spread so an explicit mode in
server params still wins. Tests spawn real child processes: one checks
a custom errlog receives the output, one checks stderr: "ignore" still
opts out.
* chore: drop stray version.ts that does not belong on beta
Left over from a main checkout; packages/mcp-use does not exist on this
branch.
* fix(client): expose stderr mode on the public stdio APIs
Per review, the compatibility escape hatch only worked for callers that
built StdioConnectionManager directly. StdioConnector did not accept or
forward stderr and StdioServerConfig did not expose it, so users of the
normal public APIs could not opt back into inherited stderr.
- Add a StdioStderrMode of "pipe" | "inherit" | "ignore", default "pipe".
- Accept it on StdioConnector and StdioServerConfig, forward it into
StdioServerParameters, and thread it through the config path.
- Apply the default after the spread so an explicit stderr: undefined no
longer defeats it.
- Only forward transport.stderr when the mode leaves a readable stream.
- Pipe with { end: false } and unpipe on close, since errlog is
caller-owned and may be reused across reconnects.
- Handle stream errors instead of letting a destroyed errlog surface as
an unhandled 'error' event.
Tests now start the transport before asserting, so the non-pipe cases are
exercised against a real child instead of passing by construction.
* fix(client): handle errlog write errors
---------
Co-authored-by: Andrew Khadder <andrew@manufact.com>
* chore(typescript): version packages (canary)
* fix(inspector): block loopback proxy targets by default (#2134)
mountInspector defaulted oauthProxyAllowLoopback to true, and the standalone
CLI hardcoded it — including in the published Docker image, which runs the
CLI with NODE_ENV=production on a public port. A publicly reachable inspector
could therefore proxy requests to the host's loopback services (SSRF), while
RFC1918/metadata targets were already blocked.
- mountInspector: default allowLoopback to false; local dev tooling opts in
- CLI: allow loopback unless NODE_ENV=production; INSPECTOR_ALLOW_LOOPBACK
overrides either way
- Express-adapter test opts in explicitly (it proxies to its own 127.0.0.1
echo server); new regression test covers the default and the opt-in
* chore(typescript): version packages (canary)
* docs: add v2 changelog updates
* chore: remove retired beta release flow (#2141)
* fix: keep prerelease versioning visible to Knip (#2142)
* fix: patch dependency vulnerabilities (#2151)
* fix: patch vulnerable dependencies
* fix: use mcp-use in client demo servers
* chore(typescript): version packages (canary)
---------
Signed-off-by: Andrew Khadder <54488379+khandrew1@users.noreply.github.com>
Co-authored-by: Ayaan Gazali <ayaangazali.work@gmail.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: Enrico Toniato <2827496+tonxxd@users.noreply.github.com>
Co-authored-by: cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com>
Co-authored-by: VihaanAgarwal <72850668+VihaanAgarwal@users.noreply.github.com>
* docs: the v1 compatibility bridge no longer exists in v2
The migration guide tells people they can stage a migration by keeping
`import { MCPServer, text } from "mcp-use/server"`. That export was
removed before v2 went stable, so the import does not resolve and the
advice sends migrating users down a path that fails immediately.
Replaces the staging section with what actually happened and points at
the package root, and drops the matching allowance from the cleanup step.
* docs: drop the compatibility bridge section entirely
Per review: the bridge was never part of the official release, so
documenting its removal keeps a beta remnant alive in the migration
guide. Removes the section rather than rewriting it.
The cleanup step keeps its correction, since v1 really did import from
mcp-use/server and migrating users still need to remove those.
* Set V2 as the default documentation version
* Reorganize documentation navigation and redirects
* Remove deprecated repository content
* Rename Manufact deployment guide
The templates table and the templates page both list meal-plan and
recipe-suggestion under Tools for the Recipe Finder, but the server
registers those two as prompts, not tools. Querying the linked demo
server confirms it:
tools/list -> search-recipes, get-recipe
prompts/list -> meal-plan, recipe-suggestion
The distinction matters because a model can call a tool on its own but
cannot invoke a prompt, so anyone reading the table expects behavior
they will not get. #1883 is someone hitting exactly that.
* fix: use hosted WebSocket tunnel relay
* fix: reattach tunnels across relay deploys
* fix: negotiate tunnel keepalive support
* refactor: remove spinner state and improve loading indicators in ViewRenderer and MCP Apps components
- Updated migration guide link in README.md to point to the correct TypeScript v2 documentation.
- Added a new warning banner in docs.json to announce that mcp-use v2 is now in beta.
- Enhanced TypeScript SDK description in docs.json to clarify documentation for both V1 and V2.
- Restructured documentation sections in docs.json for better organization and clarity.
- Replaced logo with a new banner image for better visibility.
- Improved text formatting for readability.
- Updated badge links for npm version and downloads.
- Adjusted Discord badge style for consistency.
Preserve the V1 TypeScript docs, add independently navigable V2 beta documentation, and align shared documentation. Rename both V2 migration guides to “Migrating to v2”.
- Updated CLI command syntax to include [path] for deployment.
- Improved descriptions for deployment options, including `--name`, `--new`, and `--region`.
- Added `--json` option for machine-readable output and clarified its behavior in the documentation.
- Enhanced error handling and output formatting for better user feedback.
- Updated various command help texts to reflect new features and usage patterns.
- Improved local authentication flow and clarified the behavior of `--no-open` and `--json` options.
- Added tests to ensure correct behavior of new features and error handling.
Drop chalk/cli-highlight from @mcp-use/agent (inline ANSI for prettyStreamEvents), remove the redundant ./browser entry, default autoInitialize in simplified mode, and ship package examples plus corrected install guidance (client is a transitive dep; /langchain is a subpath).
- Updated the API reference to reflect the migration from v1 enum elicitation helpers to Zod form schemas.
- Revised descriptions and examples in the elicitation schemas documentation to guide users on the new Zod-based approach.
- Adjusted links and callouts to emphasize the removal of deprecated v1 helpers and provide migration guidance.
- Renamed `ToolContext` to `RequestContext` in documentation and code.
- Updated the context object to provide enhanced client metadata, including user information and capabilities.
- Improved examples and descriptions for clarity on client capabilities and request-scoped metadata.
- Adjusted tests to reflect changes in client metadata handling and ensure type safety.
Bring back typed Hono routes/middleware with server.fetch as the serving
boundary, restore deprecated response helpers for upgrades, and require
useCallTool names to resolve against mcp-env.d.ts ToolRefs (with
useDynamicTool + mcp-use typecheck as the escape hatch).
* fix inspector hosted proxy and oauth recovery
* remove inspector compatibility report
* refactor(inspector): mount project-local dev inspector
* refactor(inspector): remove CDN application delivery
* fix(inspector): finalize local mount and proxy health checks
Andrew Khadder