> ## Documentation Index
> Fetch the complete documentation index at: https://docs.metamcp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP 服务器

> 了解如何在 MetaMCP 中配置和管理 MCP 服务器实例

**MCP 服务器**是一个配置，告诉 MetaMCP 如何启动和管理模型上下文协议服务器。这些服务器提供工具、资源和提示，可以通过 MetaMCP 端点聚合和暴露。

## 什么是 MCP 服务器？

MCP 服务器是 MetaMCP 的构建块。每个服务器配置定义：

* **如何启动服务器**（命令、参数、环境）
* **服务器类型**（STDIO、SSE、可流式 HTTP）
* **身份验证要求**（如果有）
* **资源依赖**（Python 包、Node 模块等）

<Card title="配置示例" icon="code">
  ```json theme={null}
  {
    "name": "HackerNews",
    "type": "STDIO", 
    "command": "uvx",
    "args": ["mcp-hn"],
    "description": "访问 HackerNews 故事和评论"
  }
  ```
</Card>

## 服务器类型

MetaMCP 支持三种类型的 MCP 服务器：

<AccordionGroup>
  <Accordion icon="terminal" title="STDIO 服务器">
    **最常见类型** - 通过标准输入/输出流通信

    ```json theme={null}
    {
      "type": "STDIO",
      "command": "uvx", 
      "args": ["mcp-server-package"],
      "env": {
        "API_KEY": "your-api-key"
      }
    }
    ```

    **使用场景：**

    * 通过 `uvx` 安装的 Python 包
    * 通过 `npx` 的 Node.js 包
    * 自定义可执行脚本
  </Accordion>

  <Accordion icon="globe" title="SSE 服务器">
    **服务器发送事件** - 通过 SSE（服务器发送事件）通信

    ```json theme={null}
    {
      "type": "SSE",
      "url": "https://api.example.com/sse",
      "bearerToken": "your-bearer-token"
    }
    ```

    <Info>如果服务器使用 OAuth，您可以将 bearerToken 留空。</Info>
  </Accordion>

  <Accordion icon="globe" title="可流式 HTTP 服务器">
    **基于 HTTP 的流式传输** - 可流式 HTTP 现在是远程 MCP 的标准

    ```json theme={null}
    {
      "type": "STREAMABLE_HTTP",
      "url": "https://api.example.com/mcp",
      "bearerToken": "your-bearer-token"
    }
    ```

    <Info>如果服务器使用 OAuth，您可以将 bearerToken 留空。</Info>
  </Accordion>
</AccordionGroup>

## 配置选项

### 基本配置

<CodeGroup>
  ```json 必填字段 theme={null}
  {
    "name": "unique-server-name",
    "type": "STDIO|SSE|STREAMABLE_HTTP",
    "command": "command-to-run", // 仅 STDIO
    "args": ["arg1", "arg2"],     // 仅 STDIO
    "url": "https://...",         // 仅 SSE/STREAMABLE_HTTP
  }
  ```

  ```json 可选字段 theme={null}
  {
    "description": "人类可读的描述",
    "env": {
      "KEY": "value"
    },
    "bearerToken": "auth-token"   // 仅 SSE/STREAMABLE_HTTP
  }
  ```
</CodeGroup>

### 环境变量

向 STDIO 服务器传递环境变量：

```json theme={null}
{
  "name": "TimeServer",
  "type": "STDIO",
  "command": "uvx",
  "args": ["mcp-server-time", "--local-timezone=America/New_York"],
  "env": {
    "TZ": "America/New_York"
  }
}
```

#### 环境变量插值

使用 `${ENV_VAR}` 语法在运行时引用环境变量：

```json theme={null}
{
  "name": "ExampleServer",
  "type": "STDIO",
  "command": "uvx",
  "args": ["mcp-example"],
  "env": {
    "API_KEY": "${API_KEY}",
    "DEBUG": "true"
  }
}
```

**优势：**

* **安全**：API 密钥和密钥不会硬编码在配置中
* **灵活**：值从容器环境中解析
* **向后兼容**：原始值仍然像以前一样工作

**工作原理：**

* `${VAR_NAME}` 在运行时被 `process.env.VAR_NAME` 替换
* 缺失的变量会记录警告但不会使服务器崩溃
* 密钥在日志中自动被隐藏

### 身份验证

对于需要身份验证的服务器：

<CodeGroup>
  ```json 带有 API 密钥的 STDIO theme={null}
  {
    "env": {
      "API_KEY": "your-secret-key"
    }
  }
  ```

  ```json 带有 Bearer Token 的远程服务器 theme={null}
  {
    "bearerToken": "your-bearer-token"
  }
  ```
</CodeGroup>

## 管理 MCP 服务器

### 添加服务器

1. **导航**到 MetaMCP 仪表板中的 MCP 服务器
2. **点击**"添加服务器"
3. **配置**服务器详细信息
4. **测试**配置
5. **保存**使其可用于命名空间

### 批量导入/导出

MetaMCP 支持批量导入和导出 MCP 服务器配置，便于迁移和备份。

#### 导出服务器

将所有配置的 MCP 服务器导出到 JSON 文件：

1. **导航**到仪表板中的 MCP 服务器
2. **点击**"导出 JSON"按钮
3. **选择**下载文件或复制到剪贴板

<Card title="导出格式" icon="code">
  ```json theme={null}
  {
    "mcpServers": {
      "HackerNews": {
        "type": "stdio",
        "command": "uvx",
        "args": ["mcp-hn"],
        "description": "访问 HackerNews 故事和评论"
      },
      "TimeServer": {
        "type": "stdio", 
        "command": "uvx",
        "args": ["mcp-server-time"],
        "env": {
          "TZ": "America/New_York"
        },
        "description": "时间和时区实用工具"
      },
      "RemoteAPI": {
        "type": "streamable_http",
        "url": "https://api.example.com/mcp",
        "bearerToken": "your-bearer-token",
        "description": "通过 HTTP 的远程 MCP 服务器"
      }
    }
  }
  ```
</Card>

#### 导入服务器

从 JSON 配置导入多个 MCP 服务器：

1. **导航**到仪表板中的 MCP 服务器
2. **点击**"导入 JSON"按钮
3. **粘贴**或输入您的 JSON 配置
4. **点击**"导入"添加服务器

<CodeGroup>
  ```json STDIO 服务器格式 theme={null}
  {
    "mcpServers": {
      "ServerName": {
        "type": "stdio",
        "command": "uvx",
        "args": ["package-name"],
        "env": {
          "API_KEY": "your-key"
        },
        "description": "可选描述"
      }
    }
  }
  ```

  ```json SSE 服务器格式 theme={null}
  {
    "mcpServers": {
      "ServerName": {
        "type": "sse",
        "url": "https://api.example.com/sse",
        "bearerToken": "your-token",
        "description": "可选描述"
      }
    }
  }
  ```

  ```json 可流式 HTTP 格式 theme={null}
  {
    "mcpServers": {
      "ServerName": {
        "type": "streamable_http", 
        "url": "https://api.example.com/mcp",
        "bearerToken": "your-token",
        "description": "可选描述"
      }
    }
  }
  ```
</CodeGroup>

<Note>
  **类型值（不区分大小写）：**

  * `"stdio"`, `"STDIO"`, `"std"` → STDIO
  * `"sse"`, `"SSE"` → SSE
  * `"streamable_http"`, `"STREAMABLE_HTTP"`, `"streamablehttp"`, `"http"` → STREAMABLE\_HTTP
</Note>

<Note>
  **导入行为：**

  * 具有现有名称的服务器将使用新配置**更新**
  * 新服务器将被**创建**
  * 无效配置将被**跳过**并显示错误消息
  * 导入过程显示成功/失败计数
</Note>

<Tip>
  使用批量导入/导出用于：

  * **环境迁移**（开发 → 测试 → 生产）
  * **团队协作**（共享服务器配置）
  * **备份和恢复**（配置备份）
  * **快速设置**（一次部署多个服务器）
</Tip>

### 空闲会话管理

MetaMCP 预分配空闲会话以获得更好的性能：

<Card title="冷启动优化" icon="zap">
  * **默认**：每个服务器 1 个空闲会话
  * **可配置**：根据使用模式调整
  * **自动扩展**：按需创建会话
  * **清理**：超时后回收空闲会话
</Card>

## 依赖项的自定义 Dockerfile

如果您的 MCP 服务器需要 `uvx` 或 `npx` 之外的额外依赖项，您可以自定义 MetaMCP Dockerfile：

```dockerfile theme={null}
FROM metamcp:latest

# 安装 Python 依赖项
RUN pip install requests beautifulsoup4

# 安装系统包
RUN apt-get update && apt-get install -y \
    curl \
    git \
    && rm -rf /var/lib/apt/lists/*

# 全局安装 Node.js 包
RUN npm install -g some-mcp-package
```

<Warning>
  自定义依赖项会增加 Docker 镜像大小和启动时间。尽可能考虑使用轻量级替代方案。
</Warning>

## 故障排除

<AccordionGroup>
  <Accordion icon="triangle-alert" title="服务器无法启动">
    **常见原因：**

    * 缺少依赖项（通过自定义 Dockerfile 安装）
    * 命令或参数不正确
    * 环境变量未设置
    * 网络连接问题（对于 SSE/可流式 HTTP）

    **调试步骤：**

    1. 在 MetaMCP 仪表板中检查服务器日志
    2. 在终端中手动测试命令
    3. 验证环境变量
    4. 检查网络连接
  </Accordion>

  <Accordion icon="clock" title="性能缓慢">
    **优化策略：**

    * 为频繁使用的服务器增加空闲会话计数
    * 尽可能使用本地服务器而不是远程服务器
    * 在自定义 Docker 镜像中预安装依赖项
    * 配置适当的超时值
  </Accordion>

  <Accordion icon="shield" title="身份验证问题">
    **常见问题：**

    * API 密钥或 bearer token 过期
    * 环境变量名称不正确
    * 缺少必需的标头
    * 外部 API 的速率限制

    **解决方案：**

    1. 刷新 API 密钥/token
    2. 检查服务器文档了解必需的身份验证
    3. 实现适当的错误处理
    4. 添加带有退避的重试逻辑
  </Accordion>
</AccordionGroup>

## 下一步

<CardGroup cols={2}>
  <Card title="创建命名空间" icon="package" href="/cn/concepts/namespaces">
    将您的 MCP 服务器分组到有组织的命名空间中
  </Card>

  <Card title="设置端点" icon="link" href="/cn/concepts/endpoints">
    创建公共端点以访问您的服务器
  </Card>

  <Card title="添加中间件" icon="filter" href="/cn/concepts/middleware">
    转换和过滤 MCP 请求和响应
  </Card>

  <Card title="集成指南" icon="plug" href="/cn/integrations/cursor">
    将您配置的服务器连接到 MCP 客户端
  </Card>
</CardGroup>