Skip to content

Commit 113194f

Browse files
torresmateonearestnabors
torresmateo
and
nearestnabors
authored
custom mcp server quickstart (#507)
* custom mcp server quickstart * Update app/en/home/custom-mcp-server-quickstart/page.mdx Co-authored-by: RL "Nearest" Nabors <[email protected]> * implemented latest round of feedback * better auth tool justification * sort MCP clients to put http first * added prompt examples * better secrets explanation * sync title --------- Co-authored-by: RL "Nearest" Nabors <[email protected]>
1 parent 2308637 commit 113194f

File tree

3 files changed

+222
-4
lines changed

3 files changed

+222
-4
lines changed

‎app/en/home/_meta.tsx‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,9 @@ export const meta: MetaRecord = {
4242
quickstart: {
4343
title: "Hosted Tools Quickstart",
4444
},
45+
"custom-mcp-server-quickstart": {
46+
title: "Build MCP Server QuickStart",
47+
},
4548
"api-keys": {
4649
title: "Get an API key",
4750
},

‎app/en/home/build-tools/create-a-tool-with-secrets/page.mdx‎

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -44,10 +44,6 @@ You can set the environment variable in your terminal like so:
4444
export SECRET_KEY="my-secret-value"
4545
```
4646

47-
```env filename=".env"
48-
SECRET_KEY="my-secret-value"
49-
```
50-
5147
Or you can create a `.env` file in the root of your project and add your secret:
5248

5349
```env filename=".env"

‎app/en/home/custom-mcp-server-quickstart/page.mdx‎

Lines changed: 219 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,219 @@
1+
---
2+
title: "Build MCP Server QuickStart"
3+
description: "Create your custom MCP Server with Arcade MCP"
4+
---
5+
6+
import { Steps, Tabs, Callout } from "nextra/components";
7+
import { SignupLink } from "@/app/_components/analytics";
8+
import { GuideOverview } from "@/app/_components/guide-overview";
9+
10+
# Build MCP Server QuickStart
11+
12+
<GuideOverview>
13+
<GuideOverview.Outcomes>
14+
15+
Most AI apps are stuck in read-only mode. Arcade gives your AI the power to act — send Gmail, update Notion, message in Slack, and more.
16+
17+
</GuideOverview.Outcomes>
18+
19+
<GuideOverview.Prerequisites>
20+
21+
- Python 3.10 or higher
22+
- For this guide, we'll use [uv](https://docs.astral.sh/uv/getting-started/installation/) as our package manager.
23+
24+
</GuideOverview.Prerequisites>
25+
26+
<GuideOverview.YouWillLearn>
27+
28+
- Install the Arcade MCP Framework
29+
- Start your MCP server and connect to it from your favorite MCP client
30+
- Call a simple tool
31+
- Call a tool that requires a secret
32+
- Create an Arcade account
33+
- Call a tool that requires authentication
34+
35+
</GuideOverview.YouWillLearn>
36+
</GuideOverview>
37+
38+
<Steps>
39+
40+
## Create your virtual environment
41+
42+
In your terminal, run the following command to create and activate a virtual environment:
43+
44+
```bash
45+
uv venv
46+
source .venv/bin/activate
47+
```
48+
49+
## Install the Arcade CLI
50+
51+
In your terminal, run the following command to install the `arcade-mcp` package:
52+
53+
```bash
54+
uv pip install arcade-mcp
55+
```
56+
57+
This package includes the CLI tools and the `arcade-mcp-server` library.
58+
59+
## Create Your Server
60+
61+
In your terminal, run the following command to scaffold a new MCP Server called `my_server`:
62+
63+
```bash
64+
arcade new my_server
65+
cd my_server
66+
```
67+
68+
This generates a complete project with:
69+
70+
- **server.py** Main server file with MCPApp and example tools
71+
- **pyproject.toml** Dependencies and project configuration
72+
- **.env.example** Example `.env` file containing a secret required by one of the generated tools in `server.py`
73+
74+
`server.py` includes proper structure with command-line argument handling. It creates an `MCPApp` with three sample tools:
75+
76+
- **`greet`**: This tool has a single argument, the name of the person to greet. It requires no secrets or auth
77+
- **`whisper_secret`**: This tool requires no arguments, and will output the last 4 characters of a `MY_SECRET_KEY` secret.
78+
- **`get_posts_in_subreddit`**: This tool has a single argument, a subreddit, and will return the latest posts on that subreddit, it requires the user to authenticate their reddit account.
79+
80+
> If you're having issues with the `arcade` command, please see the [Troubleshooting](#troubleshooting) section.
81+
82+
## Setup the secrets in your environment
83+
84+
Secrets are sensitive strings like passwords, api-keys, or other tokens that grant access to a protected resource or API. Arcade includes the "whisper_secret" tool that requires a secret key to be set in your environment. If the secret is not set, the tool will return an error.
85+
86+
<Tabs items={["Environment Variable", "Terminal"]}>
87+
<Tabs.Tab>
88+
You can create a `.env` file in the root of your project and add your secret:
89+
90+
```env filename=".env"
91+
MY_SECRET_KEY="my-secret-value"
92+
```
93+
94+
The project includes a `.env.example` file with the secret key name and example value.
95+
You can rename it to `.env` to start using it.
96+
97+
```bash
98+
mv .env.example .env
99+
```
100+
101+
</Tabs.Tab>
102+
<Tabs.Tab>
103+
You can set the environment variable in your terminal directly with this command:
104+
105+
```bash
106+
export MY_SECRET_KEY="my-secret-value"
107+
```
108+
109+
</Tabs.Tab>
110+
</Tabs>
111+
112+
## Connect to Arcade to enable authenticated tool calling
113+
114+
Since the Reddit tool accesses information only available to your Reddit account, you'll need to authorize it. For this, you'll need to create an Arcade account and connect to it from the terminal, run:
115+
116+
```bash
117+
arcade login
118+
```
119+
120+
Follow the instructions in your browser, and once you've finished, your terminal will be connected to your Arcade account.
121+
122+
## Run your MCP Server
123+
124+
Run your MCP Server using one of the with the following commands in your terminal:
125+
126+
<Tabs
127+
items={["HTTP transport (default)", "stdio transport (for Claude Desktop)"]}
128+
storageKey="preferredTransport"
129+
>
130+
131+
<Tabs.Tab>
132+
133+
```bash
134+
uv run server.py http
135+
```
136+
137+
For HTTP transport, view your server's API docs at [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs).
138+
139+
</Tabs.Tab>
140+
<Tabs.Tab>
141+
142+
```bash
143+
uv run server.py stdio
144+
```
145+
146+
</Tabs.Tab>
147+
</Tabs>
148+
149+
You should see output like this in your terminal:
150+
151+
```bash
152+
INFO | Starting server v1.0.0 (my_server)
153+
INFO | Added tool: greet
154+
INFO | Starting MCP server on http://127.0.0.1:8000
155+
```
156+
157+
## Configure your MCP Client(s)
158+
159+
Now you can connect your MCP server to apps that support MCP Clients, like AI assistants and IDEs. :
160+
161+
<Tabs
162+
items={["Cursor IDE", "VS Code", "Claude Desktop"]}
163+
storageKey="preferredAgent"
164+
>
165+
<Tabs.Tab>
166+
167+
```bash
168+
arcade configure cursor --from-local
169+
```
170+
171+
</Tabs.Tab>
172+
<Tabs.Tab>
173+
174+
```bash
175+
arcade configure vscode --from-local
176+
```
177+
178+
</Tabs.Tab>
179+
<Tabs.Tab>
180+
181+
```bash
182+
arcade configure claude --from-local
183+
```
184+
185+
</Tabs.Tab>
186+
</Tabs>
187+
188+
## Try it out!
189+
190+
Try calling your tool inside your assistant.
191+
192+
Here's some prompts you can try:
193+
194+
- "What's the latest post on r/mcp?"
195+
- "What's the last 4 characters of my secret key?"
196+
- "Greet me as Supreme MCP Master"
197+
198+
</Steps>
199+
200+
## Troubleshooting
201+
202+
### `arcade` command not found or not working
203+
204+
If you're getting issues with the `arcade` command, please make sure you did not install it outside of your virtual environment. For example, if your system-wide Python installation older than 3.10, you may need to uninstall arcade from that Python installation in order to the terminal to recognize the `arcade` command installed in your virtual environment.
205+
206+
### The Reddit tool is not working
207+
208+
Ensure you run `arcade login` and follow the instructions in your browser to connect to your Arcade account.
209+
210+
### The Whisper Secret tool is not working
211+
212+
Ensure you have set the environment variable in your terminal or `.env` file, and that it matches the secret key defined in the `@app.tool` decorator.
213+
214+
## Next Steps
215+
216+
- Try some of our [prebuilt MCP Servers](/mcp-servers) and get MCP tools that work with your favorite integrations
217+
- Learn more about the [Tool Context](/home/build-tools/tool-context) and building MCP tools with Arcade
218+
- Learn how to [evaluate tools](/home/evaluate-tools/why-evaluate-tools) to ensure they're working correctly
219+
- [Deploy](/home/serve-tools/arcade-deploy) your MCP server

0 commit comments

Comments
 (0)