Skip to content

Commit ecd752d

Browse files
kamathkamath
authored
Merge pull request smithery-ai#8 from smithery-ai/anirudh/update
add a ton of examples
2 parents 6d6f7a9 + aa8263e commit ecd752d

16 files changed

+1487
-203
lines changed

‎concepts/cli.mdx‎

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
---
2+
title: "Smithery CLI"
3+
description: "You can use the Smithery CLI to install MCP servers from the registry or debug your MCP servers in the Smithery playground"
4+
---
5+
6+
<Card
7+
title="View the Smithery CLI on GitHub"
8+
icon="github"
9+
href="https://github.com/smithery-ai/cli"
10+
>
11+
The Smithery CLI is a registry installer and manager for Model Context
12+
Protocol (MCP) servers, designed to be client-agnostic.
13+
</Card>
14+
15+
The Smithery CLI is really helpful for debugging your MCP servers. You can use it to:
16+
17+
- Install MCP servers from the registry
18+
- Debug your MCP servers in the Smithery playground
19+
- Build your MCP servers for production
20+
21+
## Examples
22+
23+
```bash
24+
# Show the help menu
25+
npx @smithery/cli --help
26+
27+
# Add the exa MCP server to Cursor
28+
npx -y @smithery/cli@latest install exa --client cursor --profile your-profile-123456 --key $SMITHERY_API_KEY
29+
30+
# Run a local MCP server running on port 3000 in the Smithery playground
31+
npx @smithery/cli@latest playground --port 3000 --key $SMITHERY_API_KEY
32+
```
33+
34+
## Reference
35+
36+
```bash
37+
npx @smithery/cli <command>
38+
```
39+
40+
### Available Commands
41+
42+
- `install <package>` - Install a package
43+
- `--client <name>` - Specify the AI client
44+
- `--config <json>` - Provide configuration data as JSON (skips prompts)
45+
- `uninstall <package>` - Uninstall a package
46+
- `--client <name>` - Specify the AI client
47+
- `inspect <server-id>` - Inspect a server interactively
48+
- `run <server-id>` - Run a server
49+
- `--config <json>` - Provide configuration for the server
50+
- `list clients` - List available clients
51+
- `list servers --client <name>` - List installed servers for specific AI client
52+
- `login` - Login with an API key (interactive)
53+
- `dev [entryFile]` - Start development server with hot-reload and tunnel
54+
- `--port <port>` - Port to run the server on (default: 8181)
55+
- `--key <apikey>` - Provide an API key
56+
- `--no-open` - Don't automatically open the playground
57+
- `--prompt <prompt>` - Initial message to start the playground with
58+
- `-c, --config <path>` - Path to config file (default: auto-detect smithery.config.js)
59+
- `build [entryFile]` - Build MCP server for production
60+
- `-o, --out <outfile>` - Output file path (default: .smithery/index.cjs)
61+
- `--transport <type>` - Transport type: shttp or stdio (default: shttp)
62+
- `-c, --config <path>` - Path to config file (default: auto-detect smithery.config.js)
63+
- `playground` - Open MCP playground in browser
64+
- `--port <port>` - Port to expose (default: 3000)
65+
- `--key <apikey>` - Provide an API key
66+
- Can pass command after `--` separator
67+
- `--help` - Show help message
68+
- `--verbose` - Show detailed logs for debugging
69+
70+
### Examples
71+
72+
```bash
73+
# Install a server (requires --client flag)
74+
npx @smithery/cli install mcp-obsidian --client claude
75+
76+
# Install a server with pre-configured data (skips prompts)
77+
npx @smithery/cli install mcp-obsidian --client claude --config '{"vaultPath":"path/to/vault"}'
78+
79+
# Remove a server
80+
npx @smithery/cli uninstall mcp-obsidian --client claude
81+
82+
# List available clients
83+
npx @smithery/cli list clients
84+
85+
# List installed servers for claude
86+
npx @smithery/cli list servers --client claude
87+
88+
# Inspect a specific server from smithery's registry
89+
npx @smithery/cli inspect mcp-obsidian
90+
91+
# Run a server with configuration
92+
npx @smithery/cli run mcp-obsidian --config '{"key":"value"}'
93+
94+
# Login and set API key
95+
npx @smithery/cli login
96+
97+
# Start development server with hot-reload
98+
npx @smithery/cli dev
99+
npx @smithery/cli dev server.ts --port 3000
100+
101+
# Build server for production
102+
npx @smithery/cli build
103+
npx @smithery/cli build server.ts --out dist/server.cjs --transport stdio
104+
105+
# Open playground in browser
106+
npx @smithery/cli playground
107+
npx @smithery/cli playground --port 3001 -- node dist/server.js
108+
109+
# Show help menu
110+
npx @smithery/cli --help
111+
112+
# Install with verbose logging for debugging
113+
npx @smithery/cli install mcp-obsidian --client claude --verbose
114+
```
115+
116+
### Important Notes
117+
118+
- Use `login` command to set your Smithery API key (required for some operations)
119+
- Remember to restart your AI client after installing or uninstalling servers
120+
- Use the `inspect` command for interactive server testing
121+
- Run without arguments to see the help menu
122+
- Use `--verbose` flag for detailed logs when troubleshooting
123+
- The `dev` command provides hot-reload for MCP server development
124+
- Use `playground` to test your MCP servers in an interactive web interface

‎concepts/data_policy.mdx‎

Lines changed: 0 additions & 40 deletions
This file was deleted.

‎concepts/playground.mdx‎

Lines changed: 0 additions & 6 deletions
This file was deleted.

‎concepts/profiles.mdx‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
---
2+
title: "Profiles"
3+
description: "How to use Smithery profiles and the registry API to easily transport your MCP identity between clients"
4+
---
5+
6+
# Profiles
7+
8+
When you connect to an MCP server through Smithery, we store your identity in a profile. This profile is then used to transport your identity between clients.
9+
10+
Similar to profiles on your browser, you can have a "Personal" profile with connections to Spotify, your personal Notion, etc. and a "Work" profile with connections to your work Notion, your work Slack, Linear, etc.
11+
12+
<Frame>
13+
<img src="/images/profile_list.png" alt="Smithery Profiles" />
14+
</Frame>
15+
16+
You can manage your profiles at [smithery.ai/account/profiles](https://smithery.ai/account/profiles).
17+
18+
Then, when you add a Smithery URL to a client that connects over OAuth, you can select the profile you want to use.
19+
20+
<Frame>
21+
<img src="/images/oauth_profile.png" />
22+
</Frame>
23+
24+
This will then securely transport your Smithery identity to the MCP client you are using, like Cursor or Claude Desktop.
25+
26+
To search for servers in a profile, check out the [page on searching servers with the registry API](/concepts/registry_search_servers).

‎concepts/registry_get_server.mdx‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
---
2+
title: "Registry: Get Server Info"
3+
description: "Use the registry API to get information about a specific MCP server"
4+
openapi: "GET /servers/{id}"
5+
---
6+
7+
You can also use the registry to get information about a specific MCP server.

‎concepts/registry_search_servers.mdx‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
---
2+
title: "Registry: Search Servers"
3+
description: "Use the registry to search for MCP servers"
4+
openapi: "GET /servers"
5+
---
6+
7+
# Search Servers
8+
9+
The registry is a list of MCP servers that are available to use. You can search for MCP servers by name, description, tags, or profile. To get started, all you need is a Smithery API Key. You can get one at [smithery.ai/account/api-keys](https://smithery.ai/account/api-keys).
10+
11+
<Tip>
12+
To search for servers in a profile, you'll need to get the [**profile
13+
ID**](https://smithery.ai/account/profiles), not the profile name.
14+
<Frame>
15+
<img src="/images/get_profile_id.png" alt="Warning" />
16+
</Frame>
17+
</Tip>

‎concepts/what_is_mcp.mdx‎

Lines changed: 53 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,57 @@
11
---
22
title: "What is MCP?"
3-
description: "What is MCP?"
3+
description: "What is MCP? How does it work? What does Smithery do with MCP?"
44
---
55

6-
- Local v. Remote, STDIO v. SSE v. SHTTP
6+
<Frame caption="Source: https://hoangndst.com/blog/model-context-protocol">
7+
<img src="/images/mcp.png" alt="MCP Diagram" />
8+
</Frame>
9+
10+
# What is MCP?
11+
12+
MCP (Model Context Protocol) is an open standard that enables LLMs to access bespoke tools and context, as long as the LLM supports MCP and the tool implements the MCP protocol.
13+
14+
### Use Cases
15+
16+
Broadly speaking, MCP is useful when you want your LLM to get information from the outside world or perform actions on your behalf:
17+
18+
- **Context**: Context is data that can be used by the LLM that may not be available in the LLM's training data. For example, your LLM might want to search the web or access internal company data.
19+
- **Tools**: Tools are functions that can be called by the LLM. This can be something like "open a pull request from one branch into main" or "send an email to a specific person".
20+
21+
### Servers, Clients, and Transports
22+
23+
MCP, just like HTTP, is a client-server protocol. The **client** is the LLM, and the **server** exposes tools to the LLM. The client and server communicate over a **transport**, which can be fully local or over the internet.
24+
25+
- **Servers** expose tools to a client.
26+
- **Clients** can call tools on a server.
27+
- **Transports** are how the client and server communicate with each other. This can be local (STDIO), over the internet (HTTP), or even over a custom transport.
28+
29+
<Card
30+
title="Read the official MCP documentation"
31+
icon="scroll"
32+
href="https://modelcontextprotocol.io/"
33+
>
34+
Learn more about MCP from the Model Context Protocol website
35+
(modelcontextprotocol.io)
36+
</Card>
37+
38+
# What does Smithery do with MCP?
39+
40+
Smithery is a platform that allows you to build MCP servers and clients. We allow users to find the right MCP server for their needs, and we allow developers to build MCP servers to expose to the world.
41+
42+
We have a diverse mix of MCP servers, both local (STDIO) and over the internet (HTTP). Here are some popular ones:
43+
44+
- [Desktop Commander](https://smithery.ai/server/@wonderwhy-er/desktop-commander) (Local, STDIO): Allow apps like Claude Desktop to run terminal commands on your computer.
45+
- [Exa](https://smithery.ai/server/exa) (Remote, HTTP): Access live web search results. Do Deep Research, get LinkedIn profiles, and more!
46+
- [Context7](https://smithery.ai/server/@upstash/context7-mcp) (Remote, HTTP): Let your IDE agent like Cursor Composer access documentation for your favorite libraries and SDKs.
47+
- [Browserbase](https://smithery.ai/server/@browserbasehq/mcp-browserbase) (Remote, HTTP): Use Claude Desktop/Cursor to control a remote web browser.
48+
49+
You can also build and deploy your own MCP servers on Smithery!
50+
51+
<Card
52+
title="Build and deploy your own MCP server to Smithery"
53+
icon="anvil"
54+
href="/getting_started/quickstart_build"
55+
>
56+
Learn how to build and deploy your own MCP server to Smithery
57+
</Card>

0 commit comments

Comments
 (0)