Custom MCP
Connect any MCP-compatible server to an agent, including your own.
On this page
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:
- Selects the right tool exposed by a connected MCP server
- Sends a request to the server using the MCP protocol
- 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#
- Open your agent in the Runbear dashboard and go to the Tools tab.
- In the integration catalog, find the Custom MCP category and click Add Custom MCP.
- In the Add Remote MCP Server dialog, fill in the connection details:
| Field | Description |
|---|---|
| Server Name | A name to identify this server. It is also how the rest of Runbear refers to the server: the server of a hook handler and the app field of the Tool integrations API both take this name |
| 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) |
- 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.
The OAuth option also shows these fields:
| Field | Description |
|---|---|
| Redirect URI | Shown once you enter a valid Server URL, with a copy button. Register this exact URI as the redirect URI in your server's OAuth configuration before saving. |
| Client ID | Optional. The OAuth client ID from your server's OAuth client configuration, shared across your organization. Leave the client ID and secret empty to reuse the client your organization already configured for this server URL, or when your server doesn't need one. |
| Authorization Server Issuer | Optional. The exact issuer from the authorization server metadata, such as https://example.com. |
| Client Secret | Optional. The secret for that client. When editing, leave it empty to keep the current value. |
| Required scopes | Optional. Comma-separated OAuth scopes to request at authorization time. |
Static#
Select Static when your server expects a fixed API key or bearer token. Enter the header name in Header Key (for example Authorization) and its value in Header Value (for example Bearer sk-...). The header is sent with every request. Values are encrypted at rest and never exposed in logs or to end users.
Custom Headers is a separate, optional section for any extra headers your server needs, whichever authentication mode you choose.
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's pill, and modify the fields. When editing a static header, leaving the value empty keeps the existing secret.
To disconnect, open the Tools tab, click the server's pill to open it, and click Disconnect in the dialog. The agent immediately loses access to that server's tools; existing conversations are unaffected. For an OAuth server, the same dialog also has Reconnect OAuth, which restarts authorization without changing the saved details.
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#
| 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#
- Tool catalog — managed servers Runbear hosts
- Tool overview — how the agent uses tools at runtime
- Knowledge — ground answers in synced documents