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

# SEP-414：记录 OpenTelemetry 跟踪上下文传播约定

* **状态（Status）**: Final
* **类型（Type）**: Standards Track
* **创建（Created）**: 2025-04-25
* **作者（Author(s)）**: Adrian Cole (@codefromthecrypt)
* **担保人（Sponsor）**: Marcelo Trylesinski (@Kludex)
* **PR**: [https://github.com/modelcontextprotocol/modelcontextprotocol/pull/414](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/414)

## 摘要

本 SEP 记录了 MCP 中 OpenTelemetry（OTel）跟踪上下文传播的约定。

[面向 MCP 的 OTel 语义约定](https://github.com/open-telemetry/semantic-conventions/blob/e126ea9105b15912ccd80deab98929025189b696/docs/gen-ai/mcp.md#context-propagation)规定使用 `_meta` 作为 W3C Trace Context 键的载体。这在 C# SDK 和其他实现中已经付诸实践。

本规范记录了对 `_meta` 中键的 DNS 前缀约定的一个例外。这使得既有和新的实现之间能够互操作，并为相关 SEP（如 [SEP-2028](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2028)）奠定基础。

## 规范

本 SEP 向 MCP 规范添加文档，指出：

1. 当 OTel 跟踪上下文通过 `_meta` 传播时，键 `traceparent`、`tracestate` 和 `baggage` 遵循 [W3C Trace Context](https://www.w3.org/TR/trace-context/) 和 [W3C Baggage](https://www.w3.org/TR/baggage/) 的值格式。

2. 一个展示 `_meta` 中跟踪上下文的非规范性示例。

3. 一条说明，澄清为何这是 `_meta` 中键 DNS 前缀的一个例外：为了与既有实现以及 OpenTelemetry 语义约定保持兼容。

关于 ACP 中等价的文档变更，参见 [agentclientprotocol/agent-client-protocol#297](https://github.com/agentclientprotocol/agent-client-protocol/pull/297)。

### 非规范性示例

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "get_weather",
    "arguments": {
      "location": "New York"
    },
    "_meta": {
      "traceparent": "00-0af7651916cd43dd8448eb211c80319c-00f067aa0ba902b7-01"
    }
  }
}
```

## 理由

### 为何记录这一点？

这目前记录在别处，但并未作为 MCP 规范。将其纳入规范可确保依赖此模式的 SEP 能够完成，同时也让 MCP 组织内外的其他 SDK 得以完成，例如 [Logfire](https://github.com/pydantic/logfire/blob/09232402fd7e268c667db59d1e9f890ed30f7850/logfire/_internal/integrations/mcp.py#L149-L162) 和 [ToolHive](https://github.com/stacklok/toolhive/issues/3399)。

如果我们不记录这一共同关切，可能会出现不同的解释，例如将 traceparent 命名空间化为 `io.modelcontextprotocol.traceparent`，这会破坏跟踪（trace）和日志关联。

### 相关 SEP

* [SEP-1788](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/1788) —— `_meta` 中的保留键；本 SEP 实现时应更新，加入 `traceparent`、`tracestate` 和 `baggage`
* [SEP-2028](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2028) —— 在本 SEP 基础上，将 `_meta` 值转发到 HTTP 头部

## 向后兼容性

本 SEP 记录既有约定，向后兼容。

## 安全影响

`_meta` 中的跟踪上下文可能包含关联 ID（correlation ID）。实现应遵循适合其环境的既有数据处理指南。

## 参考实现

使用此模式的既有实现：

* [C# SDK instrumentation](https://github.com/modelcontextprotocol/csharp-sdk/blob/main/src/ModelContextProtocol.Core/Diagnostics.cs)
* [Python SDK instrumentation](https://github.com/modelcontextprotocol/python-sdk/pull/1693)
* [OpenInference MCP instrumentation (Python)](https://github.com/Arize-ai/openinference/tree/main/python/instrumentation/openinference-instrumentation-mcp)
* [OpenInference MCP instrumentation (TypeScript)](https://github.com/Arize-ai/openinference/tree/main/js/packages/openinference-instrumentation-mcp)
* [Envoy AI Gateway](https://github.com/envoyproxy/ai-gateway/blob/6331b54aef81dd6c8d3d184acc4e2cb8167cea2a/internal/tracing/tracingapi/mcp.go)
* [Logfire](https://github.com/pydantic/logfire/blob/09232402fd7e268c667db59d1e9f890ed30f7850/logfire/_internal/integrations/mcp.py#L149-L162)
* [ToolHive](https://github.com/stacklok/toolhive/issues/3399)