a11f79b32d
1. Updates docs to prefer `uv run server.py` instead of `arcade mcp` or `python -m arcade_mcp_server` 2. Found a bug with running stdio servers while updating the docs, so i snuck that in this PR
165 lines
4.1 KiB
Markdown
165 lines
4.1 KiB
Markdown
# Quick Start
|
|
|
|
The `arcade_mcp_server` package provides powerful ways to run MCP servers with your Arcade tools. **We recommend using `arcade new`** from the `arcade-mcp` CLI to create your server project with all necessary files and dependencies.
|
|
|
|
## Recommended: Create with arcade new
|
|
|
|
### 1. Install the CLI
|
|
|
|
```bash
|
|
uv pip install arcade-mcp
|
|
```
|
|
|
|
The `arcade-mcp` package includes the CLI tools and the `arcade-mcp-server` library.
|
|
|
|
### 2. Create Your Server
|
|
|
|
```bash
|
|
arcade new my_server
|
|
cd my_server
|
|
```
|
|
|
|
This generates a complete project with:
|
|
|
|
- **server.py** - Main server file with MCPApp and example tools
|
|
|
|
- **pyproject.toml** - Dependencies and project configuration
|
|
|
|
- **.env.example** - Example `.env` file containing a secret required by one of the generated tools in `server.py`
|
|
|
|
The generated `server.py` includes proper structure with command-line argument handling:
|
|
|
|
```python
|
|
#!/usr/bin/env python3
|
|
import sys
|
|
from typing import Annotated
|
|
from arcade_mcp_server import MCPApp
|
|
|
|
app = MCPApp(name="my_server", version="1.0.0")
|
|
|
|
@app.tool
|
|
def greet(name: Annotated[str, "Name to greet"]) -> str:
|
|
"""Greet someone by name."""
|
|
return f"Hello, {name}!"
|
|
|
|
if __name__ == "__main__":
|
|
transport = sys.argv[1] if len(sys.argv) > 1 else "http"
|
|
app.run(transport=transport, host="127.0.0.1", port=8000)
|
|
```
|
|
|
|
### 3. Run Your Server
|
|
|
|
```bash
|
|
# Run with uv (recommended)
|
|
uv run server.py
|
|
|
|
# Run with HTTP transport (default)
|
|
uv run server.py http
|
|
|
|
# Run with stdio transport (for Claude Desktop)
|
|
uv run server.py stdio
|
|
```
|
|
|
|
You should see output like:
|
|
|
|
```text
|
|
INFO | Starting server v1.0.0 (my_server)
|
|
INFO | Added tool: greet
|
|
INFO | Added tool: add_numbers
|
|
INFO | Starting MCP server on http://127.0.0.1:8000
|
|
```
|
|
|
|
For HTTP transport, view your server's API docs at [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs).
|
|
|
|
### 4. Configure MCP Clients
|
|
|
|
Connect your server to AI assistants:
|
|
|
|
```bash
|
|
# Configure Claude Desktop
|
|
arcade configure claude --from-local
|
|
|
|
# Configure Cursor IDE
|
|
arcade configure cursor --from-local
|
|
|
|
# Configure VS Code
|
|
arcade configure vscode --from-local
|
|
```
|
|
|
|
That's it! Your MCP server is running and connected to your AI assistant.
|
|
|
|
|
|
## Building MCP Servers
|
|
|
|
The simplest way to create an MCP server programmatically is using `MCPApp`, which provides a FastAPI-like interface:
|
|
|
|
```python
|
|
from arcade_mcp_server import MCPApp
|
|
from typing import Annotated
|
|
|
|
app = MCPApp(
|
|
name="my_serve_",
|
|
version="1.0.0",
|
|
instructions="Custom MCP server with specialized tools"
|
|
)
|
|
|
|
@app.tool
|
|
def calculate(
|
|
expression: Annotated[str, "Mathematical expression to evaluate"]
|
|
) -> Annotated[float, "The result of the calculation"]:
|
|
"""Safely evaluate a mathematical expression."""
|
|
# Safe evaluation logic here
|
|
return eval(expression, {"__builtins__": {}}, {})
|
|
|
|
@app.tool
|
|
def fetch_data(
|
|
url: Annotated[str, "URL to fetch data from"]
|
|
) -> Annotated[dict, "The fetched data"]:
|
|
"""Fetch data from an API endpoint."""
|
|
import requests
|
|
return requests.get(url).json()
|
|
|
|
# Run the server
|
|
if __name__ == "__main__":
|
|
app.run(host="0.0.0.0", port=8080, reload=True)
|
|
```
|
|
|
|
|
|
|
|
## Secrets
|
|
|
|
Define your tool secrets in an environment file `.env` in the same directory as your `MCPApp`, or export as environment variables
|
|
|
|
```bash
|
|
# Tool secrets (available to tools via context)
|
|
MY_API_KEY="secret-value"
|
|
DATABASE_URL="postgresql://..."
|
|
```
|
|
|
|
## Development Tips
|
|
|
|
### Hot Reload
|
|
Use the `reload=True` parameter for development to automatically restart on code changes:
|
|
|
|
```python
|
|
app.run(host="127.0.0.1", port=8000, reload=True)
|
|
```
|
|
|
|
### Logging
|
|
- Set `log_level="DEBUG"` in MCPApp for verbose logging
|
|
- In stdio mode, logs go to stderr
|
|
- In HTTP mode, logs go to stdout
|
|
|
|
### Docs for your MCP Server
|
|
With HTTP transport, access API documentation at:
|
|
|
|
- http://localhost:8000/docs (Swagger UI)
|
|
|
|
- http://localhost:8000/redoc (ReDoc)
|
|
|
|
## Next Steps
|
|
|
|
- Check out the [Examples](../examples/README.md) for detailed tutorials
|
|
- Learn about [Client Integration](../clients/claude.md) with Claude Desktop, Cursor, and VS Code
|
|
- Explore the [MCPApp API](../api/mcp_app.md) for advanced server customization
|
|
- Read about [Transport Modes](../advanced/transports.md) (stdio vs HTTP)
|