# Custom MCP

> Connect any MCP-compatible server to an agent, including your own.

Source: https://docs.runbear.io/agents/tools/custom-mcp

Last updated: 2026-08-26

Runbear is a managed **MCP host** for Slack, Microsoft Teams, and Discord. Beyond the [managed catalog](/agents/tools/catalog.md), you can connect any MCP-compatible server to your agent — hosted services, internal APIs, or local servers exposed via a secure tunnel.

This page covers everything you need to connect, configure, and manage your own MCP servers in Runbear.

![Tools tab with Custom MCP category and integration catalog](/img/team-agent/custom-mcp/tools-tab-overview.png)

## Overview

Runbear acts as a full-fledged MCP client that connects your agent to external systems over the [Model Context Protocol](https://modelcontextprotocol.io/). When your agent needs to take an action or look up data, it:

1. Selects the right tool exposed by a connected MCP server
2. Sends a request to the server using the MCP protocol
3. Uses the response to formulate its answer in the conversation

Because Runbear runs as a managed cloud service, MCP servers must be reachable over HTTPS. See [Local development](#connect-a-local-mcp-server-secure-tunnel) for how to expose a local server securely.

## Supported transports

Runbear supports the two remote MCP transports defined in the MCP specification:

| Transport           | Protocol                           | When to use                                   |
| ------------------- | ---------------------------------- | --------------------------------------------- |
| **Streamable HTTP** | HTTP POST with streaming responses | Recommended default for most MCP servers      |
| **SSE**             | Server-Sent Events over HTTP       | Legacy servers using long-lived event streams |

STDIO transport (local process pipes) is not directly supported, because Runbear runs in the cloud. To expose a STDIO-based server, run it behind a local tunnel — see [Local development](#connect-a-local-mcp-server-secure-tunnel).

## Connect a custom MCP server

1. Open your agent in the Runbear dashboard and go to the **Tools** tab.
2. In the integration catalog, find the **Custom MCP** category and click **Add Custom MCP**.

![Add Custom MCP button](/img/team-agent/custom-mcp/add-custom-mcp-button.png)

3. In the **Add Remote MCP Server** dialog, fill in the connection details:

| Field              | Description                                                                 |
| ------------------ | --------------------------------------------------------------------------- |
| **Server Name**    | A friendly name to identify this server                                     |
| **Server URL**     | The HTTPS endpoint of your MCP server (e.g., `https://api.example.com/mcp`) |
| **Transport Type** | `Streamable HTTP` (default) or `SSE`                                        |
| **Authentication** | `OAuth`, `Static`, or `None` — see below                                    |
| **Custom Headers** | Optional extra HTTP headers sent on every request (expand to add)           |

![Add Remote MCP Server dialog](/img/team-agent/custom-mcp/server-config-dialog.png)

4. Click **Connect**. Runbear performs a handshake with your server and lists the discovered tools on the server tile.

## Authentication

Runbear supports three authentication modes for custom servers.

### OAuth

Select **OAuth** when your MCP server implements the OAuth 2.0 authorization flow defined in the MCP spec. Tokens are stored encrypted and refreshed automatically.

OAuth has two authorization methods:

- **Per-User** (default) — each team member connects their own account while talking to the agent. The agent acts on behalf of the signed-in user.
- **Shared** — a single set of credentials is shared with all users of the agent. Choose this only if you trust everyone on the agent with the underlying access.

### Static

Select **Static** when your server expects a fixed API key or bearer token. Configure the key/value pair in the **Custom Headers** section (for example `Authorization: Bearer sk-...`). The header is sent with every request. Values are encrypted at rest and never exposed in logs or to end users.

### None

Select **None** when your server does not require authentication — for example, when it's protected by an IP allowlist or VPN.

## Edit or disconnect a server

To update server details, open the **Tools** tab, click the server tile, and modify the fields. When editing a static header, leaving the value empty keeps the existing secret.

To disconnect, open the more-options menu on the server tile and select **Disconnect**. The agent immediately loses access to that server's tools; existing conversations are unaffected.

## Connect a local MCP server (secure tunnel)

For servers running on your own machine or inside a private network, expose them over HTTPS using a tunneling tool, then follow the [Connect a custom MCP server](#connect-a-custom-mcp-server) steps with the tunnel URL.

Any tunnel that produces a stable HTTPS URL works. Common options:

- [ngrok](https://ngrok.com/)
- [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/)
- [Tailscale Funnel](https://tailscale.com/kb/1223/funnel)

> **Note**
>
> Pair the tunnel URL with **Static header** authentication so that only Runbear's requests are accepted. Never expose an unauthenticated MCP server to the public internet.

## Writing effective tool definitions

The quality of your tool names, descriptions, and parameter schemas directly affects how reliably the agent picks the right tool. If your agent misuses a tool or fails to discover it, revisit the server definition before tuning prompts.

Recommended practices:

- **Names**: short, action-oriented verbs (`search_issues`, `create_invoice`)
- **Descriptions**: one or two sentences explaining when to use the tool and any notable side effects
- **Parameters**: give each parameter a description explaining expected format and constraints
- **Errors**: return descriptive error messages so the agent can recover or report clearly

## Troubleshooting

| Symptom                            | Likely cause                                   | Fix                                                                                                                            |
| ---------------------------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| "Failed to connect" on save        | URL unreachable, TLS error, or wrong transport | Verify the URL is HTTPS, the server is running, and the transport matches what the server implements                           |
| Server connects but lists no tools | Server not responding to `tools/list`          | Check the MCP server logs; ensure it advertises at least one tool                                                              |
| Tool calls time out                | Long-running tool or slow backend              | Return partial progress or move the work behind a background job                                                               |
| Authorization errors on every call | Expired token or wrong header value            | Re-authorize (OAuth) or update the static header value                                                                         |
| Tool not invoked by the agent      | Ambiguous or missing description               | Improve the tool description and parameter docs; see [Writing effective tool definitions](#writing-effective-tool-definitions) |

## Related

- [Tool catalog](/agents/tools/catalog.md) — managed servers Runbear hosts
- [Tool overview](/agents/tools/overview.md) — how the agent uses tools at runtime
- [Knowledge](/agents/knowledge/overview.md) — ground answers in synced documents