Skip to content

Commit f0b88e1

Browse files
EricGustinEricGustin
authored
Migration guide from toolkit to MCP Server (#542)
* Migration from toolkit guide * . * Make stdio default
1 parent c03cb26 commit f0b88e1

File tree

2 files changed

+302
-0
lines changed

2 files changed

+302
-0
lines changed

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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,4 +8,5 @@ export default {
88
"providing-useful-tool-errors": "Providing useful tool errors",
99
"retry-tools-with-improved-prompt": "Retry tools with improved prompt",
1010
"call-tools-from-mcp-clients": "Call tools from MCP clients",
11+
"migrate-from-toolkits": "Migrate from toolkits",
1112
};

‎app/en/home/build-tools/migrate-from-toolkits/page.mdx‎

Lines changed: 301 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,301 @@
1+
---
2+
title: "Migrate from toolkits to MCP servers"
3+
description: "Learn how to migrate your existing Arcade toolkit to the new MCP Server framework"
4+
---
5+
6+
import { Steps, Callout } from "nextra/components";
7+
8+
# Migrate from toolkits to MCP servers
9+
10+
This guide helps you migrate your existing Arcade toolkit to the new MCP Server framework. The `arcade-tdk` package has been deprecated in favor of `arcade-mcp-server`, and the `arcade-ai` CLI has been replaced by `arcade-mcp`.
11+
12+
<Callout type="info">
13+
If you're building a new MCP server from scratch, check out the [Create an MCP
14+
Server](/home/build-tools/create-a-mcp-server) guide instead.
15+
</Callout>
16+
<Callout type="info">
17+
If you're migrating an existing toolkit to a new MCP server, it may be useful
18+
to read through our quickstart guide to get a sense of the new MCP Server
19+
framework: [Create an MCP Server](/home/build-tools/create-a-mcp-server)
20+
</Callout>
21+
22+
## Understanding the changes
23+
24+
Before migrating, it's helpful to understand what has changed:
25+
26+
### Terminology updates
27+
28+
- **Workers** are now called **servers** or **MCP servers**
29+
- **Toolkits** are now called **servers**, **MCP servers**, or **tools** depending on the context
30+
31+
### Package changes
32+
33+
- **arcade-ai** (old CLI) → **arcade-mcp** (new CLI)
34+
- **arcade-tdk** (old tool development kit) → **arcade-mcp-server** (new MCP Server framework)
35+
36+
The new `arcade-mcp-server` framework should feel familiar if you've used `arcade-tdk`, but there are important differences to be aware of.
37+
38+
<Steps>
39+
40+
## Update your dependencies
41+
42+
Open your `pyproject.toml` file and update the dependencies:
43+
44+
### Replace the main dependency
45+
46+
Replace `arcade-tdk` with `arcade-mcp-server`:
47+
48+
```toml
49+
[project]
50+
dependencies = [
51+
"arcade-mcp-server>=1.4.0,<2.0.0",
52+
# ... other dependencies
53+
]
54+
```
55+
56+
### Update development dependencies
57+
58+
If your toolkit used `arcade-ai` or `arcade-serve` as development dependencies, replace them with `arcade-mcp[all]`:
59+
60+
```toml
61+
[project.optional-dependencies]
62+
dev = [
63+
"arcade-mcp[all]>=1.3.0,<2.0.0",
64+
# ... other dev dependencies
65+
]
66+
```
67+
68+
### Install the updated dependencies
69+
70+
Run the following command to install the updated dependencies and development dependencies:
71+
72+
```bash
73+
uv sync --extra dev
74+
```
75+
76+
## Update your imports
77+
78+
Replace all imports from `arcade-tdk` with imports from `arcade-mcp-server`. Most import paths have remained the same or have only slight variations:
79+
80+
### Auth imports
81+
82+
```python
83+
# Before
84+
from arcade_tdk.auth import Google
85+
86+
# After
87+
from arcade_mcp_server.auth import Google
88+
```
89+
90+
### Tool decorator
91+
92+
```python
93+
# Before
94+
from arcade_tdk import tool
95+
96+
# After
97+
from arcade_mcp_server import tool
98+
```
99+
100+
### Error handling
101+
102+
```python
103+
# Before
104+
from arcade_tdk.errors import ToolExecutionError
105+
106+
# After
107+
from arcade_mcp_server.exceptions import ToolExecutionError
108+
```
109+
110+
### Context object
111+
112+
Replace `ToolContext` with `Context`:
113+
114+
```python
115+
# Before
116+
from arcade_tdk import ToolContext
117+
118+
@tool
119+
def my_tool(context: ToolContext) -> str:
120+
"""My tool that uses context"""
121+
return "Hello"
122+
123+
# After
124+
from arcade_mcp_server import Context
125+
126+
@tool
127+
def my_tool(context: Context) -> str:
128+
"""My tool that uses context"""
129+
return "Hello"
130+
```
131+
132+
<Callout type="warning">
133+
The `ToolContext` class is no longer used. Make sure to replace all instances
134+
of `ToolContext` with `Context` in your tool functions.
135+
</Callout>
136+
137+
## Create an entrypoint file
138+
139+
Previously, you would run your toolkit using the `arcade serve` CLI command. Now, you need to create an entrypoint file that runs your MCP server. This allows you to define your own startup and teardown logic for your MCP server.
140+
141+
An entrypoint file is a Python file that creates and runs an `MCPApp` when invoked. `MCPApp` is the developer-facing API for creating and managing your MCP server.
142+
143+
### Option 1: Use the tool decorator
144+
145+
You can register tools directly on the app using the `@app.tool` decorator:
146+
147+
```python
148+
#!/usr/bin/env python3
149+
"""My MCP Server"""
150+
151+
import sys
152+
from arcade_mcp_server import MCPApp
153+
154+
app = MCPApp(name="my_server", version="1.0.0")
155+
156+
@app.tool
157+
def echo_hello() -> str:
158+
"""Tool that just says hello"""
159+
return "Hello"
160+
161+
@app.tool
162+
def echo_goodbye() -> str:
163+
"""Tool that just says goodbye"""
164+
return "Goodbye"
165+
166+
if __name__ == "__main__":
167+
transport = sys.argv[1] if len(sys.argv) > 1 else "stdio"
168+
app.run(transport=transport)
169+
```
170+
171+
### Option 2: Register tools explicitly
172+
173+
You can also use the standalone `@tool` decorator and register tools explicitly:
174+
175+
```python
176+
#!/usr/bin/env python3
177+
"""My MCP Server"""
178+
179+
import sys
180+
from arcade_mcp_server import MCPApp, tool
181+
182+
@tool
183+
def echo_hello() -> str:
184+
"""Tool that just says hello"""
185+
return "Hello"
186+
187+
@tool
188+
def echo_goodbye() -> str:
189+
"""Tool that just says goodbye"""
190+
return "Goodbye"
191+
192+
app = MCPApp(name="my_server", version="1.0.0")
193+
app.add_tool(echo_hello)
194+
app.add_tool(echo_goodbye)
195+
196+
if __name__ == "__main__":
197+
transport = sys.argv[1] if len(sys.argv) > 1 else "stdio"
198+
app.run(transport=transport)
199+
```
200+
201+
### Option 3: Register tools from modules
202+
203+
If your old toolkit had many tools, you may want to use the `add_tools_from_module` method to register all your tools at once:
204+
205+
```python
206+
#!/usr/bin/env python3
207+
"""My MCP Server"""
208+
209+
import sys
210+
import my_module_with_tools
211+
212+
from arcade_mcp_server import MCPApp
213+
214+
app = MCPApp(name="my_server", version="1.0.0")
215+
app.add_tools_from_module(my_module_with_tools)
216+
217+
if __name__ == "__main__":
218+
transport = sys.argv[1] if len(sys.argv) > 1 else "stdio"
219+
app.run(transport=transport)
220+
```
221+
222+
<Callout type="info">
223+
For large toolkits with many tools, using `add_tools_from_module` is the
224+
recommended approach. This keeps your entrypoint file clean and maintainable.
225+
</Callout>
226+
227+
## Run your MCP server
228+
229+
Replace the old `arcade serve` command with direct execution of your entrypoint file:
230+
231+
```bash
232+
# Before
233+
arcade serve
234+
235+
# After
236+
uv run server.py
237+
```
238+
239+
You can specify the transport type as a command line argument:
240+
241+
```bash
242+
# Run with stdio transport (default)
243+
uv run server.py stdio
244+
245+
# Run with HTTP transport
246+
uv run server.py http
247+
```
248+
249+
## Update deployment configuration
250+
251+
The `arcade deploy` command still exists for deploying MCP servers, but the deployment process has been simplified.
252+
253+
### Before (with toolkits)
254+
255+
Previously, you would deploy your toolkit using:
256+
257+
```bash
258+
arcade deploy
259+
```
260+
261+
And configure your deployment with a `worker.toml` file.
262+
263+
### After (with MCP servers)
264+
265+
You still use `arcade deploy`, but you no longer need a `worker.toml` file:
266+
267+
```bash
268+
arcade deploy
269+
```
270+
271+
The deployment configuration is now inferred from your `MCPApp` and project structure.
272+
273+
<Callout type="info">
274+
You're no longer deploying a "worker" you're deploying an MCP server. The
275+
deployment process has been streamlined to require less configuration.
276+
</Callout>
277+
278+
</Steps>
279+
280+
## Quick reference
281+
282+
Here's a quick reference table for common changes:
283+
284+
| Old (toolkit) | New (MCP server) |
285+
| -------------------------------------------------- | ------------------------------------------------------------- |
286+
| `arcade-tdk` | `arcade-mcp-server` |
287+
| `arcade-ai` | `arcade-mcp` |
288+
| `arcade serve` | `uv run server.py` |
289+
| `from arcade_tdk import tool` | `from arcade_mcp_server import tool` |
290+
| `from arcade_tdk import ToolContext` | `from arcade_mcp_server import Context` |
291+
| `from arcade_tdk.errors import ToolExecutionError` | `from arcade_mcp_server.exceptions import ToolExecutionError` |
292+
| `worker.toml` | Not needed |
293+
294+
## Next steps
295+
296+
After migrating your toolkit to an MCP server:
297+
298+
- **Test your server**: Run your server locally and verify all tools work correctly
299+
- **Update your CI/CD**: Update any automated workflows to use the new CLI and commands
300+
- **Deploy your server**: Use `arcade deploy` to deploy your MCP server
301+
- **Configure MCP clients**: Connect your server to [MCP clients](/home/build-tools/call-tools-from-mcp-clients) like Claude Desktop, Cursor, or VS Code

0 commit comments

Comments
 (0)