Custom MCP

Runbear is a managed MCP host for Slack, Microsoft Teams, and Discord. Beyond the pre-built catalog, you can connect any MCP-compatible server to your Team 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.

Overview

Runbear acts as a full-fledged MCP client that connects your Team Agent to external systems over the Model Context Protocol. 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 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 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.

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)

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 steps with the tunnel URL.

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

• ngrok
• Cloudflare Tunnel
• Tailscale Funnel

tip

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

Related

• Pre-built MCP Servers — one-click managed integrations
• Tool overview — how the agent uses tools at runtime
• Knowledge Base — ground answers in synced documents