PluginBench
Skill
Pass
Audit score 90

smithery-ai-cli

smithery.ai

Find, connect, and use 100K+ MCP tools and skills via the Smithery CLI marketplace.

View on skills.sh

What is smithery-ai-cli?

Smithery is a marketplace CLI for discovering and connecting to MCP servers and tools. Use it when you need to search for integrations, install skills, authenticate with external services (GitHub, Slack, Jira, Notion, etc.), and call tools programmatically.

  • Search and discover MCP servers from a 100K+ tool marketplace
  • Connect to external services with managed OAuth and credential storage
  • List and inspect tool schemas (input/output JSON)
  • Call tools directly from the CLI with arguments
  • Manage namespaces for workspace isolation and multi-environment setups
  • Create scoped service tokens with granular permission policies

How to install smithery-ai-cli

npx skills add null --skill smithery-ai-cli
Prerequisites
  • Node.js and npm installed
  • Smithery CLI installed globally: npm install -g @smithery/cli
  • Smithery account and browser for OAuth authentication
Claude Code
Cursor
Windsurf
Cline

How to use smithery-ai-cli

  1. 1.Run smithery auth login to authenticate (browser confirmation required)
  2. 2.Search for an MCP server: smithery mcp search "service-name"
  3. 3.Add a connection: smithery mcp add "url-or-name" --id connection-id
  4. 4.List available tools: smithery tool list connection-id
  5. 5.Inspect a tool's schema: smithery tool get connection-id tool-name
  6. 6.Call a tool: smithery tool call connection-id tool-name '{json-args}'

Use cases

Good for
  • Discover a GitHub integration and connect your account to create issues programmatically
  • Search for a Slack MCP server and authenticate to send messages from an agent
  • Set up separate namespaces for dev and prod environments with different tool connections
  • Generate a time-limited token restricted to specific tools for browser or mobile usage
  • List all available tools under a connected service to understand what's callable
Who it's for
  • AI agent developers building multi-tool workflows
  • DevOps engineers managing integrations across environments
  • Backend developers integrating external APIs and services
  • Teams needing secure, scoped credentials for untrusted code

smithery-ai-cli FAQ

What's the difference between a namespace and a connection?

A namespace is a workspace boundary for organizing resources (servers, connections, skills). A connection is a managed MCP session to a specific service with OAuth, credentials, and token refresh handled automatically.

How do I handle OAuth authentication?

Run smithery mcp add with a URL or name. If the connection shows auth_required status, the CLI will provide an authorization URL for the user to open in a browser. Retry the command after authorization completes.

Can I restrict which tools an agent can call?

Yes. Use token policies with metadata for connection-level restrictions and rpcReqMatch for method/tool-level restrictions. Combine both for granular control over what an agent can execute.

How do I use Smithery in a multi-environment setup?

Create separate namespaces (e.g., my-app-dev, my-app-prod), set each as active with smithery namespace use, and add connections within each namespace. This isolates credentials and tools per environment.

What output format does Smithery use when piping commands?

Piped output is JSONL (one JSON object per line), making it easy to filter and process tool lists or results with grep, jq, or other CLI tools.

Full instructions (SKILL.md)

Source of truth, from smithery.ai.


name: smithery-ai-cli description: Find, connect, and use MCP tools and skills via the Smithery CLI. Use when the user searches for new tools or skills, wants to discover integrations, connect to an MCP, install a skill, or wants to interact with an external service (email, Slack, Discord, GitHub, Jira, Notion, databases, cloud APIs, monitoring, etc.). metadata: { "openclaw": { "requires": { "bins": ["smithery"] }, "homepage": "https://smithery.ai" } }

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"

# 4. Connect to a server (URL or qualified name both work)
smithery mcp add "https://github.run.tools" --id github

# 5. Browse tools (tree view — drill into groups by passing the prefix)
smithery tool list github
smithery tool list github issues.

# 6. Inspect tool input/output JSON schema
smithery tool get github issues.create

# 7. Call a tool
smithery tool call github issues.create '{"repo": "owner/repo", "title": "Bug"}'

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:

smithery namespace list
smithery namespace create my-app-prod
smithery namespace use my-app-prod

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

smithery mcp add https://github.run.tools \
  --id user-123-github \
  --metadata '{"userId":"user-123"}'

smithery mcp list --metadata '{"userId":"user-123"}'
smithery tool list user-123-github

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:

smithery auth token --policy '{
  "namespaces": "my-app",
  "resources": "connections",
  "operations": ["read", "execute"],
  "metadata": { "userId": "user-123" },
  "ttl": "1h"
}'

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:

smithery auth token --policy '{
  "resources": "connections",
  "operations": "execute",
  "metadata": { "connectionId": "my-github" },
  "rpcReqMatch": {
    "method": "tools/call",
    "params.name": "^issues\\."
  },
  "ttl": "30m"
}'

Piped Output

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

smithery tool list github --flat --limit 1000 | grep label

Related skills

More from smithery.ai and the wider catalog.