Skip to main content
Use mcp-use client when you want to test or automate an MCP server from the terminal. The fastest useful loop is: connect to a server, list its tools, then call one tool. For the complete command and flag catalog, see the CLI reference.

​
Install the CLI

Run the CLI with npx, or install it globally if you use it often.

​
Connect and call a tool

Save the server under a short name, then use that name in every later command.
After connect, the CLI prints the server name, version, capabilities, and tool count. Use tools list as the quick verification step. If the command returns the tools you expect, the server is reachable and initialized. Use any short name that helps you remember the target, such as dev, staging, prod, or filesystem.

​
Connect to HTTP or stdio servers

HTTP servers use a URL. The saved name comes before the URL.
Stdio servers use --stdio. Quote the command so the CLI can split it into the executable and arguments.
List saved servers when you need to confirm the names you have available.
Remove a saved server when you no longer need it.

​
Call tools

Start with tools list, then inspect a tool schema before calling tools with required inputs.
Tool arguments can be passed as key=value pairs. Use key:=<json> for nested values, or pass one JSON object.
Use --json when another command or script needs to parse the result.
Use --timeout <ms> for slow tools.

​
Read resources

Resources are server-provided content identified by URI. List resources first, then read the URI you need.
If a resource supports updates, subscribe to stream changes until you stop the process.

​
Get prompts

Prompts are reusable message templates exposed by the server. List prompts, then get one with its arguments.
Prompt arguments use the same simple forms as tool arguments.

​
Check OAuth status

For HTTP servers that require OAuth, connect starts the browser-based OAuth flow when the server returns 401 Unauthorized. After authentication, the saved server reuses those credentials for tools, resources, prompts, and screenshots.
Use auth refresh when you want to force a token refresh, and auth logout when you want to clear stored OAuth tokens for that server URL.
Auth commands apply only to HTTP servers authenticated through OAuth. For a static bearer token, pass --auth when connecting.
Pass --no-oauth when you want the CLI to fail on 401 Unauthorized instead of starting OAuth.

​
Capture widget screenshots

Use screenshots to verify MCP Apps widgets from a terminal or an automated test. The saved-server form reuses the auth from connect.
You can also call a tool and save its widget screenshot in one command.
For one-off captures without saving a server first, use the ad-hoc form with --mcp.
Authenticated ad-hoc screenshots can pass HTTP headers. Header flags apply only to the ad-hoc form.
Common screenshot options include --output, --width, --height, --device-scale-factor, --theme, --wait-for, --delay, --timeout, and --cdp-url. See the CLI reference for the full screenshot option list.

​
Use interactive mode

Interactive mode opens a small REPL for one saved server. Use it when you want to explore tools, resources, and prompts without repeating the full command prefix.

​
Script common checks

Use --json and stable saved names when scripting. This keeps stdout parseable while status messages stay on stderr.
For local development, a compact smoke test is enough: connect, list tools, describe the tool you changed, then call it once.

​
When a command fails

Most failures can be diagnosed from the command you just ran:
  • Server '<name>' not found: run npx mcp-use client list, or reconnect with npx mcp-use client connect <name> <url>.
  • This tool requires arguments: run tools describe <tool> and pass the required inputs.
  • Tool '<name>' not found: run tools list against the same saved server.
  • OAuth refresh fails: run mcp-use client connect <name> <url> again to re-authenticate.
For exhaustive flags, command shapes, and storage details, use the CLI reference.

​
Next steps

Use the TypeScript server overview to build a server that exposes tools, resources, prompts, and widgets. Use the MCP Apps guide when your tools should return interactive React widgets.