# anvaiops-mcp

**Give any AI agent operational memory.** An [MCP](https://modelcontextprotocol.io) server that
connects Claude (Desktop, Code), and any other MCP client, to
[AnvaiOps](https://anvaiops.com) — the memory layer for AI agents and the teams they work with.

Agents search past incidents, fixes, and decisions **with provenance** (source, team, resolution
time, RCA), and persist what they learn back into shared memory.

> *"Your next answer may already exist."*

## Verified end-to-end

Every claim on this page is backed by a reproducible session: [`demo/transcript.md`](demo/transcript.md)
shows a real agent search (31 ms, provenance included), a memory write, and a **later session
finding that agent-written memory ranked #1**. `demo/e2e.js` re-runs the whole chain with
PASS/FAIL assertions — `npm run demo:e2e` against any deployment.

## Tools

| Tool | Status | What it does |
|------|--------|--------------|
| `memory_search` | stable | Hybrid semantic search over incidents/runbooks/decisions. Results carry RCA, fix, team, resolution time, source URL, and score. |
| `memory_write` | **experimental** | Persist a memory (async ingest): what happened, how it was fixed, decision + rationale. Attributed `recorded_by=anvaiops-mcp`. |
| `memory_status` | stable | Deployment reachability/version probe. |

Status labels follow the AnvaiOps ADR-0014 discipline — no tool claims more than it delivers.

## Install

Works today straight from GitHub (the `prepare` script builds on first use; npm package pending):

```json
"command": "npx", "args": ["-y", "github:anvai-labs/anvaiops-mcp"]
```

### Claude Desktop

Add to `claude_desktop_config.json` (macOS:
`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "anvaiops": {
      "command": "npx",
      "args": ["-y", "anvaiops-mcp"],
      "env": {
        "ANVAIOPS_API_KEY": "your-key",
        "ANVAIOPS_URL": "https://anvaiops.com"
      }
    }
  }
}
```

### Claude Code

```bash
claude mcp add anvaiops -- npx -y anvaiops-mcp
export ANVAIOPS_API_KEY=your-key   # or put it in the server env
```

### Self-hosted

Point at your own deployment (the same server works against any AnvaiOps install):

```json
{ "ANVAIOPS_URL": "http://localhost:8000", "ANVAIOPS_API_KEY": "local-key" }
```

## Configuration

| Env var | Default | Meaning |
|---------|---------|---------|
| `ANVAIOPS_API_KEY` | — (required) | Tenant key; sent as `X-API-Key` |
| `ANVAIOPS_URL` | `https://anvaiops.com` | API base URL (hosted beta or self-hosted) |
| `ANVAIOPS_TIMEOUT_MS` | `15000` | Per-request timeout |
| `ANVAIOPS_DEFAULT_DAYS` | `365` | memory_search lookback window |
| `ANVAIOPS_DEFAULT_LIMIT` | `10` | memory_search page size (max 50) |

Get a hosted key from the [AnvaiOps console](https://anvaiops.com) — or run your own; the memory
core is open source on [ProximaDB](https://github.com/anvai-labs/proximaDB).

## Why an MCP server for memory?

Every team deploying agents rediscovers the same wall: retrieval is getting cheap, but **re-deriving
what the organization already knew never gets cheap**. The same incident gets debugged three times
because the answer lives in a Slack thread from March.

AnvaiOps indexes tickets, Slack threads, runbooks, post-mortems, and release notes — then surfaces
the historical fix, with provenance, the moment it's relevant. This server makes that memory
available to *any* agent, in the tool layer, where agents already work.

Design notes:

- **Provenance is not optional.** Every search result carries its source, team, and timestamps — a
  memory without provenance is a liability.
- **Writes are attributed and bounded.** 1–25 records per call, async ingest, tagged
  `recorded_by` — so agent-written memory stays auditable.
- **Zero runtime dependencies.** Hand-rolled MCP stdio (JSON-RPC 2.0, protocol `2024-11-05` →
  `2025-06-18`), global `fetch`. Small supply-chain surface, Node ≥ 18.

## Development

```bash
npm install        # dev-only deps (typescript, @types/node)
npm run build
npm test           # node:test unit suite (no network)
npm run smoke      # stdio handshake + tools/list against the built binary
```

## License

Apache-2.0 — © AnvaiOps. An [Anvai Labs](https://github.com/anvai-labs) project.