admin-valentin/arcade-mcp
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
arcade-mcp/libs/arcade-mcp-server
History
Sankara R. Avula 78c8e6fb99
feat: Add TelemetryPassbackMiddleware for serverExecutionTelemetry capability (#797) 
**Implements**: [SEP-2448: server execution telemetry]
(https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2448)



**Description:**

**The Observability Gap (The Problem)**

MCP clients propagate trace context to servers, but server-side
execution remains a black box. The client sees a single tools/call or
resources/read span; everything the server does (auth checks, policy
evaluation, API calls, sub-tool invocations) is invisible. In
cross-organization deployments, clients and servers use separate
observability backends with no shared collector access, making
traditional span export useless.

<img width="1015" height="450" alt="Screenshot 2026-03-23 at 3 43 21 PM"
src="https://github.com/user-attachments/assets/58c817b5-fee6-46a3-9877-d523a25368ad"
/>


**Server Execution Telemetry (The Solution)**

Servers advertise serverExecutionTelemetry and return a curated slice of
their execution spans directly in _meta.otel of the response. Clients
ingest these verbatim OTLP spans into their own collector, stitching
server-side execution into their distributed trace; no shared
infrastructure required. The black box becomes transparent.

<img width="945" height="574" alt="Screenshot 2026-03-23 at 3 43 44 PM"
src="https://github.com/user-attachments/assets/38d97c94-aa73-4e62-9b4e-3264600e5ed0"
/>

.
**Summary:**

Implement MCP serverExecutionTelemetry capability that enables
cross-organization distributed tracing by returning server-side
OpenTelemetry spans to clients inline via _meta.otel.traces.

  Server-side (middleware):
  - TelemetryPassbackMiddleware intercepts tools/call and resources/read
- ContextVarSpanCollector isolates span collection per-request via
ContextVar
- Propagates traceparent from client request for distributed trace
stitching
- Serializes collected spans to verbatim OTLP JSON (resourceSpans
format), directly POSTable to /v1/traces
- Top-level span filtering by default; full span tree via detailed
opt-in
- Middleware advertises capabilities via get_capabilities() on the
Middleware base class
  - Provisional API: FutureWarning emitted until SEP-2448 is ratified

  Client-side (reference agent):
- LangChain ReAct agent connects to MCP server via
streamable_http_client with OAuth 2.1
  - Detects serverExecutionTelemetry capability at initialization
- Dynamically wraps discovered MCP tools with traceparent propagation
and _meta.otel span request
- Ingests returned server spans into Jaeger (OTLP JSON) and Galileo
(OTLP protobuf)
- Two-act demo: --no-passback (black box) vs default (full server-side
visibility)

  Dependencies:
  - opentelemetry-api and opentelemetry-sdk added to arcade-mcp-server

  Bump arcade-mcp-server version to 1.18.0.
2026-03-25 15:57:50 -07:00
..
arcade_mcp_server feat: Add TelemetryPassbackMiddleware for serverExecutionTelemetry capability (#797) 2026-03-25 15:57:50 -07:00
Makefile remove mkdocs for arcade-mcp (#617) 2025-10-13 10:47:41 -07:00
pyproject.toml feat: Add TelemetryPassbackMiddleware for serverExecutionTelemetry capability (#797) 2026-03-25 15:57:50 -07:00
README.md Server start events (#635) 2025-10-22 16:14:52 -07:00

README.md

Arcade MCP Server

Arcade Logo

Arcade MCP (Model Context Protocol) Server enables AI assistants and development tools to interact with your Arcade tools through a standardized protocol. Build, deploy, and integrate MCP servers seamlessly across different AI platforms.

Quick Links

Features

  • 🚀 FastAPI-like Interface - Simple, intuitive API with MCPApp
  • 🔧 Tool Discovery - Automatic discovery of tools in your project
  • 🔌 Multiple Transports - Support for stdio and HTTP/SSE
  • 🤖 Multi-Client Support - Works with Claude, Cursor, and more
  • 📦 Package Integration - Load installed Arcade packages
  • 🔐 Built-in Security - Environment-based configuration and secrets
  • 🔄 Hot Reload - Development mode with automatic reloading
  • 📊 Production Ready - Deploy with Docker, systemd, PM2, or cloud platforms

Getting Started

Installation

pip install arcade-mcp-server

Create Your First Server

from arcade_mcp_server import MCPApp
from typing import Annotated

app = MCPApp(name="my-tools", version="1.0.0")

@app.tool
def greet(name: Annotated[str, "Name to greet"]) -> str:
    """Greet someone by name."""
    return f"Hello, {name}!"

if __name__ == "__main__":
    app.run()

Run Your Server

# For development
python my_tools.py

# For Claude Desktop
python -m arcade_mcp_server stdio

# For HTTP clients
python -m arcade_mcp_server --host 0.0.0.0 --port 8080

Community

Analytics & Privacy

Arcade MCP Server collects anonymous usage data to help us improve the service and debug issues. We track "MCP server start" events to understand server usage patterns and reliability.

What We Track

When the server starts, we collect the following information:

  • Server configuration: transport type (http or stdio), host, port
  • Server metadata: tool count, server version
  • Runtime environment: Python version, OS type and release
  • Timing: device timestamp
  • Errors: error messages (if startup fails)

Privacy

  • For anonymous users: Events are tracked with an anonymous ID and no user profile is created
  • For authenticated users: Events are linked to your account to help us provide better support
  • No sensitive data (credentials, tool inputs/outputs, or personal information) is ever collected

Opt Out

To disable usage tracking, set the environment variable ARCADE_USAGE_TRACKING to 0.

License

Arcade MCP Server is open source software licensed under the MIT license.