envbert-mcp

MCP server exposing raw envbert (DistilBERT EDD classification) to Claude — standalone.

This server calls envbert.due_diligence.envbert_predict() directly.

If you need the LLM-fallback behaviour (e.g. building a non-LLM pipeline), use envbert-agent.

Architecture

Claude / Claude Code
        │ MCP (stdio)
        ▼
envbert_mcp/server.py     ←── this file, single process
        │ in-process call
        ▼
envbert.due_diligence.envbert_predict()
        │
        ▼
DistilBERT (d4data/environmental-due-diligence-model)

Everything runs in one process. The model loads once at startup (warmup, ~10-40s on a cold HuggingFace cache) and stays in memory for the life of the server.

Tools

Note on confidence: this is a cosine similarity between the input text and a reference embedding for the predicted category — not a calibrated probability. It's a useful relative signal (higher = closer match) but shouldn't be read as "X% likely correct." Scores at or below 0.3 are already relabeled Not Relevant internally before they reach you. Every response also includes a score_basis field as a reminder.

Why low-confidence flagging matters here

Without an LLM fallback, a low envbert confidence score (e.g. 0.42) is the final answer — there's no second opinion baked in. classify_environmental_document surfaces a low_confidence_items list explicitly so Claude can apply its own judgement to exactly those paragraphs, rather than treating every result as equally reliable.

Note that confidence here is a cosine similarity to a reference embedding, not a calibrated probability — see the caveat under Tools above.

{
  "category_distribution": {"Geology": 4, "Contaminants": 2},
  "score_basis": "cosine_similarity_not_probability",
  "low_confidence_count": 1,
  "low_confidence_items": [
    {"index": 3, "label": "Remediation Standards", "confidence": 0.42}
  ],
  "results": [ ... ]
}

Quickstart

pip install envbert envbert-mcp

Register the server with Claude Code:

claude mcp add envbert -- envbert-mcp

(Add --scope user instead of the default local scope if you want it available in every project, not just the one you ran this from.)

Restart Claude Code. The model warms up in the background on first launch — check_envbert_status will report "loading": true until ready.

Example prompts:

• "Is envbert ready?"
• "Classify this: 'weathered shale was encountered below the surface with fluvial deposits'"
• "Here's a 12-paragraph site report — classify each section and flag anything you're not confident about."

envbert-mcp vs envbert-agent which to use

Both are legitimate — they're solving for different consumers of the classification, not competing implementations of the same thing.

Configuration

No other configuration needed — there's no backend URL, no LLM provider, no API keys. That's the point.

License

MIT