ResourceDefinition carries annotations and _meta, and both survive local
registration. The proxy mount copies only title, description and
mimeType, and ProxyResource does not even declare the other two, so an
upstream resource loses its client hints and its extension metadata the
moment the server is composed with use().
Both are documented on the resource descriptor and neither has a
framework-derived counterpart, unlike a tool's _meta.ui.* keys, which the
server computes from view and visibility. There is nothing to collide
with here, so forwarding is a straight passthrough.
Prompts need no equivalent change: PromptDefinition has no _meta.
* fix(client): coalesce concurrent connector operations and prevent process leaks
In @mcp-use/client, BaseConnector delegated connect() to subclasses with only
a synchronous `if (this.connected)` guard. Because this.connected was only
set after child process spawning, transport creation, and protocol handshakes:
1. Concurrent connect() calls on StdioConnector instantiated multiple
StdioConnectionManager instances, spawning duplicate OS child processes
and overwriting this.connectionManager. The first child process was
abandoned and leaked permanently in the OS.
2. Concurrent connect() calls on HttpConnector overwrote transport and client
references, causing partial teardowns mid-flight on failure or leaking
SSE sessions.
3. Invoking disconnect() while connect() was in flight saw !this.connected
and returned immediately as a no-op, leaving the connection and its
underlying resources permanently open after connect() settled.
4. Concurrent disconnect() calls issued racing duplicate calls to
cleanupResources().
This moves lifecycle synchronization directly into BaseConnector:
- Coalesce concurrent connect() calls using an internal connectPromise.
- Coalesce concurrent disconnect() calls using an internal disconnectPromise.
- When disconnect() is called while connect() is in flight, await the in-flight
connection attempt before tearing down resources so nothing is orphaned, and
prevent the connector from marking itself connected.
- When connect() is called while disconnect() is in flight, wait for teardown
to complete before opening a new connection.
- Subclasses now implement protected establishTransport() without needing to
re-implement connection concurrency guards.
* fix(client): reject in-flight connect when cancelled by disconnect
When disconnect() is initiated while establishTransport() is in flight,
connect() now rejects with 'Connection cancelled by disconnect' instead of
fulfilling. This prevents callers awaiting connect() from assuming the
connection succeeded and then encountering disconnected-state errors on
subsequent operations.
* fix(client): cancel queued reconnects on later disconnect
* chore(client): add patch changeset for connector lifecycle fixes
---------
Co-authored-by: Andrew Khadder <andrew@manufact.com>
* fix(cli): validate servers list pagination before authenticating
servers list creates the cloud client and then validates --limit and
--skip, so signed out the check never runs:
$ mcp-use servers list --limit 0
Not logged in. Run `mcp-use login`. exit 1
deployments list takes the same two options and reports them properly,
because it validates first:
$ mcp-use deployments list --limit 0
--limit must be an integer from 1 to 100. exit 2
Moving the call above cloudApiForOrganization makes the two agree, and
stops the command reaching for credentials to run something that cannot
run either way.
* test(cli): cover the --skip message in the validate-before-auth case
parsePagination raises a distinct message for --skip, and the fix moves
both checks ahead of the cloud client, so both deserve coverage. Reverting
servers.ts to the canary ordering now fails two tests rather than one.
parseMcpArguments raises a clean UsageError for a key=value grammar
mistake and for JSON that parses but is not an object, then lets the
engine's own SyntaxError escape for JSON that does not parse at all.
$ mcp-use client probe tools call foo '{bad json'
Expected property name or '}' in JSON at position 1 (line 1 column 2)
exit 1
Exit 1 is the operational-failure code, so a typed command line is
reported as an API or runtime problem, and the message says nothing about
which argument was wrong. That matters most for the key:=<json> form,
where one token out of several is at fault.
Both parses now go through a helper that names the argument and raises
UsageError, so they exit 2 like every other grammar mistake in the same
function.
The parse runs during argument validation, before the client connects, so
this is reachable without a reachable server.
* fix(client): stabilize useMcp configuration dependencies to prevent reconnection loops
* test(client): expand array comparison and clientOptions stability test coverage
* feat(client): trigger reconnection in useMcp when headers or clientOptions change
* refactor(client): scope useMcp stability to clientInfo and proxyConfig
* fix(client): preserve absent vs empty icon fields and normalize proxy headers
* fix(client): preserve raw proxyConfig and strengthen useMcp stability and transition tests
* fix(client): return shallow copy in clientInfo and proxyConfig useMemo callbacks
* test(client): remove oversized integration test file and retain focused helper tests
* fix(cli): preserve sensitive flag on env update when --secret is omitted
* refactor: simplify sensitive flag expression per review feedback
* fix(cli): warn on env set secret downgrade, document --secret required every write
* chore: remove stale changeset describing reverted behavior
* fix(cli): tighten env set messages and drop downgradedFromSecret per review
* refactor(cli): drop env set downgrade detection, keep help and docs clarification
Scope the change to help text, docs, and the success message. The success
message now depends only on whether --secret was passed on this invocation.
Write semantics and JSON output are unchanged.
* fix(tunnel): default localHostHeader to localhost in standalone mcp-tunnel CLI
* fix(tunnel): drop redundant --local-host-header alias and document Host rewriting
* fix(tunnel): drop --local-host CLI flag per maintainer review while keeping localhost default
* docs(tunnel): document forwarded Host: localhost default and x-forwarded-host in README
createJwtVerifier canonicalizes options.resource with canonicalUrl, the
same helper used for the resource claim carried by a token. That helper
raises invalidToken, so misconfiguring the server throws an OAuth
invalid_token error at construction, complaining about a token resource
claim when no token exists yet. oauthCustomProvider validates the same
option with a TypeError.
Validation now happens in configuredResourceUrl, which applies the same
URL rules and reports a config problem as TypeError.
Deliberately not normalizedProviderUrl, which the first revision used:
that helper prefixes https:// onto a scheme-less string. Right for a
provider domain, wrong here, because it would have accepted
"api.example.com/mcp" from a JavaScript caller that the URL type does not
constrain. Which URLs are accepted is therefore unchanged from before
this PR; only the error type and message move.
canonicalUrl now only ever sees a token claim, so it takes a string.
* fix(client): clean up sandbox message listener on unmount and add timeout in ViewRenderer
* fix(client): avoid early handshake promise rejection on blob fetch abort and verify timeout listener cleanup
* fix(client): tie ViewRenderer sandbox readiness wait to effect lifecycle and clean up on unmount
* refactor(client): support optional timeoutMs in waitForSandboxProxyReady and add timeout unit tests
* test(client): add ViewRenderer default 15s timeout integration test
* refactor(client): remove sandbox readiness timeout and verify exact listener teardown
* chore: enter canary prerelease mode
* fix(cli): stop reporting deletes that never happened (#2411)
* fix(cli): stop reporting deletes that never happened
Two delete commands print a success line and exit 0 when the thing they
were asked to delete does not exist.
servers env unset looks the key up, filters on both key and branch, then
guards only the DELETE call on having found a match. The success line
runs either way, so a typo prints "Deleted TYPO." and, worse, unsetting a
production variable while passing --branch matches nothing and still
reports the deletion. The variable is still there.
client remove deletes a key from the saved-servers record without
checking it was present, so an unknown name prints "Removed <name>." and
exits 0. Every other saved-server command rejects the same name with
"Unknown saved server" and exit 2.
Both now fail. env unset raises env_variable_not_found naming the scope
that was searched, since the branch mismatch is the case that is hard to
see. client remove reuses the existing unknown-server wording and points
at client list rather than client connect.
* 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>
* chore(typescript): version packages (canary)
* feat(client): export AI SDK MCP adapter (#2441)
* feat(client): add Vercel AI SDK MCP adapter
* fix(client): make AI SDK adapter dependency-free
* docs(client): correct AI SDK adapter release note
* docs(client): add runnable AI SDK adapter example
* chore(client): omit example lockfile
* chore(typescript): version packages (canary)
---------
Signed-off-by: Andrew Khadder <54488379+khandrew1@users.noreply.github.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: Ayaan Gazali <ayaangazali.work@gmail.com>
Co-authored-by: cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com>
Co-authored-by: Enrico Toniato <2827496+tonxxd@users.noreply.github.com>
* docs(server): stop teaching the removed ctx.elicit in v2 samples
ctx.elicit was removed and tests/type-level.test.ts asserts its absence, but the
v2 elicitation page and the migration guide still built every sample on it, so
none of them compiled. Rewrite them on inputResponse, acceptedContent and
inputRequired, mirroring examples/elicitation.
migration.mdx already stated the replacement in its own comparison table while
the sample below it used the old call.
* docs(server): describe the real inputResponse result in the status table
The table still listed the removed call's statuses and its result and data
fields. Unions taken from the compiler: kind is elicit, missing, roots or
sampling, and action is accept, cancel or decline.
* docs(server): finish the URL mode note and qualify the response table
The URL section still described passing the url as a third positional argument,
which was the removed call's shape. The response table also lost the original's
note that URL mode carries no form data, and read as the helper's complete
union when roots and sampling exist for other request types.
* docs(server): show the helper imports in the migration snippet
The replacement snippet used inputResponse, acceptedContent and inputRequired
without showing where they come from, so copying it into a migrated server left
unresolved identifiers.
* fix(create-mcp-use-app): drop the dead --no-git flag from help (#2392)
Scaffolding stopped initializing a git repository in a62db703, but the help
text kept advertising --no-git. parseArgs declares no git option and nothing
reads the flag, so passing it has been indistinguishable from omitting it.
* chore: enter canary prerelease mode
* chore(typescript): version packages (canary)
* fix(client): rebind the OAuth loopback listener after a failed bind (#2393)
* fix(client): rebind the OAuth loopback listener after a failed bind
startLoopback() assigned this.server before listen() resolved, so a bind
failure left a handle that was never listening. The guard at the top of the
method then made every later call return early without binding, and the
caller waited on a dead port until authTimeoutMs expired.
Assign only after a successful bind, and close the server on failure.
* fix(client): keep the loopback handle set while the bind is in flight
Clearing this.server only on failure keeps an overlapping redirectToAuthorization()
and dispose() able to observe the in-flight listener. Assigning after the bind
resolved left a window where both saw null, so two calls could race onto the
same port and dispose() could miss a listener that was still being created.
* test(client): occupy the reserved loopback port instead of a fixed guess
portRange: 1 with an asserted port made the test fail whenever an unrelated
process held the preferred port. Widen the range to match the sibling tests
and bind whatever reservePort settled on.
* chore(client): shorten loopback binding comment
---------
Co-authored-by: Andrew Khadder <andrew@manufact.com>
* chore(typescript): version packages (canary)
* fix(inspector): resolve chat widgets by connection id (#2404)
* chore(typescript): version packages (canary)
* chore(docs): update changelogs for v20.3.5 and v20.3.4 releases
- Added details for v20.3.5, including fixes for chat widgets using the connection id and an update to mcp-use v2.4.1.
- Documented v20.3.4 enhancements, such as request duration display, screenshot failures on initialization, and an update to mcp-use v2.4.0.
---------
Co-authored-by: Mohammed Alkindi <alkndymhmd692@gmail.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: Andrew Khadder <andrew@manufact.com>
UseMcpResult exposes state, not status, so the quick-start destructured an
undefined value and the ready check never passed. The canonical docs page
already uses state.
* docs(typescript): fix CLI flag syntax that silently deploys the wrong directory
The v2 CLI reference wrote the repeatable --env, --watch-paths and
--deploy-branches flags in commander's variadic notation (<glob...>) and
showed examples passing several values to one flag. The CLI parses argv
with node's util.parseArgs, where multiple: true means the flag is
repeatable, not variadic, so only the first value is read and the rest
become positionals.
That makes the two documented examples wrong in different ways:
mcp-use deploy --root-dir apps/mcp-server \
--watch-paths "apps/mcp-server/**" "packages/shared/**"
deploy takes an optional [path] positional, so "packages/shared/**" is
accepted as the deploy path. The command succeeds and deploys the wrong
directory with one watch path instead of two.
mcp-use servers update srv_abc123 \
--watch-paths "apps/api/**" "packages/shared/**" --deploy-branches "release/*"
servers update allows exactly one positional, so the extra value fails
with exit code 2 and "Usage: mcp-use servers update <id-or-slug>".
Also drops the -y short flag from servers delete. deploy defines
yes: { type: "boolean", short: "y" }, but servers delete defines only
yes: { type: "boolean" }, so -y exits 2 with "Unknown option '-y'".
The legacy docs/typescript reference already uses the repeated-flag form.
This brings v2 in line with it and with the CLI's own --help output.
* docs: say outright that the servers update pattern flags are repeatable
The deploy table carries Repeatable in the description column, but the
servers update row is a flat options list with nowhere to put it, so the
one place a reader learns the rule was the corrected example.
* test(cli): make the remaining skill rewrites change file length (#2374)
* chore: enter canary prerelease mode
* feat(inspector): show request duration instead of timestamp in RPC logger (#2364)
The RPC log rows rendered the wall-clock timestamp on the right of each
row while the request latency was squeezed into the truncated method
label. The timestamp is rarely useful compared to how long a request
took, and the inline latency contributed to text truncation.
Move the latency into the right-side slot where the timestamp rendered
and remove it from the method label. Rows for a correlated response now
show "42 ms" with a tooltip including the wall-clock time; rows without
a measured duration (notifications, pending requests) render no
right-side time. Search and row test ids now match the bare method name.
Fixes#2327
* chore(typescript): version packages (canary)
* fix(typescript): fail screenshot CLI on MCP App init failure (#2355)
* fix(typescript): fail screenshot CLI on MCP App init failure
* fix(typescript): ignore post-init guest re-sync errors in view lifecycle signal
* fix(typescript): re-arm view lifecycle error signal on bridge reconnect
* fix(typescript): keep view load failure marker across late teardown events
* chore(typescript): version packages (canary)
* feat(auth): add Convex OAuth provider example and integration (#2372)
* feat(auth): add Convex OAuth provider example and integration
- Introduced a new example for an MCP server authenticated by a Convex OAuth Provider.
- Updated pnpm-lock.yaml to include dependencies for the Convex example.
- Added necessary configurations in package.json, tsup.config.ts, and typedoc.json for the new Convex integration.
- Created new source files for Convex OAuth handling and example server logic.
- Updated tests to include verification for Convex OAuth functionality.
- Enhanced documentation to include Convex in the examples section.
* feat(auth): add Convex OAuth provider example and integration
- Add Convex OAuth provider documentation with setup and usage examples
- Create new Convex provider guide covering configuration, environment variables, and identity verification
- Update authentication provider index to include Convex in built-in providers list
- Update authentication overview table to reference Convex as a supported provider option
- Add Convex example to auth registry with environment configuration
- Enhance Convex example server with OAuth provider implementation
- Add changeset entry documenting new Convex OAuth provider support
* feat(auth): add Convex OAuth provider example and integration
- Add Convex OAuth provider documentation with setup and usage examples
- Create new Convex provider guide covering configuration, environment variables, and identity verification
- Update authentication provider index to include Convex in built-in providers list
- Update authentication overview table to reference Convex as a supported provider option
- Add Convex example to auth registry with environment configuration
- Enhance Convex example server with OAuth provider implementation
- Add changeset entry documenting new Convex OAuth provider support
* docs(typescript): move Convex provider guide to v2
---------
Co-authored-by: Andrew Khadder <andrew@manufact.com>
* chore(typescript): version packages (canary)
* fix(client): stop OAuth retries after disconnect (#2367)
* fix(client): stop OAuth retries after disconnect
* chore: add client patch changeset
* chore(typescript): version packages (canary)
* ci: update checkout, setup-python, setup-node, and upload-artifact to current majors (#2377)
* ci: update checkout, setup-python, setup-node, and upload-artifact to current majors in ci.yml
* ci: bump github-script to v9 to finish action updates
---------
Co-authored-by: katsugtgz <katsugtgz@users.noreply.github.com>
Co-authored-by: katsugtgz <187455787+katsugtgz@users.noreply.github.com>
* fix(client): hold one client reference across listAllResources pagination (#2387)
* fix(client): hold one client reference across listAllResources pagination
listAllResources guards on this.client, then paginates inside a single
executeRequest closure that re-reads this.client on every page. disconnect()
runs cleanupResources, which sets this.client to null, so a teardown landing
between pages makes the next iteration throw
TypeError: Cannot read properties of null (reading 'listResources')
instead of the not-connected error the rest of the connector reports.
Capturing the client in the existing guard fixes it without changing the
guard's behaviour: the reference is read once, at a point where it is known
to be set, and the loop keeps using it. A disconnect mid-listing now surfaces
whatever the closed transport reports rather than a null dereference.
This is the pagination half of #2366. #2367 covered the OAuth retry path by
re-checking the connector state before re-invoking the closure; that guard
does not apply here because the loop never leaves executeRequest, and the
race needs no OAuth provider to reach.
* docs: describe what the captured reference actually prevents
The comment claimed the loop would otherwise report the not-connected
error. It would not: capturing the reference means a disconnect mid
listing fails on the closed transport, which is what the test asserts.
* chore(typescript): version packages (canary)
* feat(inspector): configure embedded max steps (#2401)
* feat(inspector): configure embedded max steps
* fix(inspector): refresh embedded max steps
* chore(typescript): version packages (canary)
---------
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: Mert Çetin <97505365+merttcetn@users.noreply.github.com>
Co-authored-by: Prasad Shinde <144712280+Prasad8830@users.noreply.github.com>
Co-authored-by: Anirban Ghosh <anirbanghosh060@gmail.com>
Co-authored-by: Elioooon <102770919+Elioooon@users.noreply.github.com>
Co-authored-by: Muhammad Naufal Mahdi <053792227@ecampus.ut.ac.id>
Co-authored-by: katsugtgz <katsugtgz@users.noreply.github.com>
Co-authored-by: katsugtgz <187455787+katsugtgz@users.noreply.github.com>
Co-authored-by: Pietro Zullo <62951181+pietrozullo@users.noreply.github.com>
openapi-to-mcp twice tells the reader to switch to build-mcp-app, which this
repo does not ship. The widget skill here is mcp-apps-builder, which is also
the template named in the same sentence.
* docs(inspector): drop the stale SSE claim from the feature table
The Connect Panel hardcodes transportType to http and the same README says
Streamable HTTP only a few sections later, so the feature table was the
outlier. #2363 corrected the WebSocket half of this row and left the SSE half.
* docs(create-mcp-use-app): import MCPAgent from the langchain entry
The example passes a ChatOpenAI instance as llm, which only the langchain
MCPAgent accepts. The root entry types llm as string | ProviderConfig, so the
snippet fails to typecheck. The agent package README uses the same pairing
with @mcp-use/agent/langchain.
* docs(cli): org use, and logout takes --yes
Two more rows that do not match the binary.
`org switch` does not exist. The dispatch is:
$ mcp-use org switch my-org
Usage: mcp-use org <list|current|use> exit 2
$ mcp-use org use my-org
Not logged in. Run `mcp-use login`. exit 1
The third subcommand is `use`.
`logout` is documented as taking no options, and the example is a bare
`mcp-use logout`. It prompts, so without a TTY that example fails:
$ mcp-use logout
Log out? Pass --yes to confirm. exit 2
$ mcp-use logout --yes
Logged out. exit 0
It also honours `--json`, verified both ways:
$ mcp-use logout --json --yes
{"loggedOut":true} exit 0
Document both options and make the example runnable.
* docs(cli): clarify org use and logout
---------
Co-authored-by: Andrew Khadder <andrew@manufact.com>
* docs(cli): drop the two deploy flags that do not exist
The deploy option table lists --port and --runtime. Neither is accepted:
$ mcp-use deploy --port 3000
Unknown option '--port'. exit 2
$ mcp-use deploy --runtime node
Unknown option '--runtime'. exit 2
deploy's parseArgs declares exactly org, name, branch, root-dir, region,
env, env-file, build-command, start-command, dockerfile, watch-paths,
wait-for-ci, no-github, new, open, yes, json and help. There is nowhere
for port or runtime to land.
Every other row in that table was checked the same way and is correct,
including `-y, --yes`, whose short form does work here even though the
deployments table's does not.
`--port` stays in the dev and start tables, where it is real.
* docs(cli): remove invalid runtime example
---------
Co-authored-by: Andrew Khadder <andrew@manufact.com>
* docs(cli): correct the deployments subcommand table
Seven claims in this table do not match the binary. Each was checked by
running it; the CLI errors with exit 2 on a bad option or subcommand and
reaches "Not logged in" with exit 1 once it parses, which makes the two
easy to tell apart without credentials.
ls alias Usage: mcp-use deployments <list|get|logs|restart|stop|delete>
rm alias same
start subcommand same
--sort Unknown option '--sort'
-b (logs) Unknown option '-b'
-f (logs, restart) Unknown option '-f'
stop, no --yes Stop deployment dep_x? Pass --yes to confirm.
The long forms --build and --follow do work; only the short aliases are
absent. The dispatch accepts exactly list, get, logs, restart, stop and
delete (deployments.ts:63-71), so ls, rm and start have nowhere to land.
Also adds --org and --server to the list row. Both are real and were
missing; the command's own usage string advertises them.
Removes the `deployments start dep_abc123` example, which cannot run, and
notes that stop prompts for confirmation like delete does.
Every row in the corrected table now parses and reaches the auth check
rather than failing on arguments.
* docs(cli): document deployment JSON output
---------
Co-authored-by: Andrew Khadder <andrew@manufact.com>
github-actions[bot]