AWS Lambda Powertools Tracer for MCP Servers

Tracer setup and IAM requirements

Tracer requires the Lambda execution role to have xray:PutTraceSegments and xray:PutTelemetryRecords permissions, and the function must have Active Tracing enabled (not just Pass-Through). Without active tracing, X-Ray receives no data and the tracer silently does nothing — it does not raise an error.

from aws_lambda_powertools import Tracer
from aws_lambda_powertools.utilities.typing import LambdaContext

tracer = Tracer(service="mcp-tool-dispatcher")

@tracer.capture_lambda_handler(
    capture_response=False,   # don't store response in segment — large MCP outputs
    capture_error=True,       # capture exception details on failure (default True)
)
def handler(event: dict, context: LambdaContext) -> dict:
    tool_name = event.get("toolName", "unknown")
    tracer.put_annotation(key="ToolName", value=tool_name)
    tracer.put_annotation(key="UserTier", value=event.get("userTier", "free"))
    return dispatch_tool(event)

CloudFormation / CDK active tracing configuration:

# CDK (TypeScript)
const fn = new lambda.Function(this, "McpToolDispatcher", {
  tracing: lambda.Tracing.ACTIVE,  // required — PASS_THROUGH records nothing
  // ...
});
fn.addToRolePolicy(new iam.PolicyStatement({
  actions: ["xray:PutTraceSegments", "xray:PutTelemetryRecords"],
  resources: ["*"],
}));

capture_method — tracing internal operations

@tracer.capture_method creates an X-Ray subsegment for any method in your MCP server code. The subsegment appears as a child of the Lambda handler segment in the service map, with its own start time, end time, and error state. This is how you identify which internal step is slow — not just that the Lambda was slow.

from aws_lambda_powertools import Tracer

tracer = Tracer(service="mcp-tool-dispatcher")

@tracer.capture_method
def call_external_api(endpoint: str, payload: dict) -> dict:
    # This method appears as a subsegment named "call_external_api"
    # Duration and any exception are captured automatically
    response = http_client.post(endpoint, json=payload)
    response.raise_for_status()
    return response.json()

@tracer.capture_method
def validate_mcp_input(tool_name: str, input_data: dict) -> bool:
    schema = load_tool_schema(tool_name)
    return schema.validate(input_data)

For async methods, Powertools Tracer supports async functions natively:

@tracer.capture_method
async def fetch_context_async(session_id: str) -> dict:
    async with aiohttp.ClientSession() as session:
        async with session.get(f"{context_store_url}/{session_id}") as resp:
            return await resp.json()

Annotations vs metadata

X-Ray has two mechanisms for attaching data to segments. They look similar but have very different behavior:

# Annotations: searchable, low-cardinality
tracer.put_annotation(key="ToolName", value=tool_name)      # "search_codebase"
tracer.put_annotation(key="Status", value="success")        # "success" | "error"
tracer.put_annotation(key="UserTier", value="pro")          # "free" | "pro" | "enterprise"

# Metadata: not searchable, use for debugging context
tracer.put_metadata(key="tool_input", value={"query": query, "filters": filters})
tracer.put_metadata(key="api_response_headers", value=dict(response.headers))

A common mistake is annotating with user_id or request_id. These are high-cardinality: X-Ray won't index them usefully for filtering, and you hit the 50-annotation limit quickly. Use metadata for these values — they're still visible in individual trace views but won't pollute the index.

Manual subsegments for fine-grained timing

When you can't use @tracer.capture_method (e.g., inside a loop, or for a code block that isn't a standalone function), use the context manager form:

from aws_lambda_powertools import Tracer

tracer = Tracer(service="mcp-tool-dispatcher")

def process_tool_batch(tool_calls: list) -> list:
    results = []
    for call in tool_calls:
        # Create a named subsegment for each iteration
        with tracer.provider.in_subsegment(f"tool-{call['name']}") as subsegment:
            subsegment.put_annotation("ToolName", call["name"])
            try:
                result = execute_single_tool(call)
                subsegment.put_annotation("Status", "success")
                results.append(result)
            except Exception as e:
                subsegment.put_annotation("Status", "error")
                subsegment.add_exception(e, traceback.extract_stack())
                raise
    return results

Disabling tracer in local and test environments

X-Ray SDK raises errors when run outside a Lambda environment without an active trace context. Powertools Tracer disables itself automatically when:

• POWERTOOLS_TRACE_DISABLED=true is set
• AWS_SAM_LOCAL=true is set (SAM CLI sets this automatically)
• The function runs outside Lambda (no _X_AMZN_TRACE_ID env var)

When disabled, all decorator and method calls are no-ops — no exceptions, no code changes needed between environments. In unit tests this means you can test handler logic without mocking X-Ray SDK at all:

# pytest conftest.py — disable tracer for all unit tests
import os
os.environ["POWERTOOLS_TRACE_DISABLED"] = "true"
os.environ["POWERTOOLS_SERVICE_NAME"] = "test-service"

Common failures