MCP semantic conventions #2083

lmolkova · 2025-04-10T05:15:27Z

Fixes #2043

Adds the first version of MCP conventions including spans and basic metrics.

Implementations/prototypes:

docs/attributes-registry/mcp.md

docs/gen-ai/mcp.md

docs/attributes-registry/mcp.md

docs/gen-ai/mcp.md

model/mcp/common.yaml

model/mcp/registry.yaml

…nt from metrics

dcramer · 2025-06-22T05:23:07Z

I realize this is dangling, but one thing I wanted to mention here: you should keep mcp.transport. Abstracting this purely to the network transport removes the value conventions add. For example, how would I identify the difference between http streaming and sse?

We (Sentry) are already implemented a variation of this spec, so I'm going to suggest to the team to capture that too. We'll probably just do "http" and "sse" and stick w/ the conventions used in the SDKs.

Copilot

Pull Request Overview

Adds the first version of Model Context Protocol (MCP) semantic conventions, including span definitions, attribute and metric schemas, documentation, and repository configuration.

Introduce model/mcp/ with common attributes, spans, and metrics YAML definitions
Generate and link corresponding documentation under docs/registry/attributes/mcp.md and docs/gen-ai/mcp.md
Update templates, issue forms, and CODEOWNERS to include MCP

Reviewed Changes

Copilot reviewed 13 out of 13 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
templates/registry/markdown/weaver.yaml	Added `MCP` to known acronyms
model/mcp/common.yaml	Defined common MCP attributes
model/mcp/spans.yaml	Added client/server span definitions
model/mcp/registry.yaml	Registered MCP attributes and method enums
model/mcp/metrics.yaml	Defined MCP operation and session metrics
docs/registry/attributes/mcp.md	Auto-generated attribute reference page
docs/registry/attributes/README.md	Added MCP to attribute namespace listing
docs/gen-ai/mcp.md	New semantic conventions guide for MCP
docs/gen-ai/README.md	Linked MCP guide in Gen-AI overview
.github/ISSUE_TEMPLATE/{change_proposal,bug_report}.yaml	Added `area: mcp` in issue templates
.github/CODEOWNERS	Assigned owners for `model/mcp/`
.chloggen/2083.yaml	Added changelog entry for MCP enhancement

Comments suppressed due to low confidence (2)

model/mcp/registry.yaml:139

This inline comment reflects internal uncertainty. Consider moving it into a formal note field or resolving the overlap between mcp.tool.name and gen_ai.tool.name instead of leaving it as a code comment.

        # This is effectively the same as `gen_ai.tool.name`, but it's not clear

docs/gen-ai/mcp.md:223

This manual duplication of the server span note diverges from the autogenerated snippet and is outdated. Remove the redundant block and rely on the generated content to keep docs in sync.

<!-- This is a dup of yaml note and should no longer be necessary after https://github.com/open-telemetry/semantic-conventions/pull/1505 -->

docs/registry/attributes/mcp.md

austinborn

Amazing work on this! Excited to clean up a few small areas and get it merged in.

docs/gen-ai/mcp.md

model/mcp/registry.yaml

model/mcp/common.yaml

model/mcp/metrics.yaml

austinborn · 2025-07-12T18:03:39Z

model/mcp/registry.yaml

+              stability: development
+            - id: ping
+              value: ping
+              brief: >


Would you mind also updating the brief for ping? It doesn't provide any progress updates, it just expects an empty payload in response.

thompson-tomo · 2025-07-13T13:44:24Z

model/mcp/registry.yaml

+      - id: mcp.session.id
+        type: string
+        brief: Identifies MCP session.
+        stability: development
+        examples: ["191c4850af6c49e08843a3f6c80e5046"]


Could we use the existing session.id attribute?

I can see this going either way, but it's worth noting that the definition of MCP's session is somewhat distinct from OTel's:

MCP:

An MCP “session” consists of logically related interactions between a client and a server, beginning with the initialization phase. To support servers which want to establish stateful sessions: ...

OTel

Session is defined as the period of time encompassing all activities performed by the application and the actions executed by the end user. ... When a session reaches end of life, typically due to user inactivity or session timeout, a new session identifier will be assigned. ...

session for MCP seems more closely aligned with gen_ai.conversation.id, which is its own attribute in the gen_ai group.

thompson-tomo · 2025-07-13T13:59:06Z

model/mcp/registry.yaml

+      - id: mcp.request.id
+        type: string
+        brief: >
+          This is a unique identifier for the request.
+        stability: development
+        examples: ["42"]


Thoughts on using an attribute like peer.request.id when describing it from the client?

From what I see in the context of OTel peer means a separate process, usually over the network. Since MCP client-server relationships have the option to run on stdio, IMO it doesn't always meet the definition of a peer. Happy to get a second opinion though.

For me a peer is any service that you are interacting with hence it is important to note peer doesn't define any addressing attributes this is left to namespaces such as destination & server.

Understood, that makes sense. To be clear, you would completely replace mcp.request.id with peer.request.id? What about the mcp.request.argument.<key> attribute?

I would leave it as I see them as comparable to http arguments etc.

thompson-tomo · 2025-07-13T14:03:52Z

model/mcp/metrics.yaml

+  - id: metric.mcp.client.session.duration
+    type: metric
+    metric_name: mcp.client.session.duration
+    brief: The duration of the MCP session as observed on the MCP client.
+    unit: s
+    instrument: histogram
+    stability: development
+    extends: mcp.session.metrics.attributes
+    attributes:
+      - ref: server.address
+      - ref: server.port
+        requirement_level:
+          recommended: When `server.address` is set
+
+  - id: metric.mcp.server.session.duration
+    type: metric
+    metric_name: mcp.server.session.duration
+    brief: The duration of the MCP session as observed on the MCP server.
+    unit: s
+    instrument: histogram
+    stability: development
+    extends: mcp.session.metrics.attributes


Would these fit in the session namespace with perhaps a session type attribute?

Cirilla-zmh

Thank you for this PR!

Cirilla-zmh · 2025-08-11T12:52:12Z

docs/gen-ai/mcp.md

+| `quic` | QUIC | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
+| `tcp` | TCP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
+| `udp` | UDP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
+| `unix` | Unix domain socket | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |


Why not go with 'uds'?

Cirilla-zmh · 2025-08-11T13:46:38Z

docs/gen-ai/mcp.md

+| [`network.transport`](/docs/registry/attributes/network.md) | string | The transport protocol used for the MCP session. [4] | `tcp`; `udp` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
+| [`server.address`](/docs/registry/attributes/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [5] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
+| [`server.port`](/docs/registry/attributes/server.md) | int | Server port number. [6] | `80`; `8080`; `443` | `Recommended` When `server.address` is set | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
+| [`mcp.request.argument.<key>`](/docs/registry/attributes/mcp.md) | string | Additional arguments passed to the request within `params` object. `<key>` being the normalized argument name (lowercase), the value being the argument value. [7] | `mcp.request.argument.location="Seattle, WA"`; `mcp.request.argument.a="42"` | `Opt-In` | ![Development](https://img.shields.io/badge/-development-blue) |


Why is the '' needed here? I don't see a specific reason to parse the first layer of arguments, especially since the input could be a nested JSON object.
See https://github.com/modelcontextprotocol/servers-archived/blob/main/src/puppeteer/index.ts

Cirilla-zmh · 2025-08-11T13:49:49Z

docs/gen-ai/mcp.md

+| [`server.address`](/docs/registry/attributes/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [5] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
+| [`server.port`](/docs/registry/attributes/server.md) | int | Server port number. [6] | `80`; `8080`; `443` | `Recommended` When `server.address` is set | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
+| [`mcp.request.argument.<key>`](/docs/registry/attributes/mcp.md) | string | Additional arguments passed to the request within `params` object. `<key>` being the normalized argument name (lowercase), the value being the argument value. [7] | `mcp.request.argument.location="Seattle, WA"`; `mcp.request.argument.a="42"` | `Opt-In` | ![Development](https://img.shields.io/badge/-development-blue) |
+


Maybe we need 'mcp.response.output' here with opt-in level, which is the same as chat history.

This is based on the work in open-telemetry/semantic-conventions#2083 with the goal to be standardised monitoring of this MCP server.

Add automatic OpenTelemetry instrumentation for the Model Context Protocol (MCP) SDK to enable distributed tracing across MCP client–server boundaries. Features 1. Automatic span creation for client requests and server handlers. 2. OpenTelemetry context propagation via request metadata. 3. Support for MCP semantic conventions. Reference: MCP semantic conventions open-telemetry/semantic-conventions#2083 Tests 1. End-to-end test with HTTP-based MCP client and server 2. End-to-end test with stdio-based MCP client and server 3. All unit tests pass Implementation Notes According to the MCP SDK documentation https://github.com/modelcontextprotocol/typescript-sdk/blob/main/README.md, the following modules are used to create the MCP client and server: Client Module name: '@modelcontextprotocol/sdk/client/index.js' basedir: '/Users/someone/http-client-server/client/node_modules/@modelcontextprotocol/sdk' Server Module name: '@modelcontextprotocol/sdk/server/mcp.js' basedir: '/Users/someone/http-client-server/server/node_modules/@modelcontextprotocol/sdk' The existing InstrumentationBase could not wrap both modules from the @modelcontextprotocol/sdk package. This PR introduces a custom hook within the MCP instrumentation library to support both.

github-project-automation bot added this to Semantic Conventions Triage Apr 10, 2025

github-project-automation bot moved this to Untriaged in Semantic Conventions Triage Apr 10, 2025

lmolkova mentioned this pull request Apr 10, 2025

OpenTelemetry: context propagation and semconv update modelcontextprotocol/csharp-sdk#262

Merged

3 tasks

lmolkova force-pushed the mcp branch from 7c6c3c0 to b51d631 Compare April 11, 2025 21:43

AbhiPrasad mentioned this pull request Apr 14, 2025

MCP Server auto instrumentation getsentry/sentry-javascript#16052

Open

samsp-msft reviewed Apr 14, 2025

View reviewed changes

docs/attributes-registry/mcp.md Outdated Show resolved Hide resolved

samsp-msft reviewed Apr 14, 2025

View reviewed changes

docs/gen-ai/mcp.md Outdated Show resolved Hide resolved

docs/gen-ai/mcp.md Outdated Show resolved Hide resolved

docs/gen-ai/mcp.md Show resolved Hide resolved

docs/gen-ai/mcp.md Outdated Show resolved Hide resolved

docs/gen-ai/mcp.md Show resolved Hide resolved

Cirilla-zmh reviewed Apr 16, 2025

View reviewed changes

docs/gen-ai/mcp.md Outdated Show resolved Hide resolved

docs/attributes-registry/mcp.md Outdated Show resolved Hide resolved

lmolkova force-pushed the mcp branch from 7fc49b1 to 4f9670c Compare April 17, 2025 05:06

github-actions bot added the enhancement New feature or request label Apr 17, 2025

lmolkova changed the title ~~[WIP] MCP semantic conventions~~ MCP semantic conventions Apr 17, 2025

lmolkova moved this from Untriaged to Awaiting SIG approval in Semantic Conventions Triage Apr 17, 2025

lmolkova marked this pull request as ready for review April 17, 2025 05:19

lmolkova requested review from a team as code owners April 17, 2025 05:19

lmolkova commented Apr 17, 2025

View reviewed changes

docs/gen-ai/mcp.md Show resolved Hide resolved

samsp-msft mentioned this pull request Apr 21, 2025

Initial proposal for MCP semantic conventions #2045

Closed

3 tasks

gyliu513 reviewed Apr 21, 2025

View reviewed changes

model/mcp/common.yaml Outdated Show resolved Hide resolved

model/mcp/registry.yaml Outdated Show resolved Hide resolved

model/mcp/registry.yaml Show resolved Hide resolved

Liudmila Molkova added 10 commits April 23, 2025 17:34

MCP first stab

117cf6c

try tool and prompt name, add args

8c29e3a

clean up session metrics

a3d5a6d

simplify

a70852f

rename metrics

a04c19a

clean up

fc518ee

feedback

6295a1e

clean up

6048ce5

remove server.address|port from server metrics and spans, remove clie…

1ace1a5

…nt from metrics

feedback and clean up

8e6b9cb

github-actions bot closed this Jun 21, 2025

lmolkova reopened this Jun 21, 2025

github-actions bot removed the Stale label Jun 22, 2025

betegon mentioned this pull request Jun 23, 2025

MCP Server - instrumentation spec document getsentry/sentry-docs#14106

Closed

anuraaga mentioned this pull request Jun 27, 2025

OpenTelemetry support modelcontextprotocol/go-sdk#59

Closed

lmolkova requested a review from Copilot July 1, 2025 05:37

Copilot AI reviewed Jul 1, 2025

View reviewed changes

docs/registry/attributes/mcp.md Outdated Show resolved Hide resolved

austinborn mentioned this pull request Jul 6, 2025

Data Model with Agent-Focused Semantic Conventions shinzo-labs/shinzo-ts#6

Closed

2 tasks

austinborn suggested changes Jul 11, 2025

View reviewed changes

github-project-automation bot moved this from Awaiting SIG approval to Blocked in Semantic Conventions Triage Jul 11, 2025

Liudmila Molkova added 2 commits July 12, 2025 09:42

update methods and other review comments

1e22aac

Merge branch 'main' into mcp

d4289d2

lmolkova force-pushed the mcp branch from 3097fb0 to d4289d2 Compare July 12, 2025 16:45

Liudmila Molkova added 2 commits July 12, 2025 09:59

more feedback

8d275a5

lint

ae2decf

lmolkova mentioned this pull request Jul 12, 2025

Capturing RPC transport type #2512

Open

lmolkova moved this from Blocked to Awaiting SIG approval in Semantic Conventions Triage Jul 12, 2025

austinborn reviewed Jul 12, 2025

View reviewed changes

thompson-tomo reviewed Jul 13, 2025

View reviewed changes

austinborn mentioned this pull request Jul 18, 2025

Include OpenTelemetry Trace identifiers as part of the MCP client -> server protocol modelcontextprotocol/modelcontextprotocol#246

Open

florianl mentioned this pull request Jul 24, 2025

Proposal: Support for OTel Implementation in go-mcp open-telemetry/opentelemetry-go-contrib#7616

Open

Cirilla-zmh reviewed Aug 11, 2025

View reviewed changes

wolfeidau mentioned this pull request Sep 14, 2025

feat: adding handler middleware to ensure otel attributes are set buildkite/buildkite-mcp-server#150

Merged

This was referenced Oct 15, 2025

feat(instrumentation-mcp): add OpenTelemetry instrumentation for MCP SDK open-telemetry/opentelemetry-js-contrib#3175

Draft

Add OpenTelemetry instrumentation for Model Context Protocol (MCP) open-telemetry/opentelemetry-python-contrib#3822

Open

lukeina2z mentioned this pull request Oct 21, 2025

feat(instrumentation-mcp): add OpenTelemetry instrumentation for MCP SDK open-telemetry/opentelemetry-js-contrib#3186

Open

MCP semantic conventions #2083

Are you sure you want to change the base?

MCP semantic conventions #2083

Conversation

lmolkova commented Apr 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

dcramer commented Jun 22, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

austinborn left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

austinborn Jul 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

austinborn Jul 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Cirilla-zmh left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

12 participants

lmolkova commented Apr 10, 2025 •

edited

Loading

austinborn Jul 12, 2025 •

edited

Loading

austinborn Jul 13, 2025 •

edited

Loading