smithery-ai-cli
smithery.ai
Find, connect, and use 100K+ MCP tools and skills via the Smithery CLI marketplace.
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- Node.js and npm installed
- Smithery CLI installed globally: npm install -g @smithery/cli
- Smithery account and browser for OAuth authentication
How to use smithery-ai-cli
- 1.Run smithery auth login to authenticate (browser confirmation required)
- 2.Search for an MCP server: smithery mcp search "service-name"
- 3.Add a connection: smithery mcp add "url-or-name" --id connection-id
- 4.List available tools: smithery tool list connection-id
- 5.Inspect a tool's schema: smithery tool get connection-id tool-name
- 6.Call a tool: smithery tool call connection-id tool-name '{json-args}'
Use cases
- 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
- 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
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.
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.
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.
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.
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 toolsauth_required: human must open authorization URLerror: 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
--policyflag - 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:
metadatafor connection-level restrictionrpcReqMatchfor 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.
