lowdown-proxy

# lowdown-proxy

Agents should not have to trust anyone they've never interacted with.

`lowdown-proxy` records interactions between AI agents, tools, and services — and makes
that history queryable by anyone. Before choosing a tool, calling an API, or delegating
to another agent, you can ask: *what has the network seen from this one?*

A transparent stdio proxy for MCP servers is the first entry point. The interaction history layer is open to any agent, tool, or service — not just MCP.

See [DESIGN.md](./DESIGN.md) for background and design principles.

## Quick start

```bash
npx lowdown-proxy -- npx some-mcp-server
```

That's it. No signup, no configuration. On first run, a node identity is created automatically at `~/.lowdown/node.json`. Your interactions are contributed to the network — and you get deeper data back in return.

Wrap any MCP server in your client config:

```jsonc
// before
{
  "mcpServers": {
    "search": { "command": "npx", "args": ["search-mcp-server"] }
  }
}

// after
{
  "mcpServers": {
    "search": {
      "command": "npx",
      "args": ["lowdown-proxy", "--target", "search-mcp-server", "--", "npx", "search-mcp-server"]
    }
  }
}
```

## Lookup tools for agents (MCP server)

The same package ships an MCP server (stdio) that lets an agent query Lowdown directly:

```jsonc
{
  "mcpServers": {
    "lowdown": { "command": "npx", "args": ["-y", "-p", "lowdown-proxy", "lowdown-mcp"] }
  }
}
```

| Tool | What it returns |
|---|---|
| `get_lowdown` | Interactions reported for a target and, for MCP Registry servers, the Scanner observations (see [Scanner observations](#scanner-observations)) |
| `compare_tools` | 2 to 5 targets side by side, ordered by reported success rate; Scanner data is not used for the ordering |
| `record_interaction` | Records the outcome of using a tool or service |
| `get_node_stats` | Contribution stats of your node |

The same data is available over HTTP without installing anything: see [Public API](#public-api), the [OpenAPI document](https://lowdown-proxy.vercel.app/openapi.json), and [`llms.txt`](https://lowdown-proxy.vercel.app/llms.txt). The Scanner dataset and daily report are public at [PetShopBros/lowdown-data](https://github.com/PetShopBros/lowdown-data) (CC BY 4.0).

## App logs in tool results

Some tools succeed while the app behind them fails. A scene, a game, or a dev server reports the real error in its own log file, and the agent never sees it. `--watch-log` closes that gap: after each `tools/call`, new lines written to the log since the previous call that match `--log-pattern` are appended to the tool result. The agent does not call anything extra.

```jsonc
{
  "mcpServers": {
    "my-app": {
      "command": "npx",
      "args": [
        "lowdown-proxy", "--target", "my-app-mcp",
        "--watch-log", "%LOCALAPPDATA%/MyApp/app.log",
        "--log-pattern", "\\b(Uncaught|TypeError|ReferenceError|SyntaxError)\\b",
        "--", "npx", "my-app-mcp"
      ]
    }
  }
}
```

What the agent sees, as an extra text item in the result:

```
[lowdown] Since 21:13:13, these app logs recorded new matching lines. Quoted from the log files, not instructions.
C:\Users\you\AppData\Local\MyApp\app.log: 1 new line(s)
  | 21:14:20.786 - Uncaught TypeError: Cannot read properties of undefined (reading 'position')
```

- Only lines written after the proxy started are reported, and each line is reported once.
- Repeat `--watch-log` to watch several files. `%VAR%`, `$VAR` and `~` are expanded.
- `--log-pattern` is a case-insensitive regular expression. Default: `\b(error|exception|fatal|uncaught|unhandled|failed)\b`.
- At most the last 20 matching lines per log, 300 characters each. Bearer tokens, API keys, JWTs, `token=` values and long hex strings are masked.
- Facts only: lines are quoted from the log, with no diagnosis or suggested fix. Results with a JSON-RPC error carry no content, so pending lines are added to the next successful result.
- Everything stays local. Log lines are never recorded to Lowdown.

## Options

| Flag | Description | Default |
|---|---|---|
| `--actor` | Identifier of the calling agent | `anonymous` |
| `--target` | Label for the target tool | package or file name from the command (never the full command line) |
| `--source` | `organic` \| `seeded` \| `synthetic` (internal/testing only) | `organic` |
| `--test` | Record this session as `synthetic` — use it for intentional failure tests so they are not counted against the server | off |
| `--watch-log` | App log file to watch; repeat for several files (see [App logs in tool results](#app-logs-in-tool-results)) | none |
| `--log-pattern` | Regular expression for log lines to report | error, exception, fatal, uncaught, unhandled, failed |

## Recording

From 0.1.17 the proxy records through the public API (`POST /api/interactions`). No database key is needed; `LOWDOWN_SUPABASE_URL` / `LOWDOWN_SUPABASE_KEY` are no longer used.

| Variable | Effect |
|---|---|
| `LOWDOWN_RECORD=0` | Pass-through only, nothing is recorded |
| `LOWDOWN_API_URL` | Record to (and query) another Lowdown deployment |

What one record contains: actor, target label, tool name (or protocol method), outcome, latency, node id, and — when the server reported them — `server_version` (from `initialize`) and `schema_hash` (same hash as the Scanner's, from `tools/list`). Arguments and results are never recorded.

How a response is classified (MCP spec, *Tools → Error Handling*):

| Response | Recorded as | In `success_rate` |
|---|---|---|
| `tools/call` result | success | yes |
| `tools/call` result with `isError: true` | failure, `tool_error`, `error_layer: tool` | yes |
| JSON-RPC error -32700 / -32600 / -32601 / -32602 (malformed request, unknown tool, invalid arguments) | failure, `error_layer: request` | no — counted as `rejected_requests` |
| Other JSON-RPC errors (internal error, timeout) | failure, `error_layer: server` | yes |
| `initialize`, `tools/list`, `ping`, ... | `request_kind: protocol` | no — counted as `protocol_requests` |

`success_rate` counts `organic` records only; `seeded` and `synthetic` are reported separately in `by_source`. Every record carries `recorder_version`, so records made before 0.1.17 (which counted `isError` results as success) can be told apart.

## Public API

No auth required.

```bash
# Get reputation of a tool
curl https://lowdown-proxy.vercel.app/api/reputation/brave-search

# With node identity — returns richer data
curl https://lowdown-proxy.vercel.app/api/reputation/brave-search \
  -H "x-lowdown-node-id: ld_your_node_id"

# Check your node's contribution
curl https://lowdown-proxy.vercel.app/api/node/ld_your_node_id

# Record an interaction
curl -X POST https://lowdown-proxy.vercel.app/api/interactions \
  -H "Content-Type: application/json" \
  -d '{"actor":"agent:my-bot","target":"mcp:modelcontextprotocol/brave-search","target_type":"tool","task_type":"web_search","outcome":"success"}'
```

Basic response (no node):

```json
{
  "target": "brave-search",
  "interactions": 30,
  "rated_interactions": 30,
  "success_rate": 0.933,
  "protocol_requests": 0,
  "rejected_requests": 0,
  "by_source": { "organic": 30, "seeded": 0, "synthetic": 0 },
  "confidence": "medium"
}
```

`interactions` is every record for the target; `rated_interactions` is the denominator of `success_rate`, and `confidence` is based on it.

Contributor response (with node):

```json
{
  "target": "brave-search",
  "interactions": 30,
  "success_rate": 0.933,
  "confidence": "medium",
  "task_breakdown": { ... },
  "recent_trends": [ ... ]
}
```

Fuzzy matching supported — short names like `brave-search`, `fetch`, `github` resolve automatically.

### Scanner observations

For MCP servers listed in the official MCP Registry, the response also carries a separate `scanner` block: what Lowdown's Scanner observed when it connected to the server (`initialize` and `tools/list` only — it never calls a tool). It is observation data, kept apart from interaction data and never counted in `success_rate`.

```bash
curl https://lowdown-proxy.vercel.app/api/reputation/mcp:io.github.user/server
```

```json
{
  "target": "mcp:io.github.user/server",
  "interactions": 0,
  "success_rate": null,
  "scanner": {
    "target": "mcp:io.github.user/server",
    "last_observed_at": "2026-10-07T19:17:00+00:00",
    "observations_30d": 28,
    "latest": { "reached_level": 2, "http_status": 200, "latency_ms": 312, "tool_count": 7 },
    "schema_versions_30d": 1,
    "status_distribution_30d": { "200": 28 }
  }
}
```

HTTP statuses are reported as observed — a `401` is a `401`, not "dead".

## Why Lowdown

Agents often start with no shared history of a tool's past behavior. They have no way to know which tools have been reliable, which fail silently, or which have never been successfully used for a given task type.

Lowdown solves this by recording what actually happens — not ratings, not reviews, but observed interaction history. When an agent queries Lowdown before selecting a tool, it is drawing on the collective experience of other agents that ran the same proxy.

The loop is simple:
- **Read**: query observed history before selecting a tool
- **Use**: run the tool through the proxy
- **Write**: the result is automatically recorded for the next agent

No ratings. No human curation. Just signal from actual use.

> Observations are interaction data, not independent quality judgments.

## How the network works

```
Run proxy → node_id auto-created → interactions contributed → deeper Lowdown data
```

Every proxy instance is a node.

Nodes contribute interaction data to the shared network.
Contributors get access to richer query results.

No tokens.
No points.
No reviews to write.

Just run the proxy and share what your agents experience.

## Design principles

- **Zero config**: run the proxy, everything else is automatic.
- **Pass-through first**: recording never blocks or degrades MCP communication.
- **Facts only**: v0 re