Skip to main content
Use mcp-use client to test or automate an HTTP MCP server from the terminal. Save a server under a name, then use that name for every tool, resource, prompt, and auth command. For the complete command and flag catalog, see the CLI reference.

​
Connect and call a tool

Run the CLI with npx, or install mcp-use in your project.
connect supports HTTP and HTTPS MCP URLs. It verifies the connection before saving it. The CLI stores saved server metadata under ~/.mcp-use/client/. List or remove saved servers with these commands:

​
Choose a protocol mode

The default --protocol auto mode prefers the modern MCP wire and falls back to the legacy wire when the server does not support modern negotiation. Use legacy or modern when you need strict compatibility testing:
legacy uses only the legacy wire. modern uses the stateless, sessionless modern wire with no fallback.

​
Authenticate with OAuth

When a server requires OAuth in an interactive terminal, the CLI displays this prompt:
Press Enter to open the authorization page. The command keeps waiting for the loopback callback, then verifies and saves the connection.

​
Mixed auth

A mixed-auth server lets connect succeed anonymously, then protects only some operations. When the server advertises OAuth through protected-resource metadata, the CLI saves it normally and prints:
You can keep using public tools and let the first wire-level OAuth challenge start authorization later, or authenticate before calling protected operations:
After interactive authorization, the CLI retries the challenged operation once. It does not infer OAuth from tool-level isError results or error text. Use --no-open to authenticate without launching a browser:
With --no-open or non-interactive human output, the CLI never prompts or opens a browser. It prints a state-free local loopback launcher URL and continues waiting for the callback. Open that local URL yourself; it redirects to the provider without putting the provider URL or OAuth state in terminal output. Under --json, the CLI never prints the authorization URL or OAuth state and never waits for consent. If fresh authorization is required, it exits with oauth_interaction_required and provides an interactive retry command in error.details.nextSteps. Use --no-oauth for a public server or when an authorization challenge should fail instead of starting OAuth. Repeated -H or --header options add static request headers.
Authenticate, check, or clear saved OAuth credentials with auth commands:
auth login starts OAuth for a saved server. auth logout removes OAuth material but keeps the saved server and its non-OAuth connection metadata. Connection URLs are stored exactly for transport use, but CLI results redact URL userinfo, query values, and fragments so signed URLs and embedded credentials are not copied into logs.

​
Call tools

List tools, inspect a tool schema, then call the tool with its required inputs.
Tool and prompt arguments accept key=value pairs. Use key:=<json> for typed or nested values, or pass one JSON object.
Use --timeout <ms> for slow tools. The default is 30000 milliseconds.

​
Read resources

Resources are server-provided content identified by URI. List resources, then read the URI you need.

​
Get prompts

Prompts are reusable message templates exposed by the server. Prompt arguments use the same forms as tool arguments.

​
Produce parseable JSON

Every client command documented with --json accepts it anywhere after client. The following forms are equivalent:
Successful commands write exactly one JSON value followed by a newline to stdout. Calls, resource reads, and prompt gets return the raw MCP result envelope. Lists return arrays. Errors write one envelope to stderr and do not write a result to stdout:
OAuth authorization URLs and dependency-install status are operational messages on stderr, so stdout remains parseable under --json.

​
Troubleshoot commands

  • Unknown saved server: <name>: run npx mcp-use client list, or reconnect with npx mcp-use client connect <name> <url>.
  • Tool not found: <name>: run tools list against the same saved server.
  • protocol_mismatch: reconnect with --protocol auto, or choose the protocol mode the server supports.
  • An OAuth command waits without opening a browser: open the authorization URL printed to stderr, then complete authorization before the configured timeout.
  • A tool returns an error: under --json, inspect error.details for the original MCP tool result.
For exhaustive command shapes, flags, and storage details, use the CLI reference.