Onboard external MCP servers

Entry point: Console → MCP Servers (admin only, database only).

This chapter covers how to add, list, view details, edit, and delete external MCP servers in the console. See MCP gateway proxy for a quick start that runs a working example, and MCP config for the configuration reference (tool ACL, context budget, REST bridge).

Add an MCP server

Console → MCP Servers → New:

Field	Description
Name	Unique, used as the tool prefix, regex ^[a-z0-9][a-z0-9_-]*$
Description	For UI display
transport	streamable_http (default) / sse
connection_type	stateful / stateless / rest_bridge (REST bridge)
endpoint	The upstream tool server URL
auth_header	The upstream Authorization header (e.g. Bearer ...)
extra_headers	Additional request headers
tags	Coarse-grained ACL filtering
priority	0–999, smaller = higher priority; used for context-budget trimming
idle_timeout_secs	Default 300
defer_loading	Load the tool schema only on first call
health_check	path / interval (default 60s) / timeout (default 5s)
max_concurrency	Per-access-key concurrency cap against this server
rate_limit	requests_per_second / tokens_per_minute
extra_config	For REST bridge, provide the simplified REST spec JSON here ({title, version, operations[]})
Enabled

Only the three transports HTTP / SSE / REST-bridge are supported; stdio / command / args / env / OAuth are not supported.

Choosing a connection type

Type	Use case
stateless (default)	Stateless tool server, each request independent
stateful	Stateful tool server, maintains a session
rest_bridge	Wrap an ordinary REST API as MCP tools

Deferred loading

With defer_loading = true, the server loads its tool schema only on the first tools/list or tools/call. Suitable for:

• Many tool servers where most are rarely used
• Reducing startup time

Health check

When configured, the gateway periodically probes whether the tool server is alive:

{
  "health_check": {
    "path": "/health",
    "interval_secs": 60,
    "timeout_secs": 5
  }
}

Tools of an unhealthy server are excluded from tools/list, and consecutive call failures trigger temporary circuit-breaking protection.

REST bridge

Wrap an ordinary REST API as MCP tools: connection_type = rest_bridge, provide the simplified REST spec JSON ({title, version, operations[]}) in extra_config, and the gateway auto-generates the tool definitions from the spec.

Note: the spec is a simplified operation list ({title, version, operations[]}), not the standard OpenAPI 3.x paths shape, and Swagger 2.0 is not supported.

Console → MCP Servers → New, set Connection type to REST Bridge, paste the simplified spec into the spec editor (each operation contains operation_id / description / method / path / parameters_schema), e.g.:

{
  "title": "Weather API",
  "version": "1.0.0",
  "operations": [
    {
      "operation_id": "getForecast",
      "description": "Get weather forecast",
      "method": "GET",
      "path": "/forecast",
      "parameters_schema": {
        "type": "object",
        "properties": {"city": {"type": "string"}},
        "required": ["city"]
      }
    }
  ]
}

After configuration, clients can call weather-api.getForecast via tools/call, and the gateway automatically translates the MCP call into a REST request. See MCP config for field details.

List and details

• List: shows all MCP servers, including name, transport, connection type, endpoint, enabled status, and health status
• Details: click a row to expand details and see the full configuration, health-check results, and recent call statistics

Edit and delete

• Edit: list → edit. All fields can be changed. An endpoint change takes effect on the next call.
• Delete: list → delete. Permanently removes it. If a key group's mcp_tool_acl references this server's tools, change the ACL first before deleting.

Full example: aggregate two tool servers and authorize by group

The steps below give Console API JSON payloads (for easy scripting/copying). If doing it in the console UI, the corresponding forms are: MCP Servers → New, Access Keys → Key Groups → New, Access Keys → New, with fields mapped one-to-one to the JSON (see the "Add an MCP server" field table above).

1. Add MCP servers

{
  "name": "github",
  "transport": "streamable_http",
  "endpoint": "http://github-mcp:3001",
  "tags": ["dev-tools"]
}

{
  "name": "slack",
  "transport": "streamable_http",
  "endpoint": "http://slack-mcp:3002",
  "tags": ["communication"]
}

2. Configure the key group

{
  "name": "dev-team",
  "models": ["*"],
  "mcp_tool_acl": {
    "allowed_tools": ["github.*", "slack.send-message", "slack.list-channels"],
    "denied_tools": ["slack.delete-channel", "slack.kick-user"]
  }
}

3. Configure the access key

{
  "api_key": "sk-dev-team-key",
  "name": "dev-alice",
  "group": "dev-team"
}

4. Client call

POST http://localhost:7890/mcp
Authorization: Bearer sk-dev-team-key

{"jsonrpc": "2.0", "method": "tools/call", "params": {
  "name": "github.list_repos",
  "arguments": {"owner": "octocat"}
}}

FAQ

Q: The newly added server's tools don't appear in the tool list? Check: ① whether the server is enabled; ② whether defer_loading is on (schema loads only on first call); ③ whether the key group's mcp_tool_acl filtered it out.

Q: The REST bridge reports the spec is unsupported? The spec is the simplified {title, version, operations[]} structure, not the standard OpenAPI 3.x paths shape, and Swagger 2.0 is not supported. Rewrite the spec per operations[].

Q: Tool calls frequently time out? Adjust the server's max_concurrency (concurrency cap) and rate_limit, or check the upstream tool server's own response speed. Each MCP server has independent circuit-breaking protection — consecutive failures trigger circuit-breaking and pause forwarding to that server (not "temporarily open"), and it auto-resumes after health recovers.

Q: How do I make a key group completely unable to use MCP? In the key group's MCP sub-tab, leave allowed_tools blank and allowed_tags blank, or don't check any tools.

Q: Does an MCP server outage affect other tools? No. Each server has independent connection management and circuit-breaking protection. When one server is unavailable, its tools are excluded from the list while other servers work normally.

Q: What is tools/search? A built-in meta-tool that uses BM25 keyword search across all available tools. Use it to quickly locate a target tool when there are many tools (50+).

Next: MCP gateway proxy quickstart for a quick working example; MCP config for tool ACL, context budget, and REST bridge field details; Endpoints · auth · protocol interop for the full endpoint list.