MCP Client#

Connect to any external MCP server and use its tools as native CLI commands — with tab completion, --help, and full argument support.

Add a server#

Point Sidekick at an MCP server once. It connects, discovers every available tool, and caches the schemas locally.

stdio (subprocess)#

# npx-based server (e.g. the official BrowserStack MCP server)
sdkck mcp client add browserstack \
  --command npx \
  --args -y \
  --args @browserstack/mcp-server@latest \
  --env BROWSERSTACK_USERNAME=your_username \
  --env BROWSERSTACK_ACCESS_KEY=your_access_key

# Local script with arguments and environment variables
sdkck mcp client add myserver \
  --command ./bin/server.js \
  --args start \
  --env API_KEY=sk-... \
  --env LOG_LEVEL=info

HTTP (remote)#

# With a Bearer token in the Authorization header
sdkck mcp client add remote \
  --url https://api.example.com/mcp \
  --header "Authorization=Bearer sk-..."

# OAuth-protected server (e.g. BrowserStack) — no extra flags needed.
# sdkck opens your browser to authorize, then saves the token automatically.
sdkck mcp client add browserstack-remote \
  --url https://mcp.browserstack.com/mcp

Flag	Description
`--command`, `-c`	Command to launch the server (stdio transport)
`--args`	Argument to pass to the command (repeatable)
`--env`	Environment variable as `KEY=VALUE` (repeatable)
`--url`, `-u`	URL of the MCP server (HTTP transport)
`--header`	HTTP header as `Key=Value` (repeatable)

Use tools as native commands#

After adding a server every tool is immediately available as sdkck <serverName> <toolName>:

# Discover what tools a server exposes
sdkck help browserstack

# Use a tool
sdkck browserstack runBrowserLiveSession "https://example.com"

# Get help for a specific tool
sdkck browserstack runBrowserLiveSession --help

Required string parameters become positional arguments. Optional parameters become --<name> flags. Complex types (objects, arrays) accept a JSON string:

# Required string param → positional arg
sdkck browserstack runBrowserLiveSession https://example.com

# Optional params → flags
sdkck browserstack runBrowserLiveSession https://example.com --browser chrome --os Windows

# Object param → JSON string
sdkck browserstack setupBrowserStackAutomateTests "my-project" --config '{"framework":"selenium","language":"javascript"}'

# Override everything with a raw JSON object (useful for complex schemas)
sdkck browserstack runBrowserLiveSession --json-args '{"url":"https://example.com","browser":"chrome","browserVersion":"latest"}'

Tool commands appear in sdkck help, sdkck commands, and tab completion alongside every other built-in command.

List servers#

# Show configured servers
sdkck mcp client list

# Include individual tool names
sdkck mcp client list --tools

Example output:

browserstack
  Transport: stdio (npx -y @browserstack/mcp-server@latest)
  Tools: 40
  Cached at: 5/25/2026, 9:00:00 AM

remote
  Transport: http (https://api.example.com/mcp)
  Tools: 5
  Cached at: 5/25/2026, 9:01:00 AM

Refresh tools#

Tool schemas are cached locally and stay valid for one hour. To pick up new tools after a server update:

# Refresh a single server
sdkck mcp client refresh browserstack

# Refresh all servers
sdkck mcp client refresh

Remove a server#

sdkck mcp client remove browserstack

This deletes the stored config and cached tools. The tool commands disappear from the CLI on the next invocation.

How it works#

Tool discovery and invocation are decoupled:

At add/refresh time — Sidekick connects to the server, calls listTools, and caches the schemas in ~/.config/sdkck/mcp-client-<name>.json.
At startup — cached schemas are read from disk and each tool is registered as a native oclif command (no live connection needed).
At invocation time — Sidekick spawns a fresh connection to the server, calls tools/call with the mapped arguments, and prints the result.

This means startup is fast regardless of how many servers are configured, and tool commands work correctly even when a server is temporarily unavailable at start time.