RFC: MCP Usage Tracking in Agent Trace

[nkyriakidis]

1. Abstract

This RFC proposes an extension to the Agent Trace specification to track Model Context Protocol (MCP) usage. As agents increasingly rely on MCP servers for external context (docs, databases) and tools (browsers, terminal execution), it is critical to record which MCP resources influenced a specific code generation for full auditability and "trace-to-source" debugging.

2. Motivation

Currently, Agent Trace tracks which model was used and where the conversation is hosted. However, it lacks a standardized way to record the augmented context or tools provided via MCP.

• Auditability: Knowing that a code block was generated based on a specific version of a documentation MCP server.
• Reproducibility: Identifying the exact tool output (e.g., a terminal command or a database schema) that led to an AI's decision.
• Security: Tracking which MCP servers were granted access during a specific contribution.

3. Proposed Changes

3.1 New Schema: mcp_usage

We propose adding an optional mcp field to the conversation or range objects. This allows for both broad (conversation-level) and granular (per-edit) tracking of MCP interactions.

New Definition: mcp_call

{
  "$defs": {
    "mcp_call": {
      "type": "object",
      "required": ["server_name", "type"],
      "properties": {
        "server_name": { "type": "string", "description": "Name of the MCP server (e.g., 'github-mcp-server')" },
        "server_version": { "type": "string" },
        "type": { "type": "string", "enum": ["tool", "resource", "prompt"] },
        "method": { "type": "string", "description": "The specific tool or resource URI accessed (e.g., 'get_issue')" },
        "uri": { "type": "string", "format": "uri", "description": "The MCP resource URI if applicable" },
        "input_hash": { "type": "string", "description": "Hash of the arguments/params sent to the MCP server" },
        "output_snapshot_url": { "type": "string", "format": "uri", "description": "Link to the data returned by the MCP call" }
      }
    }
  }
}

3.2 Schema Integration

The conversation object will be updated to include an mcp_calls array:

"conversation": {
  "type": "object",
  "required": ["ranges"],
  "properties": {
    "url": { "type": "string", "format": "uri" },
    "contributor": { "$ref": "#/$defs/contributor" },
    "ranges": { "type": "array", "items": { "$ref": "#/$defs/range" } },
    "mcp_calls": { 
      "type": "array", 
      "items": { "$ref": "#/$defs/mcp_call" },
      "description": "List of MCP interactions that informed this contribution"
    }
  }
}

4. Example Trace Record

Here is how a trace would look when an agent uses a "PostgreSQL" MCP server to read a schema before writing a migration:

{
  "version": "0.2.0",
  "id": "772e8400-e29b-41d4-a716-446655440000",
  "files": [
    {
      "path": "src/db/migration.ts",
      "conversations": [
        {
          "url": "https://api.cursor.com/v1/conversations/123",
          "contributor": { "type": "ai", "model_id": "anthropic/claude-3-5-sonnet" },
          "mcp_calls": [
            {
              "server_name": "postgres-inspector",
              "type": "resource",
              "method": "read_resource",
              "uri": "db://main/schemas/public/users",
              "output_snapshot_url": "https://trace-storage.com/snaps/mcp-123-abc"
            }
          ],
          "ranges": [
            { "start_line": 1, "end_line": 20, "content_hash": "murmur3:4f1a2b" }
          ]
        }
      ]
    }
  ]
}

5. Design Decisions & FAQ

Why at the Conversation level?

MCP calls usually happen during the "thinking" or "tool-use" phase of a conversation. Placing mcp_calls at the conversation level provides a clear history of what "senses" the agent used to produce the resulting code ranges.

How to handle large MCP outputs?

The specification recommends using output_snapshot_url or input_hash rather than inlining the full MCP response. This keeps the .agent-trace files lightweight while allowing external tools to resolve the data if needed.

Interaction with metadata

While vendors can already use the metadata field for MCP, standardizing it in the top-level schema ensures that a "Trace Viewer" (like the one proposed in the agent-trace issues) can visualize tool-use across different editors (Cursor, Windsurf, etc.).