smithery-ai-cli

Smithery

The marketplace for AI agents. Connect to 100K+ tools and skills instantly.

Use smithery --help and <command> --help for flags, arguments, and full examples. This skill focuses on concepts and canonical workflows.

Quick Start

# 1. Install
npm install -g @smithery/cli
 
# 2. Authenticate (requires human to confirm in browser)
smithery auth login
 
# 3. Search for MCP servers
smithery mcp search "github"
 

Core Concepts

Namespaces

A namespace is the workspace boundary for Smithery resources. Servers, connections, and skills all live in a namespace. Use one namespace per app/environment (for example, my-app-dev, my-app-prod), then set it as your active context. Canonical flow:

For namespace-specific flags and overrides, run smithery namespace --help and smithery mcp --help.

Connect (MCP Connections)

A connection is a managed, long-lived MCP session. Smithery Connect handles OAuth flow, credential storage, token refresh, and session lifecycle. Connection status model:

• connected: ready to list/call tools
• auth_required: human must open authorization URL
• error: inspect details and retry/fix config

Canonical flow (single user-scoped connection):

If CLI shows auth_required, tell your human to open the URL and then retry.

Token Scoping

Service tokens are restricted credentials for browser/mobile/agent usage. Never pass a full API key to untrusted code. Policy mental model:

• A token policy is one or more constraints
• In the CLI, pass one JSON object per --policy flag
• Fields inside one constraint are AND-ed (more fields = narrower)
• Lists and multiple constraints are OR-ed (more entries = wider)

Canonical user-scoped token:

Request-level Tool Restrictions (rpcReqMatch, experimental)

Use rpcReqMatch to restrict specific MCP JSON-RPC requests (regex by request path). Important: connection IDs are not in the JSON-RPC body, so combine:

• metadata for connection-level restriction
• rpcReqMatch for method/tool restriction

Canonical combined restriction:

Piped Output

When output is piped, Smithery commands emit JSONL (one JSON object per line):