veris
· npx -y veris-mcp
Provenance-first web access for AI agents. Clean content plus verifiable source metadata, in one call.
Today an AI agent reading the web gets a wall of text. It does not get: when the page was published, whether the content changed since last time, who wrote it, the canonical source, or the license terms. veris attaches all of that to every read.
web_read("https://example.com/article")
→ clean markdown
+ { publishedAt, modifiedAt, author, canonicalUrl, contentHash, license, fetchedAt }
That metadata is not a nice-to-have. It is the foundation the rest of the AI-web economy needs: freshness, change-detection, citation, and — eventually — paying the people who wrote the content.
Why this exists
The web is being scraped by AI with no attribution and no payment. Publishers are responding by blocking bots and locking content. AI gets worse; publishers lose. The fix is a layer between agents and publishers that reads cleanly, tracks provenance, and (later) settles payment.
veris is the agent-side of that layer — the SDK every agent imports to consume the web responsibly. Think "Plaid for the AI web": you don't own the publishers, you own the integration developers reach for.
Roadmap (one codebase, three stages)
| Stage | What | Status |
|---|
| 1. Clean + provenance | search / read / research with verifiable source metadata | ✅ |
| 2. Finance vertical | SEC EDGAR filings with authoritative, official provenance | ✅ |
| 3. Settlement | license-aware access + micropayment + attribution | 🔜 seams in policy.ts + cache.ts |
The Stage 3 seams already exist in the code (policy.ts, cache.ts) so growth is additive, not a rewrite.
Tools
Web
| Tool | Does |
|---|
web_search(query, n?) | Ranked results as structured JSON. Brave (with key) or keyless DuckDuckGo. |
web_read(url, fresh?) | URL → clean markdown + provenance block. 24h cache. |
web_research(query, n?) | Search + read top N + bundle with per-source citations. |
Finance — SEC EDGAR (free, official, no API key)
| Tool | Does |
|---|
finance_filings(query, formType?, limit?) | Ticker / name / CIK → recent SEC filings: form, official filing & report dates, accession, direct document URL. |
finance_filing_read(url or query, formType?) | Read a filing by URL, or auto-read the latest matching form for a company. Clean text + provenance. |
finance_financials(query) | Revenue, net income, total assets, cash, diluted EPS from SEC XBRL — each figure stamped with the exact filing it came from. |
Why EDGAR first? Filings carry authoritative dates and identifiers straight from the SEC — provenance isn't guessed, it's official. Free, structured, no auth. One call gets an agent the latest 10-K with a verifiable source:
finance_filing_read({ query: "NVDA", formType: "10-K" })
→ NVIDIA CORP — 10-K (filed 2026-02-25)
clean text + { source, filed date, contentHash, wordCount }
Watch — change detection & alerts
| Tool | Does |
|---|
watch_manage(action, target?, formType?) | Add/remove/list watches: a company's SEC filings (ticker + optional form like 8-K) or any URL (content-hash watch). |
watch_check() | Check all watches; returns only what's NEW (new filings / changed pages) and rolls baselines forward. Run it on a schedule → alert feed. |
Install
npx -y veris-mcp # zero-install, always latest
Or from source:
git clone https://github.com/jakeyoung1/veris && cd veris
npm install && npm run build
Optional env:
export BRAVE_API_KEY=your_key # better search; https://search.brave.com/app/keys
export SEC_USER_AGENT="Your Name you@email.com" # SEC fair-access policy (recommended)
Without a Brave key, search falls back to keyless DuckDuckGo automatically. SEC requires a
Name email@domain style User-Agent — veris ships a default, but set your own contact.
Use in Claude Code
Add to your MCP config (.mcp.json):
{
"mcpServers": {
"veris": {
"command": "npx",
"args": ["-y", "veris-mcp"],
"env": { "BRAVE_API_KEY": "optional", "SEC_USER_AGENT": "Your Name you@email.com" }
}
}
}
Restart Claude Code, then ask it to web_research something.
Remote server (HTTP)
Run veris as a remote MCP server (Streamable HTTP) and connect from any MCP client by URL:
npx -y veris-mcp http # http://127.0.0.1:8787/mcp
VERIS_HTTP_HOST=0.0.0.0 npx -y veris-mcp http # expose it (put TLS in front)
| Env | Does |
|---|
VERIS_PORT / PORT | Port (default 8787) |
VERIS_HTTP_HOST | Bind host (default 127.0.0.1) |
VERIS_API_KEYS | Comma-separated keys. If set, /mcp requires Authorization: Bearer <key> (or x-api-key). Unset = open. |
VERIS_RATE_LIMIT | Requests/min/IP (default 60) |
Self-hosting is free, forever. VERIS_API_KEYS exists so a hosted instance can be metered.
Docker
docker build -t veris .
docker run -p 8787:8787 veris
Works as-is on Fly.io / Render / Railway — anything that runs a Dockerfile.
Design notes
- Provenance from raw HTML. We fetch the page ourselves and pull dates/author/canonical from
<meta>, JSON-LD, and Open Graph before readability strips them.
- Content hash. sha256 of extracted text — detects whether a page changed and enables dedupe across agents (the basis for a shared web index).
- Provider interface. Swap search backends without touching tool code.
- Cache → ledger. The same keyed store that caches reads today records read events for settlement tomorrow.
License
MIT
