trail-spec

An open protocol for cross-MCP server content tracking and deduplication.
Spec (EN) · Spec (RU) · Examples · README на русском

The Problem

You have multiple MCP servers — one fetches content, another posts to Telegram, a third cross-posts to a social network. Each server is isolated by design. No server sees the others.

Now answer these questions:

• Was this image already posted to Telegram?
• Did the social network post succeed or fail?
• Where did the pipeline break yesterday at 3am?

You can't. There's no standard way to track content across isolated MCP servers.

TRAIL solves this.

How It Works

                    LLM Orchestrator (Claude, GPT, etc.)
                   /          |            \
                  /           |             \
         ┌──────────┐  ┌──────────┐  ┌──────────┐
         │ Civitai  │  │ Telegram │  │ Facebook │
         │   MCP    │  │   MCP    │  │   MCP    │
         └────┬─────┘  └────┬─────┘  └────┬─────┘
              │              │              │
         trail.jsonl    trail.jsonl    trail.jsonl

Each server keeps its own trail.jsonl — an append-only log with a shared schema. The orchestrator reads all logs and connects the dots using a universal Content ID (content_id).

One pipeline run across three servers:

# Civitai trail.jsonl
{"version":2,"timestamp":"2026-04-05T14:07:00Z","content_id":"civitai:image:12345","action":"selected","requester":"daily-post","trace_id":"run-001"}

# Telegram trail.jsonl
{"version":2,"timestamp":"2026-04-05T14:07:05Z","content_id":"civitai:image:12345","action":"posted","requester":"daily-post","trace_id":"run-001","details":{"platform":"telegram","platform_id":"42"}}

# Facebook trail.jsonl
{"version":2,"timestamp":"2026-04-05T14:07:30Z","content_id":"civitai:image:12345","action":"posted","requester":"daily-post","trace_id":"run-001","details":{"platform":"facebook","platform_id":"99"}}

The orchestrator sees: civitai:image:12345 → selected → posted to Telegram (#42) → posted to Facebook (#99). Full pipeline traced via trace_id.

Key Features

• Zero shared state — no database, no message bus, no inter-server communication
• Append-only JSONL — atomic writes, no corruption risk, trivially parseable
• Self-documenting — readable field names: content_id, action, requester, timestamp, version
• Universal Content ID — source:type:id format traces content across any number of servers
• Trace correlation — optional trace_id links entries across servers into one pipeline trace
• 15 standard actions — fetched, selected, posted, failed, skipped, retrying, transformed, moderated, expired, delivered, delegated, received, evaluated, guarded, acknowledged
• Multi-agent patterns — delegation, evaluation, guardrails, and human-in-the-loop via standard actions and caused_by chains
• Standard tools — get_trail, mark_trail, get_trail_stats — same API everywhere
• Standardized details — error types, cost tracking, content metadata, platform IDs, guardrail results, evaluation scores
• Auto-logging — publishing tools log automatically when content_id and requester are passed
• 3 conformance levels — Basic (5 fields + 2 tools), Standard (+ tracing, auto-logging, discovery), Full (+ causality chains, OTel export, all 15 actions)
• Zero dependencies — stdlib only, no external packages
• OTel-native mapping — caused_by → parentSpanId, server → service.name, full span tree in any OTel backend

Quick Start

Python

from trail import Trail

trail = Trail("./data")

# Log an event
await trail.append(
    content_id="civitai:image:12345",
    action="posted",
    requester="daily-post",
    details={"platform": "telegram", "platform_id": "42"},
    trace_id="run-001"
)

# Query the trail
entries, total = await trail.query(content_id="civitai:image:12345")

# Check if already posted
if await trail.is_used("civitai:image:12345"):
    print("Already posted, skipping")

# Get pipeline stats
stats = await trail.stats(requester="daily-post")
print(f"Posted: {stats['by_action'].get('posted', 0)}")

TypeScript

import { Trail } from "./trail";

const trail = new Trail("./data");

// Log an event
await trail.append("civitai:image:12345", "posted", "daily-post", {
  details: { platform: "telegram", platform_id: "42" },
  trace_id: "run-001",
});

// Query the trail
const { entries, total } = await trail.query({ content_id: "civitai:image:12345" });

// Check if already posted
if (await trail.isUsed("civitai:image:12345")) {
  console.log("Already posted, skipping");
}

// Get pipeline stats
const stats = await trail.stats("daily-post");
console.log(`Posted: ${stats.by_action.posted ?? 0}`);

Entry Schema

{"version":2,"timestamp":"2026-04-05T14:07:00.123Z","content_id":"civitai:image:12345","action":"posted","requester":"daily-post","server":"telegram-mcp","trace_id":"run-001","details":{"platform":"telegram","platform_id":"42"}}

Standard Actions

Standard Tools

Every TRAIL-compatible MCP server exposes:

Publishing tools (send_photo, publish_post, etc.) accept optional content_id + requester + trace_id for automatic logging.

Standardized Details

TRAIL defines standard sub-fields in details for cross-server consistency:

{
  "details": {
    "platform": "telegram",
    "platform_id": "42",
    "url": "https://t.me/channel/42",
    "error": {"type": "rate_limit", "message": "429", "retry_after": 60},
    "cost": {"tokens_in": 150, "tokens_out": 50, "usd": 0.003},
    "content": {"type": "image", "width": 1024, "height": 1024, "model": "Flux.1"},
    "duration_ms": 1200,
    "delegate_to": "optimizer-mcp",
    "score": 0.92,
    "evaluator": "llm-judge",
    "guardrail": "nsfw-filter",
    "passed": true,
    "acknowledged_by": "[email protected]",
    "decision": "approve"
  }
}

See SPEC.md — Details Field for the full specification.

Deduplication

The orchestrator handles deduplication, not the servers:

1. Before fetching  → get_trail(requester="daily-post", since="...") on source
2. Before posting   → get_trail(content_id="civitai:image:12345", action="posted") on destination
3. If already posted → skip

Servers MAY offer convenience filters (e.g., exclude_used=true) that use the trail internally.

Discovery

Servers advertise TRAIL support via capabilities:

{
  "capabilities": {
    "trail": {
      "version": 2,
      "server": "telegram-mcp",
      "conformance": "standard",
      "actions": ["fetched", "selected", "posted", "failed", "skipped", "guarded"],
      "auto_log_tools": ["send_photo", "send_message", "publish_post"],
      "supports": {
        "trace_id": true,
        "entry_id": true,
        "caused_by": true,
        "tags": true,
        "server_field": true
      },
      "retention_days": 90
    }
  }
}

Adopting TRAIL in Your MCP Server

Basic (Level 0) — deduplication and simple tracking:

1. Copy trail.py or trail.ts into your project
2. Add get_trail and mark_trail tools
3. Done

Standard (Level 1) — production pipelines:
4. Set server name in Trail constructor
5. Add get_trail_stats tool
6. Add content_id + requester + trace_id params to publishing tools
7. Advertise TRAIL in capabilities with "conformance": "standard"

Full (Level 2) — multi-agent observability:
8. Enable entry_id auto-generation and caused_by support
9. Implement all 15 standard actions
10. Add OTel export capability

Full specification: SPEC.md | SPEC.ru.md

Why Not...

FAQ

Q: Why readable field names instead of short ones?
A: A protocol for decades must be self-documenting. content_id is clear on first sight. The overhead is ~15 KB/year at typical rates — negligible.

Q: Do I need all the optional fields?
A: No. The five required fields are the whole protocol. Optional fields unlock advanced features when you need them.

Q: Orchestrator crashes mid-pipeline?
A: Use trace_id to find all entries for that run. The last entry's action shows where to resume.

Q: What are conformance levels?
A: Three tiers — Basic (5 fields + 2 tools), Standard (+ tracing, server, auto-logging), Full (+ causality chains, all 15 actions, OTel export). Start at Basic.

Q: Multi-agent pipelines?
A: delegated/received action pairs + caused_by chains + server field. The orchestrator reconstructs the full DAG. See SPEC.md — Multi-Agent Patterns.

Prior Art

We searched extensively for existing solutions. As of April 2026, no cross-MCP content tracking protocol exists:

• MCP Spec — no server-to-server communication by design
• CA-MCP (arXiv 2601.11595) — shared context store for transient state, not persistent content logs
• lokryn/mcp-log — JSONL audit logging for operations (SOC2/HIPAA), not content tracking
• IBM ContextForge — gateway proxy with OTel tracing, not content semantics
• OpenTelemetry GenAI — semantic conventions for LLM calls (Development status), not content lifecycle
• IETF AAT (draft-sharif-agent-audit-trail) — compliance-focused audit trail with hash chains, no content semantics
• Google A2A — agent-to-agent communication protocol with traceability extension, not a logging format
• Langfuse / LangSmith / Arize Phoenix — LLM observability platforms, trace API calls not content
• Agent Protocol (agentprotocol.ai) — REST API for interacting with agents, not a log format

TRAIL fills a unique gap: lightweight, zero-dependency content tracking with multi-agent support — no other protocol combines content semantics (content_id), zero shared state, and agent patterns (delegation, evaluation, guardrails).

MCP Servers Implementing TRAIL

Implementing TRAIL in your server? Open a PR to add it here.

Other Projects by @timoncool

Support the Author

I build open-source software and do AI research. Most of what I create is free and available to everyone. Your donations help me keep creating without worrying about where the next meal comes from =)

All donation methods | dalink.to/nerual_dreming | boosty.to/neuro_art

• BTC: 1E7dHL22RpyhJGVpcvKdbyZgksSYkYeEBC
• ETH (ERC20): 0xb5db65adf478983186d4897ba92fe2c25c594a0c
• USDT (TRC20): TQST9Lp2TjK6FiVkn4fwfGUee7NmkxEE7C

Star History

MIT License · Made with Claude Code