> Raw Markdown twin (generated at build time from the source Markdown). Rendered page: https://docs.gatellm.io/en/howto/onboard-external-mcp · Doc index: https://docs.gatellm.io/en/llms.txt


# 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](/en/quickstart/mcp-proxy.md) for a quick start that runs a working example, and [MCP config](/en/reference/mcp-config.md) 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:

```json
{
  "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.:

```json
{
  "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](/en/reference/mcp-config.md) 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

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

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

### 2. Configure the key group

```json
{
  "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

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

### 4. Client call

```json
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](/en/quickstart/mcp-proxy.md) for a quick working example; [MCP config](/en/reference/mcp-config.md) for tool ACL, context budget, and REST bridge field details; [Endpoints · auth · protocol interop](/en/reference/endpoints.md) for the full endpoint list.