LiteLLM Terraform Provider 中 litellm_mcp_server 数据源解析：安全地以 IaC 方式读取 MCP 服务器配置

本文围绕 LiteLLM Terraform Provider（terraform/provider/）中的 litellm_mcp_server 数据源展开：它通过 GET /v1/mcp/server/{server_id} 只读拉取一个已存在的 MCP（Model Context Protocol）服务器的完整元数据，同时刻意屏蔽 env、credentials、static_headers 等可能包含密钥的字段。读完本文，你将掌握该数据源的参数与全部导出属性、配套的 litellm_mcp_servers 列表数据源，并能结合 Go 源码理解其请求构造、错误处理以及"密钥永不出现在 Terraform state 中"的实现机制。

一、litellm_mcp_server 数据源是什么

在 mcp_server.md 的官方说明中，该数据源的职责被概括为一句话：Retrieves information about an existing MCP server via /v1/mcp/server/{server_id}. Secret material (environment variables, credentials, and static header values) is never exposed.（通过 /v1/mcp/server/{server_id} 获取已存在 MCP 服务器的信息；密钥材料——环境变量、凭据、静态请求头的值——永远不会被暴露。）

它的典型使用场景是：MCP 服务器已经通过 litellm_mcp_server 资源、管理后台或其他方式创建，你希望在 Terraform 配置中读取它的属性（如服务 URL、传输协议、健康状态），用于输出、构建依赖或拼装其他配置——例如把 url 导出给 CI 流水线，让 Claude Code 之类的客户端直接指向代理暴露的 MCP 端点。

数据源在 Provider 中注册于 provider.go 的 DataSourcesMap（"litellm_mcp_server": dataSourceLiteLLMMCPServer()），与同文件中可写资源 litellm_mcp_server 形成"读/写分离"：资源负责 CRUD，数据源只负责只读查询。

使用示例

官方文档给出的最小可用示例如下：

data "litellm_mcp_server" "github" {
  server_id = "srv-1234"
}

output "github_mcp_url" {
  value = data.litellm_mcp_server.github.url
}

使用前提是先声明并配置好 Provider（参考 Provider 文档）：

terraform {
  required_providers {
    litellm = {
      source = "BerriAI/litellm"
    }
  }
}

provider "litellm" {
  api_base = var.litellm_api_base
  api_key  = var.litellm_api_key
}

根据 provider.go 的 Provider 级 Schema，api_base 与 api_key 也支持从环境变量 LITELLM_API_BASE、LITELLM_API_KEY 读取；另有可选的 insecure_skip_verify（默认 false）用于自签名证书的开发环境。

二、Argument Reference：输入参数

该数据源只有一个必填参数：

参数	必填	说明
server_id	是	要查询的 MCP 服务器的唯一标识

从源码 data_source_mcp_server.go 可以确认，server_id 的 Schema 定义为 Type: schema.TypeString, Required: true；其余所有字段均声明为 Computed: true，即纯输出、不接受用户赋值。这也符合 Terraform 数据源的语义：你只提供定位凭据，属性由远端 API 回填。

三、Attributes Reference：全部导出属性

文档声明该数据源导出以下 19 个属性（与 mcp_server.md 的 Attributes Reference 一一对应，并与 Go 结构体 mcpServerDetail 的 JSON tag 完全一致）：

属性	类型	含义
server_name	string	服务器名称
alias	string	服务器别名
description	string	描述信息
url	string	该 MCP 服务器的 URL
transport	string	传输类型：http、sse、stdio
spec_version	string	MCP 规范版本（测试样例为 2024-11-05）
auth_type	string	认证类型：none、bearer、basic 等
mcp_access_groups	list(string)	该服务器的访问组
allowed_tools	list(string)	在此服务器上允许使用的工具
extra_headers	list(string)	转发到 MCP 服务器的请求头名称（注意只是名称，不含值）
command	string	stdio 传输对应的启动命令
args	list(string)	stdio 命令参数
allow_all_keys	bool	是否允许所有密钥访问
status	string	健康状态：healthy、unhealthy、unknown
last_health_check	string	最近一次健康检查时间戳
health_check_error	string	最近一次健康检查的错误信息（如有）
created_at / created_by	string	创建时间 / 创建者
updated_at / updated_by	string	最后更新时间 / 更新者

值得留意的是 extra_headers 的 Schema 描述（data_source_mcp_server.go）："Names of request headers forwarded to the MCP server"——只导出头名而非头的值，这与"密钥材料不外泄"的安全设计一脉相承。

四、源码级原理：请求、解码与属性回填

4.1 请求构造

读取逻辑全部位于 dataSourceLiteLLMMCPServerRead（data_source_mcp_server.go）：

endpoint := fmt.Sprintf("%s/%s", endpointMCPServerRead, serverID)
resp, err := MakeRequest(client, "GET", endpoint, nil)

其中 endpointMCPServerRead 常量定义为 "/v1/mcp/server"（resource_mcp_server_crud.go，Create/Update/Read/Delete 四个操作共用同一前缀，读写差异体现在是否拼接 /{server_id}）。因此本数据源实际发出的请求就是 GET /v1/mcp/server/{server_id}，与文档描述完全吻合。

在代理服务端，这条路由由 MCP 管理 REST 端点实现，代码位于 rest_endpoints.py；当 server_id 不存在时返回 404，例如 db.py 中会抛出 MCP server not found, passed server_id=...。

4.2 结构化解码：密钥字段在结构体层面被"删除"

解码使用的结构体是安全设计的核心（data_source_mcp_server.go）：

// mcpServerDetail intentionally omits env, credentials, and static_headers:
// those may hold secrets and must never reach data source state.
type mcpServerDetail struct {
    ServerID         string   `json:"server_id"`
    ...
    ExtraHeaders     []string `json:"extra_headers"`
    ...
}

源码注释直白地说明了意图：故意省略 env、credentials、static_headers 三个字段，因为它们可能承载密钥，绝不应进入数据源 state。由于 Go 的 json.Unmarshal 对结构体中不存在的 JSON 字段是"静默丢弃"，即便代理端返回了这些字段，它们也止步于解码过程，永远不会被 d.Set(...) 写入 Terraform state。

这个行为有专门的测试佐证。data_source_mcp_server_test.go 中的 mock 服务器刻意在响应里放入了机密值：

"env": {"SECRET_TOKEN": "should-never-surface"},
"static_headers": {"Authorization": "Bearer should-never-surface"}

测试随后断言 ID 与各非密属性（server_name、transport、status、mcp_access_groups、allowed_tools、extra_headers 等）全部正确回填——而任何 secret 值都没有出现在可读取的 state 属性中。换言之，"Security Note"（env、credentials、static_headers 不通过该数据源暴露）不是文档口号，而是有结构体裁剪 + 单元测试双重保障的硬约束。

4.3 错误处理与 404 映射

解码与错误处理通过 handleMCPAPIResponse（utils.go）完成。读取逻辑对 404 做了显式分支（data_source_mcp_server.go）：

if err := handleMCPAPIResponse(resp, &server, client); err != nil {
    if err.Error() == "mcp_server_not_found" {
        return fmt.Errorf("MCP server %q not found", serverID)
    }
    return fmt.Errorf("failed to read MCP server: %w", err)
}

对应测试 TestDataSourceMCPServerReadNotFound（data_source_mcp_server_test.go）验证了：mock 端点返回 404 时，terraform plan/apply 会收到明确错误而非空对象。实操提示：在 Terraform 中引用不存在的 server_id 会导致 plan 阶段直接失败，这既是"快速失败"的好处，也意味着引用远端对象的 ID 时要确保其已就绪（可用 depends_on 等待对应资源创建完成）。

4.4 ID 赋值与日志

读取成功后，资源 ID 通过 d.SetId(GetStringValue(server.ServerID, serverID)) 设置为 API 返回的 server_id（缺失时回退到请求参数），并在 data_source_mcp_server.go 打出 [INFO] Successfully read MCP server with ID: ... 日志，便于在 debug 模式下（TF_LOG=DEBUG）确认数据源确实发起了请求。

五、姊妹篇：litellm_mcp_servers 列表数据源

同一文件中还实现了列表型数据源 litellm_mcp_servers（data_source_mcp_server.go），文档见 mcp_servers.md。两者的关系与差异如下：

维度	litellm_mcp_server	litellm_mcp_servers
请求	GET /v1/mcp/server/{server_id}	GET /v1/mcp/server（可选 ?team_id=...）
输入	server_id（Required）	team_id（Optional，过滤该团队可访问的服务器 + allow_all_keys 的全局服务器）
输出	单个服务器的 19 个完整属性	ids + mcp_servers 列表（每条目仅 11 个摘要字段）
典型用途	精确定位单台服务器	批量盘点 / 生成依赖清单

源码中的列表读取逻辑值得注意两点：其一，team_id 会经 url.QueryEscape 后拼为查询参数（data_source_mcp_server.go），测试 TestDataSourceMCPServersRead 明确断言了 team_id=team-1 出现在请求 query 中；其二，列表条目只导出摘要字段（server_id、server_name、alias、description、url、transport、spec_version、auth_type、allow_all_keys、status、created_at、updated_at），同样复用了剔除密钥的 mcpServerDetail 结构体解码，因此"Secret material is never exposed"对列表场景同样成立。列表数据源的典型用法（引自 mcp_servers.md）：

data "litellm_mcp_servers" "all" {}

data "litellm_mcp_servers" "team_scoped" {
  team_id = litellm_team.ml.id
}

output "mcp_server_urls" {
  value = [for s in data.litellm_mcp_servers.all.mcp_servers : s.url]
}

两者可以组合使用：先用列表数据源拿到 ids，再对其中某个 ID 发起单台查询拿全量属性。

六、安全设计小结与实操建议

1. state 文件安全：Terraform state 常落在共享的远端 backend 上。本数据源从结构体层面（mcpServerDetail 不含 env/credentials/static_headers）保证密钥不会随 state 落盘或进入 plan 输出，这是把它用于 IaC 读取而非直接 curl API 的主要安全理由。
2. extra_headers 只给名字：若需要知道某请求头的取值，应回到管理端查看，而不是期望 Terraform 导出。
3. 版本对齐：按 provider README 的版本策略，Provider 版本与 LiteLLM 代理版本同步发布，建议按代理实际运行的版本约束 Provider（如 version = "~> 1.99.0"），保证数据源调用的 /v1/mcp/server/{server_id} 契约与代理端一致。Provider 的 CI 还会通过 tools/endpointaudit/ 将每个端点与代理生成的 OpenAPI schema 做静态审计（见 endpointaudit 测试 中对 GET /v1/mcp/server/{param} 的审计），防止 provider 与 API 静默漂移。
4. 404 快速失败：server_id 写错或资源尚未创建时，plan 阶段即报错 MCP server "..." not found，应核对 ID 或用 depends_on 建立创建顺序。

延伸阅读

• 数据源文档：litellm_mcp_server Data Source、litellm_mcp_servers Data Source
• 实现源码：data_source_mcp_server.go、单元测试、响应处理工具
• 可写资源端点常量：resource_mcp_server_crud.go
• Provider 总览与认证配置：Provider 文档、terraform/provider/README.md
• 代理端 MCP 管理端点：litellm/proxy/_experimental/mcp_server/rest_endpoints.py

适用前提：本文基于当前仓库中 terraform/provider/ 的源码与文档；数据源行为要求 LiteLLM 代理已启用 MCP 管理功能并开放 /v1/mcp/server 管理端点，且调用方 API key 具有相应读取权限（团队作用域行为与代理端访问控制策略一致）。