Python: Fix MCP metadata and tool name handling

[eavanvalkenburg]

Motivation & Context

MCP integrations need deterministic handling for request metadata and remote tool identity when servers provide metadata, prefixed tool names, or tool names that normalize to the same local function name.

This change keeps MCP request metadata and exposed tool filtering aligned with explicit framework-controlled inputs and remote tool identities.

Description & Review Guide

• What are the major changes?
  • Validate MCP _meta request metadata keys using the MCP 2025-06-18 key-name format.
  • Keep model-provided _meta out of generated MCP function calls while preserving trusted caller/runtime metadata.
  • Merge caller/runtime metadata, OpenTelemetry metadata, and tools/list metadata with a deterministic precedence order.
  • Filter allowed_tools by raw remote MCP tool identity and reject ambiguous remote tool names that map to the same local function name.
  • Add regression coverage for metadata precedence, metadata key validation, raw-name allowlisting, and normalized-name collisions.
  • Update the core MCP guidance to describe the current metadata and tool identity behavior.
  • Widen the Hyperlight output directory helper type used by tests to the minimal .name protocol it requires.
• What is the impact of these changes?
  • MCP tools now use deterministic request metadata precedence.
  • Ambiguous MCP tool name collisions fail during tool loading instead of exposing one colliding tool by ordering.
  • Existing prefixed local tool configuration remains supported when it maps unambiguously to the same raw remote tool.
  • Configurations that allow a tool only by a normalized/local alias for a differently named remote tool should switch to the raw remote MCP tool name.
• What do you want reviewers to focus on?
  • The compatibility behavior for allowed_tools with raw, normalized, and prefixed names.
  • The _meta merge precedence between caller/runtime metadata, OpenTelemetry metadata, and tools/list metadata.

Related Issue

N/A - no public issue provided.

Contribution Checklist

• The code builds clean without any errors or warnings
• All unit tests pass, and I have added new tests where possible
• The PR follows the Contribution Guidelines
• This PR is linked to an issue and there is no other open PR for this issue (see Related Issue above).
• This is not a breaking change. If it is a breaking change, add the breaking change label (or add "[BREAKING]" to the title prefix, before or after any language prefix) — a workflow keeps the label and title prefix in sync automatically.

[github-actions]

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/core/agent_framework
_mcp.py	1208	93	92%	232, 238, 347, 366, 566, 626–627, 759, 800, 824, 837, 861–862, 881–884, 886–887, 891, 917, 951–953, 955, 1008–1010, 1069–1070, 1339, 1380–1381, 1394, 1397, 1406–1407, 1412–1413, 1419, 1473–1474, 1494–1495, 1504–1505, 1510–1511, 1517, 1610, 1613, 1640, 1663–1667, 1690–1692, 1697, 1701–1702, 1804, 1811, 1813, 1884, 1899–1900, 1907–1908, 1913–1914, 1919, 1923, 1938, 2000, 2183, 2185, 2207, 2209–2212, 2225–2226, 2270, 2332, 2731–2732, 2954–2955, 2973
packages/hyperlight/agent_framework_hyperlight
_execute_code_tool.py	620	93	85%	69, 175, 238, 270, 273, 308–309, 324, 326, 339, 357, 367, 392, 397, 404, 410, 418, 426–428, 430–435, 475, 480, 482, 484, 509–510, 516–517, 522–523, 542–543, 552–553, 588, 619, 625–628, 646–649, 657, 690–691, 698–699, 701, 711–712, 752–753, 760, 806, 862–868, 937, 964, 1034, 1070, 1076–1078, 1107–1111, 1115–1116, 1121, 1138–1142, 1146–1147, 1204–1205
TOTAL	40661	4626	88%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
8113	34 💤	0 ❌	0 🔥	2m 11s ⏱️

[Copilot]

Pull request overview

This PR tightens the Python MCP integration’s handling of request metadata (_meta) and remote tool identity, aiming for deterministic behavior when servers return metadata, tool names are prefixed, or multiple remote tool names normalize to the same local function name.

Changes:

• Add MCP _meta key-name validation and enforce deterministic metadata precedence (caller/runtime < OpenTelemetry < tools/list).
• Filter allowed_tools/approval matching by raw remote tool identity and reject normalized-name collisions during tool loading.
• Add regression tests for metadata precedence/stripping and raw-name allowlisting vs normalized-name collisions; update MCP guidance docs.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

File	Description
python/packages/core/agent_framework/_mcp.py	Implements _meta validation + deterministic merge precedence; changes allow/approval matching to prefer raw remote tool identity; detects normalized-name collisions.
python/packages/core/tests/core/test_mcp.py	Adds regression tests for tool name collisions, raw-name allowlisting, _meta stripping, metadata precedence, and invalid _meta keys.
python/packages/core/AGENTS.md	Updates MCP guidance to document the new metadata precedence, model _meta stripping, and raw remote tool identity behavior.

[github-actions]

Automated Code Review

Reviewers: 1 | Confidence: 84% | Result: All clear

Reviewed: Design Approach

---

Automated review by eavanvalkenburg's agents