Skip to content
Runbear Docs

Custom MCP

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

On this page
OverviewSupported transportsConnect a custom MCP serverAuthenticationOAuthStaticNoneEdit or disconnect a serverConnect a local MCP server (secure tunnel)Writing effective tool definitionsTroubleshootingRelated

Runbear is a managed MCP host for Slack, Microsoft Teams, and Discord. Beyond the managed catalog, 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.

Overview#

Runbear acts as a full-fledged MCP client that connects your 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:

TransportProtocolWhen to use
Streamable HTTPHTTP POST with streaming responsesRecommended default for most MCP servers
SSEServer-Sent Events over HTTPLegacy 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.

  1. In the Add Remote MCP Server dialog, fill in the connection details:
FieldDescription
Server NameA friendly name to identify this server
Server URLThe HTTPS endpoint of your MCP server (e.g., https://api.example.com/mcp)
Transport TypeStreamable HTTP (default) or SSE
AuthenticationOAuth, Static, or None — see below
Custom HeadersOptional extra HTTP headers sent on every request (expand to add)

  1. 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:

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#

SymptomLikely causeFix
"Failed to connect" on saveURL unreachable, TLS error, or wrong transportVerify the URL is HTTPS, the server is running, and the transport matches what the server implements
Server connects but lists no toolsServer not responding to tools/listCheck the MCP server logs; ensure it advertises at least one tool
Tool calls time outLong-running tool or slow backendReturn partial progress or move the work behind a background job
Authorization errors on every callExpired token or wrong header valueRe-authorize (OAuth) or update the static header value
Tool not invoked by the agentAmbiguous or missing descriptionImprove the tool description and parameter docs; see Writing effective tool definitions