# agent-observability-mcp

[![MCPize](https://mcpize.com/badge/@contact.agentia1984/agent-observability)](https://mcpize.com/mcp/agent-observability)

Serveur **MCP** (Model Context Protocol) d'**observabilite pour agents IA** : journalisation des traces et des spans, recherche, metriques de latence, de tokens et de cout, detection d'anomalies.

> Aucune base de donnees, aucune cle d'API, aucun service tiers : tout tient dans un tampon memoire configurable.

## Outils exposes

| Outil | Description |
| --- | --- |
| `obs_event_log` | Journalise un span d'agent : operation, trace, statut, duree, modele, tokens, cout, attributs libres. |
| `obs_trace_get` | Reconstitue la chronologie complete d'une trace : spans ordonnes, duree cumulee, erreurs, tokens, cout. |
| `obs_events_search` | Recherche des evenements par projet, operation, type, statut, modele, fenetre temporelle, duree minimale ou texte libre. |
| `obs_metrics_summary` | Agrege volume, taux d'erreur, latences p50 / p95 / p99, tokens, cout et top 5 des operations. |
| `obs_anomaly_scan` | Signale taux d'erreur anormaux, latences aberrantes, concentration de cout et boucles de retry. |
| `obs_projects_list` | Liste les projets instrumentes et le remplissage du tampon. |

Chaque outil accepte `response_format` : `markdown` ou `json`.

## Modele de donnees

Un evenement represente un span : `trace_id`, `span_id`, `parent_span_id`, `name`, `kind` (llm, tool, retrieval, agent, http, other), `status` (ok, error, timeout), `duration_ms`, `model`, `input_tokens`, `output_tokens`, `cost_usd`, `attributes`.

## Installation locale

```bash
npm install
npm run build
node dist/index.js
```

## Connect via MCPize

Use this MCP server instantly with no local installation:

```bash
npx -y mcpize connect @contact.agentia1984/agent-observability --client claude
```

Or connect at: **https://mcpize.com/mcp/agent-observability**

## Configuration Claude Desktop

```json
{
  "mcpServers": {
    "agent-observability": {
      "command": "node",
      "args": ["/chemin/vers/agent-observability-mcp/dist/index.js"]
    }
  }
}
```

## Deploiement heberge (HTTP Streamable)

```bash
TRANSPORT=http node dist/index.js
```

Le serveur ecoute sur `0.0.0.0` et lit `process.env.PORT` (8083 par defaut). Endpoints : `POST /mcp`, `POST /` et `GET /health`.

## Variables d'environnement

| Variable | Valeur | Role |
| --- | --- | --- |
| `TRANSPORT` | `stdio` (defaut) ou `http` | Choix du transport MCP. |
| `PORT` | entier | Port d'ecoute en mode HTTP. |
| `OBS_MAX_EVENTS` | entier, defaut 5000 | Taille du tampon circulaire d'evenements. |

## Limites connues

Le stockage est en memoire : les evenements sont perdus au redemarrage et ne sont pas partages entre plusieurs instances. Pour un usage longue duree, journalisez en parallele vers votre propre entrepot.

## Licence

MIT.