MCP-S CLI

A lightweight CLI for connecting AI agents to the Webrix MCP Gateway from your terminal.

Overview

The MCP-S CLI (@mcp-s/cli) lets you interact with Webrix MCP servers directly from the command line. It's designed for:

Shell scripting — JSON output, pipes with jq, chaining support
AI coding agents — Optimized for Claude Code, Cursor, Gemini CLI, and others
Quick exploration — Discover and call tools without leaving the terminal

Quick Start

1. Install

Requires Node.js >= 18.

npm install -g @mcp-s/cli

Or run without installing:

npx @mcp-s/cli

2. Initialize

Configure the CLI with your Webrix Gateway:

# Interactive setup (recommended)
mcp-s-cli init

# SaaS — derive URL from org name
mcp-s-cli init --org <your-org>

# On-prem — provide a custom base URL
mcp-s-cli init --base-url https://<your-gateway>/mcp

To scope the CLI to a specific MCP or toolkit:

mcp-s-cli init --org <your-org> --mcp slack
mcp-s-cli init --org <your-org> --toolkit my-toolkit

3. Discover Tools

# List all available tools
mcp-s-cli

# Include descriptions
mcp-s-cli -d

# Search by name
mcp-s-cli grep ticket

4. Call a Tool

# View tool schema
mcp-s-cli info search_issues

# Call with inline JSON
mcp-s-cli call search_issues '{"query": "open bugs", "limit": 5}'

Commands Reference

Command	Description
`mcp-s-cli`	List all tools
`mcp-s-cli info <tool>`	Show schema for a tool
`mcp-s-cli grep <query>`	Search tools by name
`mcp-s-cli call <tool> '<json>'`	Call a tool with inline JSON
`mcp-s-cli call <tool>`	Call a tool (reads JSON from stdin)
`mcp-s-cli init`	Initialize global config
`mcp-s-cli login`	Log in via OAuth
`mcp-s-cli logout`	Remove stored OAuth tokens
`mcp-s-cli whoami`	Show config location and auth state
`mcp-s-cli clear`	Reset server config
`mcp-s-cli clear-auth`	Remove all stored auth data

Options

Option	Description
`-h, --help`	Show help message
`-v, --version`	Show version number
`-d, --with-descriptions`	Include tool descriptions in output
`-c, --config <path>`	Path to a custom config file

Authentication

OAuth (Browser-Based)

mcp-s-cli login

Opens your browser for OAuth authentication. Tokens are stored locally and refreshed automatically.

Bearer Token

Pass a static token during init:

mcp-s-cli init --base-url https://<your-org>.webrix.ai/mcp --token <your-token>

STDIO Mode (User Access Key)

When a user access key is provided, the CLI runs in STDIO mode via npx @mcp-s/mcp:

mcp-s-cli init --org <your-org> --mcp slack --user-access-key <key>

Check Auth State

mcp-s-cli whoami

Configuration

The config file lives at ~/.config/mcp-s-cli/config.json (override with -c or MCP_S_CLI_CONFIG_PATH).

HTTP Mode

{
  "baseUrl": "https://<your-org>.mcp-s.com/mcp",
  "mcp": "slack",
  "toolkit": "my-toolkit",
  "token": "<bearer-token>"
}

STDIO Mode

{
  "baseUrl": "https://<your-org>.mcp-s.com/mcp",
  "mcp": "slack",
  "toolkit": "my-toolkit",
  "userAccessKey": "<key>"
}

Init Options

Option	Description
`--org <name>`	Org name — derives URL as `https://<name>.mcp-s.com/mcp`
`--base-url <url>`	Custom server URL (mutually exclusive with `--org`)
`--mcp <name>`	MCP identifier
`--toolkit <name>`	Toolkit name
`--user-access-key <key>`	User access key — triggers STDIO mode

info

Either --org or --base-url is required; they are mutually exclusive.

Config Fields

Field	Description
`baseUrl`	MCP server URL (required for HTTP mode)
`mcp`	MCP identifier header / env var
`toolkit`	Toolkit name header / env var
`token`	Static Bearer token for HTTP auth
`userAccessKey`	User access key — triggers STDIO mode
`allowedTools`	Glob patterns of tools to allow
`disabledTools`	Glob patterns of tools to exclude
`settings`	Behavioral settings (see below)

Environment variable substitution is supported — e.g. "token": "${MY_TOKEN}".

Settings

Tune behavioral settings per config:

{
  "baseUrl": "https://<your-org>.mcp-s.com/mcp",
  "settings": {
    "timeout": 60,
    "maxRetries": 1,
    "retryDelay": 500,
    "daemon": false,
    "daemonTimeout": 120,
    "history": true
  }
}

Field	Description	Default
`timeout`	Request timeout (seconds)	`1800`
`maxRetries`	Retry attempts for transient errors	`3`
`retryDelay`	Base retry delay (milliseconds)	`1000`
`daemon`	Enable connection caching	`true`
`daemonTimeout`	Idle timeout for cached connections (seconds)	`300`
`history`	Append each invocation to `history.jsonl`	`false`

Environment Variables

Variable	Description
`MCP_S_CLI_DEBUG`	Enable debug output
`MCP_S_CLI_STRICT_ENV`	Error on missing `${VAR}` in config (`false` to warn)
`MCP_S_CLI_CONFIG_PATH`	Override config file path

Usage Examples

Calling Tools

# Inline JSON
mcp-s-cli call search_issues '{"query": "bug in authentication", "limit": 5}'

# Pipe JSON output
mcp-s-cli call search_issues '{"query": "open bugs"}' | jq '.content[0].text'

# Read JSON from stdin
echo '{"query": "urgent"}' | mcp-s-cli call search_issues

# Heredoc for complex JSON
mcp-s-cli call create_ticket <<EOF
{"title": "Fix login bug", "description": "Users can't log in with SSO"}
EOF

Chaining and Scripting

# Find issues and extract URLs
mcp-s-cli call search_issues '{"query": "priority: high"}' \
  | jq -r '.content[0].text | fromjson | .issues[].url'

# Conditional execution
mcp-s-cli call list_channels '{}' \
  | jq -e '.content[0].text | contains("engineering")' \
  && mcp-s-cli call post_message '{"channel": "engineering", "text": "Deploy complete"}'

# Error handling
if result=$(mcp-s-cli call get_config '{}' 2>/dev/null); then
  echo "$result" | jq '.content[0].text | fromjson'
else
  echo "Failed to fetch config"
fi

tip

Use jq -r for raw string output, jq -e for conditional checks, and 2>/dev/null to suppress errors when testing existence.

Using with AI Agents

The CLI is designed to give AI coding agents direct access to the Webrix MCP Gateway via the shell, without loading full tool schemas into the agent's context window.

Add this to your AI agent's system prompt:

## MCP Tools (via Webrix Gateway)

You have access to enterprise tools through the Webrix MCP Gateway via the `mcp-s-cli` CLI.

Commands:
  mcp-s-cli                    # List all tools
  mcp-s-cli info <tool>        # Get tool schema
  mcp-s-cli grep <query>       # Search tools by name
  mcp-s-cli call <tool> '{}'   # Call tool with inline JSON

Workflow:
1. Discover: `mcp-s-cli` to see available tools
2. Inspect:  `mcp-s-cli info <tool>` to get the schema
3. Execute:  `mcp-s-cli call <tool> '<json>'` with the required args

For AI agents that support skill files (Cursor, Gemini CLI, Claude Code, etc.), the CLI includes a built-in SKILL.md that can be added to your skills directory.

Connection Pooling

Daemon mode is enabled by default. The CLI keeps the server connection open for daemonTimeout seconds (default: 300s) after the last request, avoiding repeated startup latency.

To disable daemon mode, add to your config:

{
  "settings": { "daemon": false }
}

Error Handling

The CLI automatically retries transient failures (network errors, HTTP 429/502/503/504) with exponential backoff. Config errors, auth errors (401/403), and invalid JSON fail immediately.

All errors include actionable recovery suggestions:

Error [CONFIG_MISSING_FIELD]: Config file is missing required server fields
  Suggestion: Config must have at least "baseUrl" (HTTP) or "userAccessKey" (stdio).
  Run mcp-s-cli init to set up.

Error [TOOL_NOT_FOUND]: Tool "search" not found in server "server"
  Suggestion: Run 'mcp-s-cli' to see all available tools

Common Mistakes

Wrong Command	Fix
`mcp-s-cli run tool`	Use `call` instead of `run`
`mcp-s-cli list`	Use `mcp-s-cli` with no subcommand
`mcp-s-cli call tool bad_json`	Wrap JSON in quotes: `'{"key": "val"}'`

Overview​

Quick Start​

1. Install​

2. Initialize​

3. Discover Tools​

4. Call a Tool​

Commands Reference​

Options​

Authentication​

OAuth (Browser-Based)​

Bearer Token​

STDIO Mode (User Access Key)​

Check Auth State​

Configuration​

HTTP Mode​

STDIO Mode​

Init Options​

Config Fields​

Settings​

Environment Variables​

Usage Examples​

Calling Tools​

Chaining and Scripting​

Using with AI Agents​

Connection Pooling​

Error Handling​

Common Mistakes​