# @originchain/telemetry-mcp

An MCP server that gives an AI agent OriginChain's telemetry tools: log
patterns, semantic incident analysis, distributed traces and service graphs.

Works with Claude Desktop, Cursor, Continue, Cline, Zed AI, and anything else
that speaks the Model Context Protocol.

## Which package do I want?

There are two, and they do different jobs.

| Package | Talks to | Tools |
|---|---|---|
| [`@originchain/mcp-server`](https://www.npmjs.com/package/@originchain/mcp-server) | your database | ask, SQL, vector search, full-text, schemas |
| `@originchain/telemetry-mcp` (this one) | the telemetry agent | log volume, patterns, incidents, traces, service graph |

They do not conflict. Configure both if you want both.

## Install

```bash
npm install -g @originchain/telemetry-mcp
```

Or let your MCP host fetch it on demand with `npx`, as below.

## Configure

The telemetry agent normally runs inside a private network, so you reach it
through a port-forward. Point this at wherever that forward listens.

Claude Desktop, in `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "originchain-telemetry": {
      "command": "npx",
      "args": ["-y", "@originchain/telemetry-mcp"],
      "env": {
        "OC_TELEMETRY_AGENT": "http://127.0.0.1:8892"
      }
    }
  }
}
```

Cursor, in `.cursor/mcp.json`, uses the same shape.

| Variable | Default | Meaning |
|---|---|---|
| `OC_TELEMETRY_AGENT` | `http://127.0.0.1:8892` | Base URL of the telemetry agent |
| `OC_TELEMETRY_TIMEOUT` | `120000` | Per-call timeout in milliseconds |

## Tools

| Tool | Use it for |
|---|---|
| `log_volume` | Total volume and distinct pattern count |
| `top_patterns` | Highest-volume log patterns |
| `similar_patterns` | Meaning-based search, finds related patterns sharing no keywords |
| `recent_events` | The actual recent log lines, with real values rather than templates |
| `recent_errors` | Top error patterns in a window, with the window's total volume |
| `incident_analysis` | One call fusing semantic cluster, latest occurrence, trace chain, service graph and rate anomaly |
| `service_graph` | Who calls whom, with call counts |
| `fts_search` | Keyword search over log template text |
| `trace_lookup` | Every span of one distributed trace |
| `sql_query` | One read-only SELECT for a specific filtered lookup |

Two notes worth knowing, because they change the answers you get.

**Do not filter on severity for a loose "any errors?" question.** Services here
log recoverable failures at WARN, so filtering on ERROR finds nothing and reads
as "no errors". Filter by service or by substring instead.

**Prefer `recent_events` over a sorted `sql_query`** when you want actual log
lines. Ordering over the occurrences table times out.

## If a tool fails

The most common failure is that the agent is not reachable, because the
port-forward is not running. The server says so explicitly rather than
returning a bare connection error, so the message in your agent's transcript
should tell you what to fix.

## How it works

This process is deliberately thin. It advertises the tool surface over stdio
and forwards each call to the agent's `/tool` endpoint. The tools themselves
run next to the data: semantic search embeds the query server-side, and
incident analysis fuses five separate lookups into one call. Keeping that
logic on the server means this package does not have to track the rollup
schema, and it means your own host model does the orchestration rather than a
model hard-coded here.

## Licence

MIT. Copyright Silicoyn Technologies Pvt Ltd.