> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sedata-ai.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture

> How @sedata-ai/mcp instruments your server, where data flows, and what runs in-process.

The package is a thin wrapper around the OpenTelemetry Node SDK plus a small
HTTP client for safety checks. Everything runs in your process — no sidecar,
no agent.

## Components

<CardGroup cols={2}>
  <Card title="TelemetryManager" icon="cube" href="/api-reference/telemetry-manager">
    Owns the OpenTelemetry `NodeSDK`, the trace exporter, the metric reader,
    and the session id. Validates config on construction.
  </Card>

  <Card title="McpServerInstrumentation" icon="wrench" href="/api-reference/mcp-server-instrumentation">
    Patches `server.registerTool` so every registered handler becomes
    instrumented. Records spans, durations, counters, and safety attributes.
  </Card>

  <Card title="safetyCheck wrapper" icon="shield" href="/api-reference/safety-check">
    Decorates a tool handler. Calls `https://api.sedata-ai.tech/security/safety-check`
    with the chosen parameter, blocks if flagged, otherwise lets the handler run.
  </Card>

  <Card title="ConfigValidator" icon="badge-check" href="/api-reference/config-validator">
    Pure validation. Throws on missing `exporterEndpoint`, out-of-range
    `samplingRate`, malformed auth blocks, etc.
  </Card>
</CardGroup>

## Data flow

```mermaid theme={null}
flowchart LR
  A[MCP client] -->|tools/call| B[Your MCP server]
  B -->|registerTool patched| C[Instrumented handler]
  C -->|optional| D[safetyCheck → api.sedata-ai.tech]
  C -->|always| E[OTel span + metrics]
  E -->|OTLP/HTTP| F[Your OTLP backend]
  D -->|verdict| C
```

1. The MCP client (Claude, an agent, an editor) issues `tools/call`.
2. The MCP SDK invokes the registered handler — but the handler was replaced
   at `registerTool` time with an instrumented version.
3. The instrumented handler opens an active span, increments a counter, and
   runs your original handler inside it.
4. If the handler is wrapped by `safetyCheck`, a network call to
   `api.sedata-ai.tech` happens first. A flagged result short-circuits the
   handler with a safe blocked response.
5. The span ends with status + duration. The OTLP exporter batches spans and
   metrics out to your `exporterEndpoint`.

## Where the SDK runs

Everything is in-process:

* The `NodeSDK` starts on `instrumentServer(...)` and stops when you call
  `telemetry.shutdown()`.
* Trace export uses **OTLP/HTTP** by default. Switch to console for local dev.
  See [Console debugging](/guides/console-debugging).
* Metric export uses a `PeriodicExportingMetricReader` that pushes every
  `metricExportIntervalMs` (default **5000 ms**).

<Note>
  The package never opens an inbound socket and never holds your tool calls
  open waiting for telemetry to flush — exports are batched in the background.
</Note>

## What is instrumented today

| Surface                             | Status              |
| ----------------------------------- | ------------------- |
| `tools/call` (every `registerTool`) | ✅ Auto-instrumented |
| Completions                         | 🚧 Planned          |
| Logs                                | 🚧 Planned          |
| Notifications                       | 🚧 Planned          |
| Pings                               | 🚧 Planned          |
| Prompts                             | 🚧 Planned          |
| Resources                           | 🚧 Planned          |
| Roots                               | 🚧 Planned          |
| Sampling                            | 🚧 Planned          |

You can always record any of these yourself today using the
[custom instrumentation API](/metrics-and-traces/custom-instrumentation).

## Next

<CardGroup cols={2}>
  <Card title="Tracing" icon="route" href="/concepts/tracing">
    What gets recorded on each span.
  </Card>

  <Card title="Telemetry pipeline" icon="signal-stream" href="/concepts/telemetry-pipeline">
    Exporters, samplers, and batching.
  </Card>
</CardGroup>