npm package: @mcp-s/cli
Description: A lightweight CLI for connecting AI agents to the Webrix MCP Gateway
Author: Idan Chetrit
Latest version: 0.0.22

# mcp-s-cli

A lightweight CLI for connecting AI agents to the [Webrix](https://webrix.ai) MCP Gateway — Webrix's enterprise-grade identity and access layer for AI agents.

## Overview

Webrix's MCP Gateway is the secure connection layer between AI agents and your enterprise systems (GitHub, Slack, Jira, internal APIs, etc.). This CLI lets you interact with a single Webrix MCP server from your terminal or from inside AI coding agents (Claude, Cursor, Gemini CLI, etc.).

## Features

- **Lightweight** — Minimal dependencies, fast startup
- **Shell-friendly** — JSON output for `call`, pipes with `jq`, chaining support
- **Agent-optimized** — Designed for AI coding agents (Claude Code, Cursor, Gemini CLI, etc.)
- **Secure** — Supports OAuth login and Bearer token auth to the Webrix Gateway
- **Connection pooling** — Lazy-spawn daemon keeps connections warm (configurable idle timeout)
- **Tool filtering** — Allow/disable specific tools via config
- **Actionable errors** — Structured error messages with recovery suggestions

---

## Quick Start

### 1. Install

Requires [Node.js](https://nodejs.org/) >= 18.

```bash
npm install -g @mcp-s/cli
```

Or run without installing:

```bash
npx @mcp-s/cli
```

### 2. Initialize config with your Webrix Gateway URL

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

# Or non-interactive: HTTP server with a Bearer token
mcp-s-cli init --base-url https://<your-org>.webrix.ai/mcp --token <your-token>

# Or: OAuth-based (run login after init)
mcp-s-cli init --base-url https://<your-org>.webrix.ai/mcp
mcp-s-cli login
```

### 3. Discover available tools

```bash
# List all tools
mcp-s-cli

# With descriptions
mcp-s-cli -d
```

### 4. Call a tool

```bash
# View tool schema first
mcp-s-cli info <tool_name>

# Call the tool
mcp-s-cli call <tool_name> '{"param": "value"}'
```

---

## Usage

```
mcp-s-cli [options]                        List all tools
mcp-s-cli [options] info <tool>            Show schema for a specific tool
mcp-s-cli [options] grep <query>           Search tools by name
mcp-s-cli [options] call <tool>            Call a tool (reads JSON args from stdin)
mcp-s-cli [options] call <tool> <json>     Call a tool with inline JSON arguments
mcp-s-cli init [--org <org>] [--base-url <url>] [...]  Initialize global config
mcp-s-cli whoami                           Show config location and auth state
mcp-s-cli login                            Log in to the configured server via OAuth
mcp-s-cli logout                           Remove stored OAuth tokens
mcp-s-cli clear                            Reset server config
mcp-s-cli clear-auth                       Remove all stored auth data
```

> **Tip:** Add `-d` to any command to include tool descriptions.

### 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.json` config |

### Output streams

| Stream     | Content                                |
| ---------- | -------------------------------------- |
| **stdout** | Tool results and human-readable output |
| **stderr** | Errors and diagnostics                 |

---

## Commands

### List Tools

```bash
# Basic listing
$ mcp-s-cli
server
  • search_issues
  • create_ticket
  • list_channels

# With descriptions
$ mcp-s-cli -d
server
  • search_issues - Search Jira issues by query
  • create_ticket - Create a new Jira ticket
  • list_channels - List Slack channels
```

### Search Tools

```bash
# Find tools by name (case-insensitive substring match)
$ mcp-s-cli grep ticket
create_ticket
update_ticket

# With descriptions
$ mcp-s-cli grep search -d
search_issues - Search Jira issues by query
```

### View Tool Schema

```bash
$ mcp-s-cli info search_issues

Tool: search_issues

Description:
  Search Jira issues by query

Input Schema:
  {
    "type": "object",
    "properties": {
      "query": { "type": "string", "description": "JQL or natural language query" },
      "limit": { "type": "number" }
    },
    "required": ["query"]
  }
```

### Call a Tool

```bash
# With inline JSON
$ mcp-s-cli call search_issues '{"query": "bug in authentication", "limit": 5}'

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

# Read JSON args from stdin (no '-' needed)
$ 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
```

### Initialize Global Config

Set up `~/.config/mcp-s-cli/config.json` with your Webrix MCP Gateway:

```bash
# Interactive (prompts for connection type, credentials)
mcp-s-cli init

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

# HTTP mode — provide a custom base URL
mcp-s-cli init --base-url https://<your-org>.mcp-s.com/mcp

# HTTP mode with optional mcp/toolkit headers
mcp-s-cli init --org <your-org> --mcp slack --toolkit my-tk

# stdio mode — add a user access key (runs via npx @mcp-s/mcp)
mcp-s-cli init --org <your-org> --mcp slack --toolkit my-tk --user-access-key <key>
mcp-s-cli init --base-url example.com --mcp slack --user-access-key <key>
```

| Option                    | Description                                                    |
| ------------------------- | -------------------------------------------------------------- |
| `--org <org>`             | Org name — derives URL as `https://<org>.mcp-s.com/mcp`        |
| `--base-url <url>`        | Custom server URL                                              |
| `--mcp <id>`              | MCP identifier (sent as `x-mcp` header or `MCP` env var)       |
| `--toolkit <name>`        | Toolkit name (sent as `x-toolkit` header or `TOOLKIT` env var) |
| `--user-access-key <key>` | User access key — triggers stdio mode                          |

**Mode selection:**

- `--user-access-key` absent → **HTTP mode**: produces a `baseUrl` + optional headers config
- `--user-access-key` present → **stdio mode**: produces a stdio config running `npx -y @mcp-s/mcp` with env vars

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

> **Note:** `init` overwrites the global config file. It is intended as a quick-start helper.

### Authentication

```bash
# Log in via OAuth (opens browser)
mcp-s-cli login

# Log out (removes stored tokens from auth.json)
mcp-s-cli logout

# Show current auth state and config location
mcp-s-cli whoami
```

### Maintenance

```bash
# Reset server config (sets config.json to {})
mcp-s-cli clear

# Remove all stored OAuth tokens (sets auth.json to {})
mcp-s-cli clear-auth
```

---

## Config File Format

The config file lives at `~/.config/mcp-s-cli/config.json` (or a custom path via `-c`/`MCP_S_CLI_CONFIG_PATH`).

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

For stdio mode (using a user access key):

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

**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 via `npx @mcp-s/mcp` |
| `allowedTools`  | Glob patterns of tools to allow (optional)                 |
| `disabledTools` | Glob patterns of tools to exclude (optional)               |
| `settings`      | Per-agent behavioral settings (see below)                  |

Environment variable substitution is supported: `"token": "${MY_TOKEN}"`.

### `settings` block

The optional `settings` block lets you tune behavioral settings per config file — useful when different AI agents use different configs and need different tuning:

```json
{
  "org": "my-org",
  "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 (`0` = disable) | `3`     |
| `retryDelay`    | Base retry delay (milliseconds)                     | `1000`  |
| `daemon`        | Enable connection caching (daemon mode)             | `true`  |
| `daemonTimeout` | Idle timeout for cached connections (seconds)       | `300`   |
| `history`       | Append each invocation to `history.jsonl`           | `false` |

## Working with Complex JSON Arguments

For arguments containing single quotes, special characters, or multi-line content, use stdin to avoid shell escaping issues:

```bash
# Heredoc (clean, no escaping needed)
mcp-s-cli call create_ticket <<EOF
{"title": "It's broken", "description": "User said \"it doesn't work\""}
EOF

# From a file
cat args.json | mcp-s-cli call some_tool

# Using jq to build the payload
jq -n '{query: "open bugs", assignee: "me"}' | mcp-s-cli call search_issues
```

---

## Chaining and Scripting

Chain MCP calls using shell pipes and `jq`:

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

# Conditional: check something exists before acting on it
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 in scripts
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
```

**Tips:**

- Use `jq -r` for raw string output (no surrounding quotes)
- Use `jq -e` for conditional checks (exits 1 if false/null)
- Use `2>/dev/null` to suppress errors when testing existence
- Use `jq -s '.'` to merge multiple JSON outputs into an array

---

## Configuration

### Environment Variables

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

---

## Using with AI Agents

`mcp-s-cli` is designed to give AI coding agents direct access to the Webrix MCP Gateway via the shell. Rather than loading full tool schemas into the agent's context window (which consumes thousands of tokens), the CLI lets agents discover and call tools on demand.

### System Prompt Integration

Add this to your AI agent's system prompt:

```xml
## 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 (stdin for JSON args)
  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

Examples:
  mcp-s-cli call search_issues '{"query": "open bugs"}'
  echo '{"query": "urgent"}' | mcp-s-cli call search_issues
  mcp-s-cli call create_ticket <<EOF
  {"title": "Bug", "description": "Details here"}
  EOF
```

### Agents Skill

For AI agents that support Skill files (Cursor, Gemini CLI, Claude Code, etc.), use the included `SKILL.md` in your skills directory for a ready-made integration.

### Common Errors

| Wrong command                  | Error code           | Fix                                |
| ------------------------------ | -------------------- | ---------------------------------- |
| `mcp-s-cli run tool`           | `UNKNOWN_SUBCOMMAND` | Use `call`                         |
| `mcp-s-cli list`               | `UNKNOWN_SUBCOMMAND` | Use `mcp-s-cli` (no subcommand)    |
| `mcp-s-cli call tool bad_json` | `INVALID_JSON_ARGS`  | Use valid JSON: `'{"key": "val"}'` |

---

## Architecture

### Connection Model

Each CLI invocation connects to the single configured server.

| Command                      | Behaviour                         |
| ---------------------------- | --------------------------------- |
| `mcp-s-cli` (list all)       | Connects to the configured server |
| `mcp-s-cli grep <query>`     | Connects to the configured server |
| `mcp-s-cli info <tool>`      | Connects to the configured server |
| `mcp-s-cli call <tool> '{}'` | Connects to the configured server |

### Connection Pooling (Daemon)

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

```bash
mcp-s-cli call some_tool '{}'        # Uses cached connection (default)
MCP_S_CLI_DEBUG=1 mcp-s-cli info     # See connection debug output
```

To disable daemon for a specific config, add `"settings": { "daemon": false }` to `config.json`.

With daemon disabled, each CLI call opens a fresh connection and closes it when done.

### Error Handling and Retry

The CLI automatically retries transient failures with exponential backoff.

**Retried automatically:** network errors (`ECONNREFUSED`, `ETIMEDOUT`, `ECONNRESET`), HTTP `429`, `502`, `503`, `504`

**Fail immediately:** config errors, auth errors (`401`, `403`), tool not found, invalid JSON

---

## Error Messages

All errors include actionable recovery suggestions, optimized for humans and AI agents alike:

```
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"
  Details: Available tools: search_issues, create_ticket, list_channels (+5 more)
  Suggestion: Run 'mcp-s-cli' to see all available tools

Error [INVALID_JSON_ARGUMENTS]: Invalid JSON in tool arguments
  Details: Parse error: Unexpected identifier "test"
  Suggestion: Arguments must be valid JSON. Use single quotes: '{"key": "value"}'
```

---

## License

MIT License — see [LICENSE](LICENSE) for details.