---
title: "Build MCP Server QuickStart"
description: "Create your custom MCP Server with Arcade MCP"
---

import { Steps, Tabs, Callout } from "nextra/components";
import { SignupLink } from "@/app/_components/analytics";
import { GuideOverview } from "@/app/_components/guide-overview";

# Build MCP Server QuickStart

<GuideOverview>
<GuideOverview.Outcomes>

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

</GuideOverview.Outcomes>

<GuideOverview.Prerequisites>

- Python 3.10 or higher
- The [`uv` package manager](https://docs.astral.sh/uv/getting-started/installation/)

</GuideOverview.Prerequisites>

<GuideOverview.YouWillLearn>

- Install `arcade-mcp`, the secure framework for building MCP servers
- Start your MCP server and connect to it from your favorite MCP client
- Call a basic tool
- Call a tool that requires a secret
- Create an Arcade account
- Call a tool that requires auth

</GuideOverview.YouWillLearn>
</GuideOverview>

<Steps>

## Install the Arcade CLI

In your terminal, run the following command to install the `arcade-mcp` package - Arcade's CLI:

<Tabs items={["uv", "pip"]}>
  <Tabs.Tab>

```bash
uv tool install arcade-mcp
```

{" "}

<Callout type="info">
  This will install the Arcade CLI as a [uv
  tool](https://docs.astral.sh/uv/guides/tools/#installing-tools), making it
  available system wide.
</Callout>

  </Tabs.Tab>

  <Tabs.Tab>

```bash
pip install arcade-mcp
```

  </Tabs.Tab>
</Tabs>

## Create Your Server

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

```bash
arcade new my_server
cd my_server/src/my_server
```

This generates a Python module with the following structure:

```bash
my_server/
├── src/
│   └── my_server/
│       ├── __init__.py
│       ├── .env.example
│       └── server.py
└── pyproject.toml
```

- **server.py** Entrypoint 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`

`server.py` includes proper structure with command-line argument handling. It creates an `MCPApp` with three sample tools:

- **`greet`**: This tool has a single argument, the name of the person to greet. It requires no secrets or auth
- **`whisper_secret`**: This tool requires no arguments, and will output the last 4 characters of a `MY_SECRET_KEY` secret that you can define in your `.env` file.
- **`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 authorize the tool to perform a read operation on their behalf.

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

## Setup 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.

<Tabs items={[".env file", "Environment Variable"]}>
<Tabs.Tab>
You can create a `.env` file at the same directory as your entrypoint file (`server.py`) and add your secret:

```env filename=".env"
MY_SECRET_KEY="my-secret-value"
```

The generated project includes a `.env.example` file with the secret key name and example value.
You can rename it to `.env` to start using it.

```bash
mv .env.example .env
```

</Tabs.Tab>
<Tabs.Tab>
You can set the environment variable in your terminal directly with this command:

```bash
export MY_SECRET_KEY="my-secret-value"
```

</Tabs.Tab>
</Tabs>

## Connect to Arcade to unlock authorized tool calling

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 from the terminal, run:

```bash
arcade login
```

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

## Run your MCP Server

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

<Tabs
  items={["stdio transport (default)", "http transport"]}
  storageKey="preferredTransport"
>

<Tabs.Tab>

```bash
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
  to the [create a tool with
  secrets](/guides/create-tools/tool-basics/create-tool-secrets) guide for more
  information.
</Callout>

</Tabs.Tab>
<Tabs.Tab>

```bash
uv run server.py http
```

For HTTP transport, view your server's API docs at [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs).

<Callout type="info">
  For security reasons, Local HTTP servers do not currently support tool-level
  authorization and secrets. If you need to use tool-level authorization or
  secrets locally, you should use the stdio transport and configure the Arcade
  API key and secrets in your MCP connection settings. Otherwise, if you intend
  to expose your HTTP MCP server to the public internet with tool-level
  authorization and secrets, please follow the [deploying to the cloud with
  Arcade Deploy](/guides/deployment-hosting/arcade-deploy) guide or the [on-prem
  MCP server](/guides/deployment-hosting/on-prem) guide for secure remote
  deployment.
</Callout>

</Tabs.Tab>
</Tabs>

You should see output like this in your terminal:

```bash
2025-11-03 13:46:11.041 | DEBUG    | arcade_mcp_server.mcp_app:add_tool:242 - Added tool: greet
2025-11-03 13:46:11.042 | DEBUG    | arcade_mcp_server.mcp_app:add_tool:242 - Added tool: whisper_secret
2025-11-03 13:46:11.043 | DEBUG    | arcade_mcp_server.mcp_app:add_tool:242 - Added tool: get_posts_in_subreddit
INFO     | 13:46:11 | arcade_mcp_server.mcp_app:299 | Starting my_server v1.0.0 with 3 tools
```

## Configure your MCP Clients

Now you can connect MCP Clients to your MCP server:

<Tabs
  items={["Cursor IDE", "VS Code", "Claude Desktop"]}
  storageKey="preferredAgent"
>
  <Tabs.Tab>

    ```bash
    # Configure Cursor to use your MCP server with the default transport (stdio)
    arcade configure cursor

    # Configure Cursor to use your MCP server with the http transport
    arcade configure cursor --transport http
    ```

  </Tabs.Tab>
  <Tabs.Tab>

    ```bash
    # Configure VS Code to use your MCP server with the default transport (stdio)
    arcade configure vscode

    # Configure VS Code to use your MCP server with the http transport
    arcade configure vscode --transport http
    ```

  </Tabs.Tab>
  <Tabs.Tab>

    ```bash
    # Configure Claude Desktop to use your MCP server with the default transport (stdio)
    arcade configure claude

    # Configure Claude Desktop to use your MCP server with the http transport
    arcade configure claude --transport http
    ```

  </Tabs.Tab>
</Tabs>

## Try it out

Try calling your tool inside your assistant.

Here's some prompts you can try:

- "Get some posts from the r/mcp subreddit"
- "What's the last 4 characters of my secret key?"
- "Greet me as Supreme Lord of MCP"

</Steps>

## Troubleshooting

### `arcade` command not found or not working

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 for the terminal to recognize the `arcade` command installed in your virtual environment.

### The Reddit tool is not working

Ensure you run `arcade login` and follow the instructions in your browser to connect your terminal to your Arcade account.

### The Whisper Secret tool is not working

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

- **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)