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. Use --no-open to authenticate without launching a browser:
With --no-open, --json, or non-interactive stdin, the CLI never prompts or opens a browser. It prints the authorization URL to stderr and continues waiting for the loopback callback. Open that URL yourself to finish authentication. 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.
Check or clear saved OAuth credentials with auth commands:
auth logout removes OAuth material but keeps the saved server and its non-OAuth connection metadata.

​
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.