---
lastModified: 2026-11-13
title: Add your own MCP server
description: Connect a remote MCP server by URL and choose what the Runner Agent may do with each of its tools.
seo:
  description: "Connect your own remote MCP server to Runner by URL, with or without an API key, and set each tool to Allow, Ask first, or Off before the Agent can use it."
---

If a service you use has an MCP server, you can give its tools to the Runner Agent. Paste
the server URL. Runner finds the server's tools. Then you choose what the Agent may do with
each tool.

Use this for a service that is not in **Connect your tools**, such as your own ERP, an
inventory system, or a tool your team runs.

## Before you start

**Entry path:** **Project → Agent → Tools → Add your own MCP server**

You need:

- the role of store owner or admin. Other members cannot add, change, or remove a server;
- the URL of a remote MCP server, such as `https://example.com/mcp`; and
- the API key and its header name, if the server needs a key.

The server must meet these conditions:

- It must be on the public internet. Runner does not connect to `localhost` or to a
  private network address.
- It must use the MCP HTTP transport (Streamable HTTP). Runner does not run a local
  command-line (stdio) server for you.
- It must use no sign-in or an API key in a request header. **OAuth** is not available
  yet.

A store can have up to 10 MCP servers. Runner keeps up to 100 tools from each server.

**Important:** Runner can't check what a custom server does with your data. Only add
servers you run or know well.

## Add a server

1. Open your project and select **Agent → Tools**.
2. On the **Add your own MCP server** row, select **Add server**.
3. Enter the **Server URL**. Or paste the JSON config from the server's docs into
   **Paste JSON config**. Runner fills in the URL and the key header from the config.
4. Optional: enter a **Name**. If you leave it empty, Runner uses the server's own name.
   Runner shows this name in chat when it uses a tool.
5. Under **How Runner signs in**, select **No sign-in** or **API key**. For **API key**,
   enter the **Header name** and the **Key**, such as `Authorization` and `Bearer sk-…`.
   Runner saves the key encrypted. Nobody, including you, can read it back.
6. **Which agents can use it** shows **All agents**. You can change this per agent later.
7. Select **I trust this server**.
8. Select **Connect and find tools**. Runner connects to the server and lists its tools.
9. Choose a rule for each tool. Then select **Add** followed by the server name.

When the server is added, it shows under **Connected** with the **Custom MCP** tag.

## Choose what each tool may do

Each tool gets one of three rules:

- **Allow:** the Agent uses the tool without asking you.
- **Ask first:** the Agent shows you the call in chat. The tool runs only after you approve it.
- **Off:** the Agent cannot use the tool.

Runner guesses a starting rule from each tool's name, and groups the tools by that rule:

| Group | Starting rule | Tool names that Runner puts here |
| --- | --- | --- |
| **Reads data** | **Allow** | Names that start with a read word, such as `list`, `get`, or `search`. Also every name that Runner does not recognize. |
| **Changes data** | **Ask first** | Names that contain `send`, `reply`, `remove`, `publish`, `pay`, `charge`, `refund`, or `price`. |
| **Deletes data** | **Off** | Names that contain `delete` or `trash`. |

**Check the rule of every tool before you add the server.** Runner reads only the tool's
name, not what the tool does. A tool such as `update_inventory` or `create_customer`
starts as **Allow** in **Reads data**, so the Agent could change data without asking you.
Set tools like these to **Ask first** or **Off**.

You can change the rule of any tool before you add the server. Later, change it under
**What any agent may do** on the server's page. A tool that the server adds later starts
as **Ask first**, or as **Off** if its name contains `delete` or `trash`.

The rules apply to every chat in this project. Runner checks them on each tool call.

## Manage a server

Open the server from **Connected** on **Agent → Tools**. Its page has these controls:

| Control or fact | What it does |
| --- | --- |
| Server URL and copy button | Under **Connection**. **Copy server URL** copies the URL. |
| **Health** | Shows when the server last answered, or **Not checked yet**. |
| **Sign-in** | Shows **No sign-in** or the last four characters of the key. **Add key** or **Replace** changes the key. |
| **Test connection** or **Refresh tools** | Connects to the server again and gets its current tool list. New tools start as **Ask first**, or **Off** for delete tools. |
| **Remove server** | Removes the server. Agents lose its tools, and its tool rules are deleted. You can add it again later. |

## If something goes wrong

| Message | What to do |
| --- | --- |
| **Enter a full server URL, like https://example.com/mcp.** | Enter the full URL, including the path. |
| **Runner can only reach public servers. This URL points to a private network.** | Use a URL that is reachable from the internet. |
| **This URL answered, but not as an MCP server. Check the path.** | Check the server's docs for the MCP path. It often ends in `/mcp`. |
| **Runner can't reach this server. Check the URL and that it is online.** | Make sure the server is running and the URL is correct. |
| **The server rejected the key. Check the header name and key.** | Check both values. Some servers need `Bearer ` before the key. |
| **The server answered but has no tools.** | The server has no tools for this key. Check the server's settings. |
| **This store has the most MCP servers it can add. Remove one first.** | Remove a server you do not use. |

On **Connected**, a server that stopped working shows **Can't reach** or **Key rejected**.
Select **Fix** to open the server, then replace the key or check the server.

## Related guides

- [Connect and control Agent Apps](./agent-apps)
- [Apps and integrations overview](../apps-and-integrations)
- [Troubleshoot an app connection](./troubleshooting)