GitHubDashboard
Docs/CLI/Commands

CLI Command Reference

Complete reference for all MCP Shield CLI commands. Each command includes usage, options, and examples.

Authentication

login

Authenticate with MCP Shield via browser OAuth

Usage

mcp-shield login [options]
bash

Options

--no-browserPrint login URL instead of opening browser
--token <token>Authenticate with a specific token

Example

mcp-shield login

# Output:
# Opening browser for authentication...
# ✓ Authenticated as you@company.com
bash

logout

Clear local credentials and log out

Usage

mcp-shield logout
bash

Example

mcp-shield logout

# Output:
# ✓ Credentials cleared from ~/.mcpshield/credentials
bash

whoami

Display current authenticated user

Usage

mcp-shield whoami
bash

Example

mcp-shield whoami

# Output:
# Email: you@company.com
# Organization: your-org
# Role: admin
bash

Provider Management

providers list

List all connected providers

Usage

mcp-shield providers list [options]
bash

Options

--jsonOutput as JSON

Example

mcp-shield providers list

# Output:
# ┌──────────┬────────────┬───────────────────┬─────────────┐
# │ Provider │ Status     │ Connected As      │ Last Used   │
# ├──────────┼────────────┼───────────────────┼─────────────┤
# │ github   │ connected  │ your-username     │ 2 hours ago │
# │ vercel   │ connected  │ your@email.com    │ 1 day ago   │
# │ supabase │ expired    │ -                 │ 7 days ago  │
# └──────────┴────────────┴───────────────────┴─────────────┘
bash

providers connect

Connect a new provider via OAuth

Usage

mcp-shield providers connect <provider> [options]
bash

Options

--scopes <scopes>Request specific scopes (comma-separated)
--no-browserPrint authorization URL

Example

mcp-shield providers connect github

# Output:
# Opening browser to authorize GitHub...
# ✓ GitHub connected successfully
# Connected as: your-username
# Scopes: repo, read:org, read:user
bash

providers disconnect

Disconnect a provider

Usage

mcp-shield providers disconnect <provider>
bash

Example

mcp-shield providers disconnect github

# Output:
# ✓ GitHub disconnected
bash

providers refresh

Refresh provider credentials

Usage

mcp-shield providers refresh <provider>
bash

Example

mcp-shield providers refresh github

# Output:
# ✓ GitHub credentials refreshed
bash

MCP Invocation

mcp list

List available MCP tools

Usage

mcp-shield mcp list [options]
bash

Options

--provider <provider>Filter by provider
--jsonOutput as JSON

Example

mcp-shield mcp list --provider github

# Output:
# GitHub MCP Tools:
# ├── github:list_repos       List repositories
# ├── github:get_repo         Get repository details
# ├── github:create_issue     Create a new issue
# ├── github:list_issues      List issues
# └── github:create_pr        Create a pull request
bash

mcp invoke

Invoke an MCP tool through the governed proxy

Usage

mcp-shield mcp invoke <tool> [options]
bash

Options

--input <json>Tool input as JSON
--file <path>Read input from file
--dry-runSimulate without executing
--jsonOutput as JSON

Example

mcp-shield mcp invoke github:list_repos --input '{"limit": 5}'

# Output:
# ┌─────────────────────────┬───────────┬──────────────┐
# │ Repository              │ Visibility│ Last Updated │
# ├─────────────────────────┼───────────┼──────────────┤
# │ your-org/project-a      │ private   │ 2 hours ago  │
# │ your-org/project-b      │ public    │ 1 day ago    │
# └─────────────────────────┴───────────┴──────────────┘
#
# ✓ Policy: allowed (matched: default-allow-read)
# ✓ DLP: passed
# ✓ Audit: logged (event-id: evt_xxxxx)
bash

mcp describe

Show details about an MCP tool

Usage

mcp-shield mcp describe <tool>
bash

Example

mcp-shield mcp describe github:create_pr

# Output:
# Tool: github:create_pr
# Provider: GitHub
# Description: Create a pull request
#
# Input Schema:
# ├── repo (string, required)     Repository name
# ├── title (string, required)    PR title
# ├── body (string, optional)     PR description
# ├── head (string, required)     Source branch
# └── base (string, required)     Target branch
#
# Risk Level: high
# Default Policy: requires-approval
bash

Configuration

config generate

Generate configuration for AI tools

Usage

mcp-shield config generate <tool> [options]
bash

Options

--output <path>Output file path
--token <token>Embed specific token
--envUse environment variable reference

Example

mcp-shield config generate cursor

# Output:
# ✓ Config written to ~/.cursor/mcp.json
bash

config show

Display current configuration

Usage

mcp-shield config show
bash

Example

mcp-shield config show

# Output:
# Organization: your-org
# Environment: production
# API Endpoint: https://api.mcpshield.com
# Gateway: https://gateway.mcpshield.com
bash

config set

Set a configuration value

Usage

mcp-shield config set <key> <value>
bash

Example

mcp-shield config set environment staging

# Output:
# ✓ Set environment = staging
bash

Policies

policies list

List policies in your organization

Usage

mcp-shield policies list [options]
bash

Options

--jsonOutput as JSON

Example

mcp-shield policies list

# Output:
# ┌────────────────────────────┬──────────┬──────────────┐
# │ Policy                     │ Status   │ Priority     │
# ├────────────────────────────┼──────────┼──────────────┤
# │ default-allow-read         │ active   │ 100          │
# │ block-production-writes    │ active   │ 50           │
# │ security-team-elevated     │ active   │ 10           │
# └────────────────────────────┴──────────┴──────────────┘
bash

policies simulate

Simulate policy evaluation

Usage

mcp-shield policies simulate [options]
bash

Options

--mcp <tool>MCP tool to simulate
--user <email>User to simulate as
--input <json>Simulated input

Example

mcp-shield policies simulate --mcp github:create_pr --user alice@company.com

# Output:
# Policy Simulation Result:
# ┌───────────────┬──────────────────────────────────────┐
# │ Decision      │ ALLOW                                │
# │ Policy        │ dev-team-write-access                │
# │ Reason        │ User has developer role              │
# │ DLP           │ Would scan for: secrets, PII         │
# └───────────────┴──────────────────────────────────────┘
bash

Audit

audit list

List recent audit events

Usage

mcp-shield audit list [options]
bash

Options

--limit <n>Number of events (default: 20)
--user <email>Filter by user
--mcp <tool>Filter by MCP tool
--decision <decision>Filter by decision (allow/deny)
--jsonOutput as JSON

Example

mcp-shield audit list --limit 5

# Output:
# Recent Audit Events:
# ┌────────────────────┬───────────────────┬──────────┬─────────────┐
# │ Timestamp          │ MCP Tool          │ Decision │ User        │
# ├────────────────────┼───────────────────┼──────────┼─────────────┤
# │ 2024-01-15 14:32   │ github:list_repos │ allow    │ alice@co.io │
# │ 2024-01-15 14:31   │ github:create_pr  │ deny     │ bob@co.io   │
# │ 2024-01-15 14:28   │ vercel:deploy     │ allow    │ alice@co.io │
# └────────────────────┴───────────────────┴──────────┴─────────────┘
bash

audit get

Get details of an audit event

Usage

mcp-shield audit get <event-id>
bash

Example

mcp-shield audit get evt_xxxxx

# Output:
# Event: evt_xxxxx
# Timestamp: 2024-01-15T14:32:00Z
# User: alice@company.com
# MCP: github:list_repos
# Decision: allow
# Policy: default-allow-read
# DLP Result: passed
bash

Tokens

tokens list

List your API tokens

Usage

mcp-shield tokens list
bash

Example

mcp-shield tokens list

# Output:
# ┌───────────────────┬──────────┬─────────────┬─────────────┐
# │ Name              │ Type     │ Created     │ Last Used   │
# ├───────────────────┼──────────┼─────────────┼─────────────┤
# │ CI/CD Token       │ service  │ 30 days ago │ 2 hours ago │
# │ Development       │ user     │ 7 days ago  │ Just now    │
# └───────────────────┴──────────┴─────────────┴─────────────┘
bash

tokens create

Create a new API token

Usage

mcp-shield tokens create <name> [options]
bash

Options

--type <type>Token type (user/service)
--expires <duration>Expiration (e.g., 30d, 1y)
--scopes <scopes>Comma-separated scopes

Example

mcp-shield tokens create "CI/CD Token" --type service --expires 90d

# Output:
# ✓ Token created
#
# Token: mcp_live_xxxxxxxxxxxxxxxxxxxx
#
# ⚠ This token will only be shown once. Store it securely.
bash

tokens revoke

Revoke an API token

Usage

mcp-shield tokens revoke <token-id>
bash

Example

mcp-shield tokens revoke tok_xxxxx

# Output:
# ✓ Token revoked
bash

Global Options

These options can be used with any command:

--help, -hShow help for any command
--version, -vShow CLI version
--token <token>Use a specific API token
--env <env>Target environment (production, staging)
--jsonOutput results as JSON
--verboseShow detailed output
--quiet, -qSuppress non-essential output