Skip to content

Editorial improvements for #826 #828

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
github-actions wants to merge 3 commits into from
Closed

Editorial improvements for #826 #828

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
788509b
Editorial: Structure - Added intro line; changed "Your Server" to "yo…
github-actions[bot] Feb 26, 2026
5b43b56
Editorial: Structure - Added intro line; Structure - Changed headings…
github-actions[bot] Feb 26, 2026
81fd2d0
Editorial: Structure - Added intro line; Terminology - Changed "We" t…
github-actions[bot] Feb 26, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 13 additions & 11 deletions app/en/get-started/quickstarts/mcp-server-quickstart/page.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,12 +7,14 @@ import { Steps, Tabs, Callout } from "nextra/components";
import { SignupLink } from "@/app/_components/analytics";
import { GuideOverview } from "@/app/_components/guide-overview";

# Build MCP Server QuickStart
# Build MCP server quickstart

Build and run an MCP server with tools that you create.

<GuideOverview>
<GuideOverview.Outcomes>

Build and run an MCP Server with tools that you create.
Build and run an MCP server with tools that you create.

</GuideOverview.Outcomes>

Expand Down Expand Up @@ -67,9 +69,9 @@ pip install arcade-mcp
</Tabs.Tab>
</Tabs>

## Create Your Server
## Create your server

In your terminal, run the following command to scaffold a new MCP Server called `my_server`:
In your terminal, run the following command to scaffold a new MCP server called `my_server`:

```bash
arcade new my_server
Expand Down Expand Up @@ -100,7 +102,7 @@ my_server/

> If you're having issues with the `arcade` command, please see the [Troubleshooting](#troubleshooting) section.

## Setup the secrets in your environment
## Set up the secrets in your environment

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 you to set a secret key in your environment. If you don't set the secret, the tool will return an error.

Expand Down Expand Up @@ -166,9 +168,9 @@ arcade login

Follow the instructions in your browser to connect your terminal to your Arcade account.

## Run your MCP Server
## Run your MCP server

Run your MCP Server using one of the following commands in your terminal:
Run your MCP server using one of the following commands in your terminal:

<Tabs
items={["stdio transport (default)", "http transport"]}
Expand Down Expand Up @@ -223,9 +225,9 @@ You should see output like this in your terminal:
INFO | 13:46:11 | arcade_mcp_server.mcp_app:299 | Starting my_server v1.0.0 with 3 tools
```

## Configure your MCP Clients
## Configure your MCP clients

Now you can connect MCP Clients to your MCP server:
Now you can connect MCP clients to your MCP server:

<Tabs
items={["Cursor IDE", "VS Code", "Claude Desktop"]}
Expand Down Expand Up @@ -292,10 +294,10 @@ Ensure you run `arcade login` and follow the instructions in your browser to con

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. If you are using the stdio transport, then ensure you add the environment variable to the MCP client's configuration file.

## Next Steps
## Next steps

- **Learn how to write a tool with auth**: [Create a tool with auth](/guides/create-tools/tool-basics/create-tool-auth)
- **Learn how to write a tool with secrets**: [Create a tool with secrets](/guides/create-tools/tool-basics/create-tool-secrets)
- **Learn more about the Context object**: [Tools and Context](/guides/create-tools/tool-basics/runtime-data-access)
- **Learn how to write tool evaluations**: [Create an evaluation suite](/guides/create-tools/evaluate-tools/create-evaluation-suite) to optimize them for LLM usage
- **Learn how to deploy your MCP server**: [Deploy your MCP server](/guides/deployment-hosting/arcade-deploy)
- **Learn how to deploy your MCP server**: [Deploy your MCP server](/guides/deployment-hosting/arcade-deploy)
44 changes: 23 additions & 21 deletions app/en/guides/create-tools/tool-basics/build-mcp-server/page.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,9 @@ import { Steps, Tabs, Callout } from "nextra/components";

# Creating an MCP Server with Arcade

The `arcade_mcp_server` package is the secure framework to build and run MCP servers with your Arcade tools. It is easiest to use with the `arcade-mcp` package (Arcade's CLI) which can scaffold your MCP server with all the necessary files and dependencies, configure MCP Clients to connect to your server, deploy your server to the cloud, and more. This guide walks you through the complete process of creating a custom MCP server with Arcade.
Create, test, and deploy a custom MCP server using Arcade's secure framework and CLI tools.

The `arcade_mcp_server` package is the secure framework to build and run MCP servers with your Arcade tools. It is easiest to use with the `arcade-mcp` package (Arcade's CLI) which can scaffold your MCP server with all the necessary files and dependencies, configure MCP clients to connect to your server, deploy your server to the cloud, and more. This guide walks you through the complete process of creating a custom MCP server with Arcade.

<GuideOverview>
<GuideOverview.Outcomes>
Expand All @@ -26,7 +28,7 @@ Build and run a secure MCP server with tools that you define.

- How to run MCP servers with Arcade tools using the [`arcade_mcp_server`](/references/mcp/python) package
- How to use `arcade new` from the `arcade-mcp` CLI to create your server project with all necessary files and dependencies.
- How to run your local MCP Server with the Arcade CLI and register it with the Arcade Engine so that your agent can find and use your tool.
- How to run your local MCP server with the Arcade CLI and register it with the Arcade Engine so that your agent can find and use your tool.

</GuideOverview.YouWillLearn>
</GuideOverview>
Expand Down Expand Up @@ -63,9 +65,9 @@ pip install arcade-mcp
</Tabs.Tab>
</Tabs>

## Create Your Server
## Create your server

In your terminal, run the following command to scaffold a new MCP Server called `my_server`:
In your terminal, run the following command to scaffold a new MCP server called `my_server`:

```bash
arcade new my_server
Expand All @@ -84,9 +86,9 @@ my_server/
└── pyproject.toml
```

1. **server.py** Main server file with MCPApp and example tools. It creates an `MCPApp`, defines tools with `@app.tool`, and will start the server with `app.run()` when the file is executed directly.
1. **server.py** Main server file with MCPApp and example tools. It creates an `MCPApp`, defines tools with `@app.tool`, and will start the server with `app.run()` when you run the file directly.
1. **pyproject.toml** Dependencies and project configuration
1. **.env.example** Example `.env` file at the project root containing a secret required by one of the generated tools in `server.py`. Arcade automatically discovers `.env` files by traversing upward from the current directory, so placing it at the project root makes it accessible from any subdirectory. Environments are loaded on server start, so **if you update the `.env` file, you will need to restart your server.**
1. **.env.example** Example `.env` file at the project root containing a secret required by one of the generated tools in `server.py`. Arcade automatically discovers `.env` files by traversing upward from the current directory, so placing it at the project root makes it accessible from any subdirectory. The system loads environments on server start, so **if you update the `.env` file, you will need to restart your server.**

```python filename="server.py" showLineNumbers
#!/usr/bin/env python3
Expand All @@ -112,7 +114,7 @@ def greet(name: Annotated[str, "The name of the person to greet"]) -> str:
@app.tool(requires_secrets=["MY_SECRET_KEY"])
def whisper_secret(context: Context) -> Annotated[str, "The last 4 characters of the secret"]:
"""Reveal the last 4 characters of a secret"""
# Secrets are injected into the context at runtime.
# The runtime injects secrets into the context.
# LLMs and MCP clients cannot see or access your secrets
# You can define secrets in a .env file.
try:
Expand All @@ -133,12 +135,12 @@ async def get_posts_in_subreddit(
subreddit = subreddit.lower().replace("r/", "").replace(" ", "")

# Prepare the httpx request
# OAuth token is injected into the context at runtime.
# The runtime injects OAuth token into the context.
# LLMs and MCP clients cannot see or access your OAuth tokens.
oauth_token = context.get_auth_token_or_empty()
headers = {
"Authorization": f"Bearer {oauth_token}",
"User-Agent": "finally-mcp-server",
"User-Agent": "finally mcp server",
}
params = {"limit": 5}
url = f"https://oauth.reddit.com/r/{subreddit}/hot"
Expand All @@ -157,17 +159,17 @@ if __name__ == "__main__":
# - "stdio" (default): Standard I/O for Claude Desktop, CLI tools, etc.
# Supports tools that require_auth or require_secrets out-of-the-box
# - "http": HTTPS streaming for Cursor, VS Code, etc.
# Does not support tools that require_auth or require_secrets unless the server is deployed
# Does not support tools that require_auth or require_secrets unless you deploy the server
# using 'arcade deploy' or added in the Arcade Developer Dashboard with 'Arcade' server type
transport = sys.argv[1] if len(sys.argv) > 1 else "stdio"

# Run the server
app.run(transport=transport, host="127.0.0.1", port=8000)
```

## Setup the secrets in your environment
## Set up the secrets in your environment

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.
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 in your environment. If you do not set the secret, the tool will return an error.

<Tabs items={[".env file", "Environment Variable"]}>
<Tabs.Tab>
Expand All @@ -177,7 +179,7 @@ You can create a `.env` file at your project root directory and add your secret:
MY_SECRET_KEY="my-secret-value"
```

Arcade automatically discovers `.env` files by traversing upward from the current directory through parent directories. This means you can place your `.env` file at the project root (`my_server/`), and it will be found even when running your server from a subdirectory like `src/my_server/`.
Arcade automatically discovers `.env` files by traversing upward from the current directory through parent directories. This means you can place your `.env` file at the project root (`my_server/`), and the system will find it even when running your server from a subdirectory like `src/my_server/`.

The generated project includes a `.env.example` file at the project root with the secret key name and example value.
You can rename it to `.env` to start using it.
Expand Down Expand Up @@ -231,11 +233,11 @@ Since the Reddit tool accesses information only available to your Reddit account
arcade login
```

Follow the instructions in your browser, and once you've finished, your terminal will be connected to your Arcade account.
Follow the instructions in your browser, and once you've finished, your terminal will connect to your Arcade account.

## Run your MCP Server
## Run your MCP server

Run your MCP Server using one of the following commands in your terminal:
Run your MCP server using one of the following commands in your terminal:

<Tabs
items={["stdio transport (default)", "http transport"]}
Expand All @@ -251,7 +253,7 @@ uv run server.py stdio
<Callout type="info">
When using the stdio transport, MCP clients typically launch the MCP server as
a subprocess. Because of this, the server may run in a different environment
and not have access to secrets defined in your local `.env` file. Please refer
and not have access to secrets that you define in your local `.env` file. Please refer
to the [create a tool with
secrets](/guides/create-tools/tool-basics/create-tool-secrets) guide for more
information.
Expand Down Expand Up @@ -289,9 +291,9 @@ You should see output like this in your terminal:
INFO | 13:46:11 | arcade_mcp_server.mcp_app:299 | Starting my_server v1.0.0 with 3 tools
```

## Configure your MCP Client(s)
## Configure your MCP clients

Now you can connect MCP Clients to your MCP server:
Now your MCP clients can connect to your MCP server:

<Tabs
items={["Cursor IDE", "VS Code", "Claude Desktop"]}
Expand Down Expand Up @@ -332,7 +334,7 @@ Now you can connect MCP Clients to your MCP server:
</Tabs.Tab>
</Tabs>

That's it! Your MCP server is running and connected to your AI assistant.
That's it Your MCP server is running and connected to your AI assistant.

</Steps>

Expand All @@ -351,4 +353,4 @@ That's it! Your MCP server is running and connected to your AI assistant.
- **Create custom tools that use secrets**: [Learn how to create tools with secrets](/guides/create-tools/tool-basics/create-tool-secrets)
- **Learn the capabilities of the `Context` object**: [Understanding the Context object](/guides/create-tools/tool-basics/runtime-data-access)
- **Evaluate your tools**: [Explore how to evaluate tool performance](/guides/create-tools/evaluate-tools/why-evaluate)
- **Deploy your MCP server**: [Learn how to deploy your MCP server](/guides/deployment-hosting/arcade-deploy)
- **Deploy your MCP server**: [Learn how to deploy your MCP server](/guides/deployment-hosting/arcade-deploy)
Loading