Skip to content

Commit ca5d698

Browse files
torresmateonearestnabors
torresmateo
and
nearestnabors
authored
local mcp clients config (#516)
* local mcp clients config * prerequisites as the first step * removed duplicated sentence * updated guide for configuring mcp clients * added disclaimer about the state of MCP client configurations * arcade configure guide * Update app/en/home/build-tools/call-tools-from-mcp-clients/page.mdx Co-authored-by: RL "Nearest" Nabors <236306+nearestnabors@users.noreply.github.com> * removed claude http command * implemented all feedback --------- Co-authored-by: RL "Nearest" Nabors <236306+nearestnabors@users.noreply.github.com>
1 parent ebf75e0 commit ca5d698

File tree

2 files changed

+320
-0
lines changed

2 files changed

+320
-0
lines changed

‎app/en/home/build-tools/_meta.tsx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,4 +7,5 @@ export default {
77
"organize-mcp-server-tools": "Organize MCP server tools",
88
"providing-useful-tool-errors": "Providing useful tool errors",
99
"retry-tools-with-improved-prompt": "Retry tools with improved prompt",
10+
"call-tools-from-mcp-clients": "Call tools from MCP clients",
1011
};

‎app/en/home/build-tools/call-tools-from-mcp-clients/page.mdx‎

Lines changed: 319 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,319 @@
1+
---
2+
title: "Call tools from MCP clients"
3+
description: "Learn how to call tools from MCP clients"
4+
---
5+
6+
import { Steps, Tabs, Callout } from "nextra/components";
7+
8+
# Call tools from MCP clients
9+
10+
<GuideOverview>
11+
<GuideOverview.Outcomes>
12+
13+
Configure your MCP clients to call tools from your MCP server.
14+
15+
</GuideOverview.Outcomes>
16+
17+
<GuideOverview.Prerequisites>
18+
19+
- [Arcade account](https://api.arcade.dev/signup)
20+
- [Arcade CLI](/home/arcade-cli)
21+
- [An MCP Server](/home/build-tools/create-a-mcp-server)
22+
- [uv package manager](https://docs.astral.sh/uv/getting-started/installation/)
23+
24+
</GuideOverview.Prerequisites>
25+
26+
<GuideOverview.YouWillLearn>
27+
28+
- How to configure your MCP clients depending on the transport type.
29+
- How to set the secrets for your MCP server in your client's configuration file.
30+
31+
</GuideOverview.YouWillLearn>
32+
</GuideOverview>
33+
34+
## Using the `arcade configure` command
35+
36+
For popular MCP clients, you can use the `arcade configure` command to configure your MCP client to call your MCP server. This will automatically add the MCP server to your client's configuration file. By default, it will use the stdio transport.
37+
38+
<Tabs
39+
items={["Cursor IDE", "VS Code", "Claude Desktop"]}
40+
storageKey="preferredAgent"
41+
>
42+
<Tabs.Tab>
43+
44+
```bash
45+
arcade configure cursor
46+
```
47+
48+
</Tabs.Tab>
49+
<Tabs.Tab>
50+
51+
```bash
52+
arcade configure vscode
53+
```
54+
55+
</Tabs.Tab>
56+
<Tabs.Tab>
57+
58+
```bash
59+
arcade configure claude
60+
```
61+
62+
</Tabs.Tab>
63+
</Tabs>
64+
65+
You can customize a lot of the configuration passing options to `arcade configure`. For example, to change the transport type to http, you can pass the `--transport` (or `-t`) option:
66+
67+
<Tabs
68+
items={["Cursor IDE", "VS Code", "Claude Desktop"]}
69+
storageKey="preferredAgent"
70+
>
71+
<Tabs.Tab>
72+
73+
```bash
74+
arcade configure cursor --transport http
75+
```
76+
77+
</Tabs.Tab>
78+
<Tabs.Tab>
79+
80+
```bash
81+
arcade configure vscode --transport http
82+
```
83+
84+
</Tabs.Tab>
85+
<Tabs.Tab>
86+
87+
Claude Desktop does not currently support the http transport.
88+
89+
</Tabs.Tab>
90+
</Tabs>
91+
92+
### stdio specific configuration
93+
94+
If you are using the stdio transport, `arcade configure` will assume the entrypoint (the script that contains the `MCPApp` instance and calls `app.run()`) to your MCP server is `server.py` and will set the working directory to the root of your project. You can override this with the `--entrypoint` (or `-e`) option:
95+
96+
<Callout type="info">
97+
Note that the `--entrypoint` determines only the filename of the entrypoint
98+
script, not the path to the script.
99+
</Callout>
100+
<Callout type="info">
101+
When using the stdio transport, `arcade configure` will automatically load the
102+
secrets from the `.env` file in the root of your project into the appropriate
103+
configuration file for your MCP client.
104+
</Callout>
105+
106+
<Tabs
107+
items={["Cursor IDE", "VS Code", "Claude Desktop"]}
108+
storageKey="preferredAgent"
109+
>
110+
<Tabs.Tab>
111+
112+
```bash
113+
arcade configure cursor --entrypoint my_server.py
114+
```
115+
116+
</Tabs.Tab>
117+
<Tabs.Tab>
118+
119+
```bash
120+
arcade configure vscode --entrypoint my_server.py
121+
```
122+
123+
</Tabs.Tab>
124+
<Tabs.Tab>
125+
126+
```bash
127+
arcade configure claude --entrypoint my_server.py
128+
```
129+
130+
</Tabs.Tab>
131+
</Tabs>
132+
133+
### http specific configuration
134+
135+
If you are using the streamable HTTP transport, `arcade configure` will assume the MCP server is running on the default port `8000` and that the MCP server is running locally (in localhost). You can override this with the `--host` (or `-h`) and `--port` (or `-p`) options:
136+
137+
<Tabs
138+
items={["Cursor IDE", "VS Code", "Claude Desktop"]}
139+
storageKey="preferredAgent"
140+
>
141+
<Tabs.Tab>
142+
143+
Run from a different port:
144+
145+
```bash
146+
arcade configure cursor -t http --port 8000
147+
```
148+
149+
If you want to configure an MCP server running on the Arcade Cloud, you can use the `--host` option:
150+
151+
```bash
152+
arcade configure cursor -t http --host arcade
153+
```
154+
155+
</Tabs.Tab>
156+
<Tabs.Tab>
157+
158+
Run from a different port:
159+
160+
```bash
161+
arcade configure vscode -t http --port 8000
162+
```
163+
164+
If you want to configure an MCP server running on the Arcade Cloud, you can use the `--host` option:
165+
166+
```bash
167+
arcade configure vscode -t http --host arcade
168+
```
169+
170+
</Tabs.Tab>
171+
<Tabs.Tab>
172+
173+
Claude Desktop does not currently support the http transport.
174+
175+
</Tabs.Tab>
176+
</Tabs>
177+
178+
### Other configuration options
179+
180+
If you have modified the default configuration of your MCP client, you can pass the `--config` (or `-c`) option to `arcade configure` to use your custom configuration file:
181+
182+
<Tabs
183+
items={["Cursor IDE", "VS Code", "Claude Desktop"]}
184+
storageKey="preferredAgent"
185+
>
186+
<Tabs.Tab>
187+
188+
```bash
189+
arcade configure cursor --config /path/to/your/config.json
190+
```
191+
192+
</Tabs.Tab>
193+
<Tabs.Tab>
194+
195+
```bash
196+
arcade configure vscode --config /path/to/your/config.json
197+
```
198+
199+
</Tabs.Tab>
200+
<Tabs.Tab>
201+
202+
```bash
203+
arcade configure claude --config /path/to/your/config.json
204+
```
205+
206+
</Tabs.Tab>
207+
</Tabs>
208+
209+
By default, `arcade configure` will use the current directory as the name of the MCP server. You can override this with the `--name` (or `-n`) option:
210+
211+
<Tabs
212+
items={["Cursor IDE", "VS Code", "Claude Desktop"]}
213+
storageKey="preferredAgent"
214+
>
215+
<Tabs.Tab>
216+
217+
```bash
218+
arcade configure cursor --name my_server
219+
```
220+
221+
</Tabs.Tab>
222+
<Tabs.Tab>
223+
224+
```bash
225+
arcade configure vscode --name my_server
226+
```
227+
228+
</Tabs.Tab>
229+
<Tabs.Tab>
230+
231+
```bash
232+
arcade configure claude --name my_server
233+
```
234+
235+
</Tabs.Tab>
236+
</Tabs>
237+
238+
## Manually configuring your MCP client
239+
240+
If your MCP client is not supported by the `arcade configure` command, you can manually add the MCP server to your client's configuration file.
241+
242+
Each MCP client has a different way of configuring MCP servers. This section covers the most common ways of configuring MCP servers adopted by the most popular MCP clients. However, you may find inconsistencies such as the need to specify the MCP server's type as its transport, or as "local" and "remote". Some MCP clients will use "env" to pass environment variables, while others may use "environment" or "inputs". Use this guide as a conceptual reference, but always refer to your MCP client's documentation for the most up-to-date information.
243+
244+
<Tabs
245+
items={["stdio (default)", "Streamable HTTP"]}
246+
>
247+
<Tabs.Tab>
248+
249+
When configuring your MCP client using the stdio transport, you need to ensure that the MCP server is called using the right version of python and within the correct working directory. For example, let's pretend this is your setup:
250+
251+
- Your virtual environment is located at `/path/to/your/project/.venv`
252+
- Your project is located at `/path/to/your/project`
253+
- The entrypoint to your MCP server is `server.py`
254+
- One of your tools requires the `MY_SECRET_KEY` environment variable to be set.
255+
- Your secrets are stored in the `/path/to/your/project/.env` file
256+
257+
Then, your MCP client's configuration file should look like this:
258+
259+
```json
260+
{
261+
"mcpServers": {
262+
"my_server": {
263+
"command": "/path/to/your/project/.venv/bin/python",
264+
"args": ["/path/to/your/project/server.py", "stdio"],
265+
"env": {
266+
"MY_SECRET_KEY": "my-secret-value"
267+
}
268+
}
269+
}
270+
}
271+
```
272+
273+
This will ensure that the command used by the MCP client to start the MCP server is the correct version of python and that the environment variables are set correctly.
274+
275+
</Tabs.Tab>
276+
<Tabs.Tab>
277+
278+
When configuring your MCP client using the Streamable HTTP transport, ensure the MCP server is started on the correct port and from the correct working directory. For example, if your setup is:
279+
280+
- Your virtual environment is located at `/path/to/your/project/.venv`
281+
- Your MCP server is located at `/path/to/your/project/server.py`
282+
- Your secrets are stored in the `.env` file
283+
284+
Activate the virtual environment:
285+
286+
```bash
287+
source /path/to/your/project/.venv/bin/activate
288+
```
289+
290+
run the MCP server using the http transport. The secrets will be loaded from the `.env` file:
291+
292+
```bash
293+
uv run server.py http
294+
```
295+
296+
Then, your MCP client's configuration file should look like this:
297+
298+
```json
299+
{
300+
"mcpServers": {
301+
"my_server": {
302+
"url": "http://127.0.0.1:8000",
303+
"transport": "http"
304+
}
305+
}
306+
}
307+
```
308+
309+
<Callout type="info">
310+
For security reasons, Local HTTP servers do not currently support managed
311+
authorization and secrets. If you need to use authorization or secrets, you
312+
should use the stdio transport and configure the Arcade API key and secrets in
313+
your MCP connection settings. If you intend to expose your HTTP MCP server to
314+
the public internet, please follow the [on-prem MCP
315+
server](/home/deployment/on-prem-mcp) guide for secure remote deployment.
316+
</Callout>
317+
318+
</Tabs.Tab>
319+
</Tabs>

0 commit comments

Comments
 (0)