mcp-s-cli

A lightweight CLI for connecting AI agents to the Webrix 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 >= 18.

npm install -g @mcp-s/cli

Or run without installing:

npx @mcp-s/cli

2. Initialize config with your Webrix Gateway URL

# 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

# List all tools
mcp-s-cli

# With descriptions
mcp-s-cli -d

4. Call a tool

# 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

# 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

# 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

$ 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

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

# 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

# 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

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

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

For stdio mode (using a user access key):

{
  "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:

{
  "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:

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

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

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

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"}'

Contributing

Setup

git clone https://github.com/webrix-ai/mcp-cli.git
cd mcp-cli
npm install
npx simple-git-hooks   # register the pre-commit lint hook (once)

Development workflow

npm run dev        # run from source
npm run typecheck  # type check
npm run lint       # lint
npm test           # unit + integration tests

The pre-commit hook runs npm run lint:fix automatically before every commit and re-stages any auto-fixed files, so you never need to run it manually.

Releasing a new version to npm

1. Bump the version in package.json (e.g. 0.0.22 → 0.0.23)
2. Commit and push to main:

   git add package.json
   git commit -m "Release v0.0.23"
   git push origin main

3. That's it. The rest is automatic:
   • CI runs lint, type check, and tests
   • If CI passes and the version changed, Tag Release creates a v0.0.23 git tag
   • The new tag triggers Release, which builds and publishes to npm and creates a GitHub release

License

MIT License — see LICENSE for details.