Initial proposal for MCP semantic conventions

[samsp-msft]

Fixes #2043

Changes

Creates a doc version of semantic conventions for Model Context Protocol (MCP).

The Model Context Protocol (MCP) is an open protocol for interactions between applications and AI models, supporting structured input and output formats. As MCP adoption grows, there's a need to establish semantic conventions for telemetry to ensure consistent observability across implementations.

Note: if the PR is touching an area that is not listed in the existing areas, or the area does not have sufficient domain experts coverage, the PR might be tagged as experts needed and move slowly until experts are identified.

Merge requirement checklist

• CONTRIBUTING.md guidelines followed.
• Change log entry added, according to the guidelines in When to add a changelog entry.
  • If your PR does not need a change log, start the PR title with [chore]
• schema-next.yaml updated with changes to existing conventions.

[linux-foundation-easycla]

• ✅ login: samsp-msft / name: Sam Spencer (7871c01, a52d0ef, e115437, 6b56649, 88544b8, ee62d6a)
• ❌ The email address for the commit (70b4ab0, f253002, eec10bb, 6949e5a, b47acc8, cd547d8) is not linked to the GitHub account, preventing the EasyCLA check. Consult this Help Article and GitHub Help to resolve. (To view the commit's email address, add .patch at the end of this PR page's URL.) For further assistance with EasyCLA, please submit a support request ticket.

[lmolkova]

We define semantic conventions formally in YAML and generate MD from it, please refer to the contributing.md for the details.

It also seems that MCP is heavily based on JSON RPC and we have conventions defined for it here.

I assume there is some MCP specifics that's worth recording, so we'll need to also figure out whether it should be expressed on JSON RPC spans/metrics with extra attributes or as a separate set of conventions.

[eranra]

Hi @samsp-msft, very interesting.

@samsp-msft can you generalize the semantic to something like "genai.tools.repo" with broader focus beyond just the focus on MCP. This will allow future extensions to other types of tool repositories and protocols for GenAI. I am aware that MCP is beyond just tools, but this seems to be the most needed area to observe.

Also, you can add a specific semantic for "genai.tools.repo.type" that will enum value of "mcp"

[samsp-msft]

It also seems that MCP is heavily based on JSON RPC and we have conventions defined for it here.

There are multiple transports, including stdio, JSON RPC and a new Http Streaming one. The MCP standard is evolving rapidly at this point. I would expect the spans for MCP to be wrapped by those for http / RPC based on the way that the communication is used. The attributes here are more about the MCP aspect of calling tools.

@samsp-msft can you generalize the semantic to something like "genai.tools.repo" with broader focus beyond just the focus on MCP. This will allow future extensions to other types of tool repositories and protocols for GenAI. I am aware that MCP is beyond just tools, but this seems to be the most needed area to observe.

This makes sense. MCP is codifying its own transport semantics, but stepping back the same concepts exist when exposing other mechanisms for integrating data sources, tools and prompts into gen_ai. Most of this is not specific to MCP - probably just the concept of a session with an id, and some of the semantics of the type of data being requested, but the latter could be a namespaced value.

For example, if the generalized namespace is gen_ai.integration then we could use a namespaced attribute value that indicates the type eg gen_ai.integration.request = mcp.tools.call.

gen_ai already has a section on tool calling - I think MCP is extending that concept further. What should the base namespace be for the attributes and I can rework this based on that?

[lmolkova]

@samsp-msft thanks for the details! let's start with MCP - specific things inside mcp namespace. I'd suggest talking generalized tool calling integrations separately.

[samsp-msft]

Duplicate #2083