# 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)

```bash
# 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)

```bash
# 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>`:

```bash
# 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:

```bash
# 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

```bash
# 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:

```bash
# Refresh a single server
sdkck mcp client refresh browserstack

# Refresh all servers
sdkck mcp client refresh
```

## Remove a server

```bash
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.
