mirror of https://github.com/microsoft/agent-framework.git synced 2026-06-16 21:04:09 +08:00

Files

T

Tao Chen dcc218dbac Python: feat(python): Add MCP client OTel spans per GenAI semantic conventions (#6349 )

* feat(python): Add MCP client OTel spans per GenAI semantic conventions

Implement MCP client spans per the OTel GenAI Semantic Conventions for MCP
(https://opentelemetry.io/docs/specs/semconv/gen-ai/mcp/#client).

Operations instrumented:
- initialize: CLIENT span capturing MCP session setup
- tools/list: CLIENT span for tool listing (per-page)
- prompts/list: CLIENT span for prompt listing (per-page)
- tools/call: CLIENT span (nested under execute_tool when called via FunctionTool)
- prompts/get: CLIENT span

Span attributes follow the MCP semantic conventions:
- Required: mcp.method.name
- Conditional: error.type, gen_ai.tool.name, gen_ai.prompt.name
- Recommended: gen_ai.operation.name, mcp.protocol.version, mcp.session.id,
  network.transport, server.address, server.port

Transport-specific attributes per subclass:
- MCPStdioTool: network.transport=pipe
- MCPStreamableHTTPTool: network.transport=tcp, network.protocol.name=http
- MCPWebsocketTool: network.transport=tcp, network.protocol.name=websocket

All span creation gated behind OBSERVABILITY_SETTINGS.ENABLED.

Closes #3624
Closes #4697

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* refactor: simplify MCP spans — remove enrichment logic and protocol version caching

- Always create nested CLIENT spans for tools/call instead of enriching
  the parent execute_tool span
- Remove _ACTIVE_TOOL_EXECUTION_SPAN contextvar (no longer needed)
- Remove enrich_span_with_mcp_attributes() helper
- Remove _otel_error_type preservation in FunctionTool.invoke()
- Remove _mcp_protocol_version instance variable; protocol version is
  only set on the initialize span where it is available

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Refine copilot solution

* fix: enable automatic exception recording on MCP spans

Remove record_exception=False and set_status_on_exception=False from
create_mcp_client_span. Let OTel handle exception recording and status
setting automatically. The manual set_mcp_span_error calls for tools/call
still correctly set error.type (which OTel's automatic handling doesn't
touch), so tool_error is preserved.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Reduce number of lines

* Add comment to sample

* test: address PR review comments on MCP observability tests

- Fix initialize test to call mocked session.initialize() and read
  protocolVersion from the result instead of hardcoding it
- Add tools/call McpError error-path test
- Add prompts/get McpError error-path test

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Fix export error

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

dcc218dbac · 2026-06-05 19:23:01 +00:00

History

agent_as_mcp_server.py

Python: Add header_provider to Streamable HTTP MCP servers (#4849 )

2026-03-31 17:23:49 +00:00

mcp_api_key_auth.py

Python: Add header_provider to Streamable HTTP MCP servers (#4849 )

2026-03-31 17:23:49 +00:00

mcp_github_pat.py

Python: feat(python): Add MCP client OTel spans per GenAI semantic conventions (#6349 )

2026-06-05 19:23:01 +00:00

mcp_long_running_task.py

Python: MCP long-running task support in Python (#6319 )

2026-06-05 00:04:55 +00:00

README.md

Python: MCP long-running task support in Python (#6319 )

2026-06-05 00:04:55 +00:00

README.md

MCP (Model Context Protocol) Examples

This folder contains examples demonstrating how to work with MCP using Agent Framework.

What is MCP?

The Model Context Protocol (MCP) is an open standard for connecting AI agents to data sources and tools. It enables secure, controlled access to local and remote resources through a standardized protocol.

Examples

Sample	File	Description
Agent as MCP Server	`agent_as_mcp_server.py`	Shows how to expose an Agent Framework agent as an MCP server that other AI applications can connect to
API Key Authentication	`mcp_api_key_auth.py`	Demonstrates API key authentication with MCP servers using `header_provider`, runtime invocation kwargs, and a command-line API key argument
GitHub Integration with PAT	`mcp_github_pat.py`	Demonstrates connecting to GitHub's MCP server using Personal Access Token (PAT) authentication
Long-Running Task	`mcp_long_running_task.py`	Demonstrates transparent SEP-2663 long-running task handling for MCP tools that advertise `taskSupport=required`. Self-spawns a stdio MCP child server

Prerequisites

Most samples in this folder use OpenAI:

OPENAI_API_KEY environment variable
OPENAI_CHAT_MODEL environment variable

Run mcp_api_key_auth.py with the MCP API key as the first command-line argument.

For mcp_github_pat.py:

GITHUB_PAT - Your GitHub Personal Access Token (create at https://github.com/settings/tokens)

For mcp_long_running_task.py (uses Azure OpenAI via Entra-ID):

Run az login once
AZURE_OPENAI_ENDPOINT - your Azure OpenAI resource endpoint, e.g. https://<resource>.openai.azure.com/
AZURE_OPENAI_CHAT_MODEL (or AZURE_OPENAI_MODEL) - the deployment name (e.g. gpt-4o-mini)