Optional invinoveritas /review MCP server for second-opinion verdicts in the guard pipeline

[babyblueviper1]

TL;DR

The guard pipeline currently runs deterministic checks (size, cooldown, whitelist) before order push. I've been building a Lightning-paid MCP server that adds a structured LLM second-opinion verdict on the same proposal — verdict types approve | approve_with_concerns | reject with ranked issues and confidence score. Wanted to surface it as a drop-in .mcp.json entry since the integration shape happens to fit your existing template format exactly.

Edit 2026-05-22: corrected the cost-shape section and softened the "capital-scale-aware" claim — include_trading_state is exposed on the MCP review tool but is a no-op for accounts without a registered internal trading state (so it's mostly a future hook, not the current external value prop).

Why this might slot in

Your mcp.json templates already speak streamable-http and the workspaces UI lets users enable/disable MCP servers without code changes. The verdict tool is a single new entry. The review MCP tool takes an artifact (a trade proposal, plan, config change, or arbitrary string), an artifact_type enum, optional context and concerns strings, and returns a structured {verdict, confidence, issues[]} JSON.

This is meant to complement the existing guard pipeline (which catches the structural violations cleanly) by adding a slower, paid, model-graded check on the agent's reasoning itself — not to replace any of the local rules.

Drop-in .mcp.json entry

{
  "mcpServers": {
    "invinoveritas": {
      "type": "streamable-http",
      "url": "https://api.babyblueviper.com/mcp",
      "headers": {
        "Authorization": "Bearer ${INVINOVERITAS_KEY}"
      }
    }
  }
}

The Claude Agent SDK path you ship by default picks this up without any code changes. Vercel AI SDK users hit it via their existing MCP client.

Cost shape (honest)

• POST /register (free): returns a Bearer token + 250 non-withdrawable starter sats.
• /review MCP tool: ~260 sats minimum per call (1 sat / 100 chars on top of base).
• The 250 starter sats are enough for one /reason (~100 sats) but not one /review. To actually try /review you'd need to top up ~1k sats via Lightning (POST /topup returns a bolt11 invoice).
• Auth: Bearer (recommended for an agent loop) or L402 (one-shot pay-per-call).

On license

The MCP server is hosted infrastructure, so users adding the .mcp.json entry pull in zero new code into your tree — no AGPL implications. If anyone later wanted a native TS helper that wraps the verdict in your decision model, I'd ship that as a separate package rather than upstreaming into core, to keep your AGPL boundary clean.

Maintainer questions

1. Is there an existing convention for "optional paid tool" entries — separate workspace template, env-gated entry, or just listed alongside openalice/openalice-workspace?
2. Anyone running a paper-trading loop right now who'd want to feed a few historical trader-agent proposals through and compare verdicts?
3. Would a short docs note (e.g. docs/optional-tools/invinoveritas.md) be welcomed as a follow-up PR, or do you prefer external docs?

Happy to iterate the framing either way. The server is up and accepting calls now; if anyone wants to try it the /register flow is one POST.

---

References:

• Server card: https://api.babyblueviper.com/.well-known/mcp/server-card.json
• Endpoint docs: https://api.babyblueviper.com/docs
• SDK (Python helpers; not required for MCP use, Apache-2.0): https://github.com/babyblueviper1/invinoveritas-sdk

[Chris79OG]

I checked the current template shape and a docs-first PR looks like the lowest-risk path:

• add docs/optional-tools/invinoveritas.md
• keep the stock chat / finance-research mcp.json files unchanged unless maintainers want optional paid tools discoverable in templates
• frame /review as advisory only, with OpenAlice's deterministic guard pipeline still authoritative for execution safety
• include the exact env-based MCP entry and a no-secrets acceptance checklist

If that direction is welcome, I can open a small docs PR first. A template patch can be a separate follow-up so the optional paid-tool boundary stays explicit.

[babyblueviper1]

Thanks @Chris79OG — that direction works for me, and the advisory-only framing is exactly the boundary I'd want too. OpenAlice's deterministic guard pipeline stays authoritative for execution safety; /review only adds a structured second-opinion before the irreversible step, never replacing the guards.

If a docs-first PR is welcome, here's what I can hand over as ready-to-paste content for docs/optional-tools/invinoveritas.md:

• The exact env-based MCP entry (Bearer token via INVINOVERITAS_KEY env, no secrets in mcp.json)
• No-secrets acceptance checklist (no telemetry, no required signup, MIT-compatible endpoint, opt-in only)
• Honest pricing footnote: ~390 sats per /review/external call; /register returns 250 starter sats (free) which do NOT cover a single review call by design — top up via Lightning to evaluate against a live trade
• Explicit "advisory only" disclaimer with a code example showing the deterministic guards still gating execution after the verdict returns

Happy to draft it as a comment here for you to lift into the PR, or open the docs PR myself with you tagged for review — whichever is lower-friction for the maintainers. Thanks again for the path forward.

[babyblueviper1]

Thanks @Chris79OG — I appreciate your readiness to move forward. I can provide the exact content for docs/optional-tools/invinoveritas.md, including the env-based MCP entry and the no-secrets acceptance checklist. This will clarify that /review is advisory and keeps OpenAlice's deterministic guard pipeline as the authoritative layer for execution safety. Our live bot passes every entry through this review process, ensuring it aligns with our intended safety measures.

Regarding the next steps, I can either draft the content here for you to lift into the PR, or I can open the docs PR with you tagged for review. Let me know which option works best for you.

(docs + pricing below)

Here's the ready-to-paste content for docs/optional-tools/invinoveritas.md (advisory only — OpenAlice's deterministic guard pipeline stays authoritative for execution):

# Optional tool: invinoveritas /review (advisory second opinion)

**What it is.** An optional, paid MCP server that returns a capital-scale-aware
second-opinion *verdict* on a proposed trade (or any irreversible action) before
OpenAlice commits it. It is **advisory only** — OpenAlice's deterministic guard
pipeline (size / cooldown / whitelist) remains authoritative for execution safety.
`/review` never executes, cancels, or blocks; it returns a verdict your code can log
or weigh, then your guards decide.

**Why it differs from a local guard.** Local rules check thresholds; `/review` gives
an LLM-graded risk read the rules can't: is the position size sane vs current equity,
how close is this to tripping a drawdown breaker, is the signal's regime durable or a
fakeout, is the edge fee-adjusted positive. Verdict is one of
`approve` / `approve_with_concerns` / `reject` with ranked issues + a confidence score.

**Setup (no secrets in `mcp.json`).** Add the server with the Bearer token via env:

```json
{
  "mcpServers": {
    "invinoveritas": {
      "type": "streamable-http",
      "url": "https://api.babyblueviper.com/mcp",
      "headers": { "Authorization": "Bearer ${INVINOVERITAS_KEY}" }
    }
  }
}
```

Then `export INVINOVERITAS_KEY=ivv_...` in your environment.

**No-secrets acceptance checklist.**
- [ ] No token committed — `INVINOVERITAS_KEY` is read from env only.
- [ ] Opt-in: the server is absent unless a user adds this entry.
- [ ] Advisory: execution safety stays with OpenAlice's guard pipeline; `/review` output is logged/weighed, never authoritative.
- [ ] No telemetry required; no required signup to call (Bearer or L402).

**Advisory usage (guards stay authoritative).**
```ts
// after the strategy produces a candidate order, before execution:
const verdict = await invinoveritas.review({
  artifact: JSON.stringify(candidateOrder),
  artifact_type: "plan",
  context: `equity=${equity} openPositions=${positions.length} regime=${regime}`,
  severity_threshold: "high",
});
logger.info("invinoveritas advisory", verdict.verdict, verdict.confidence, verdict.issues);

// OpenAlice's deterministic guards remain the ONLY gate on execution:
if (!guardPipeline.allows(candidateOrder)) return;       // authoritative
if (verdict.verdict === "reject") return requireHumanAck(candidateOrder, verdict);
execute(candidateOrder);
```

Pricing/onboarding (corrected from my earlier comment in this thread): registration is free and returns an api_key with no starter balance — we removed the old starter-sats grant. /review is 200 sats/call (Bearer); /review/external is 300 sats. To evaluate /review against a live trade with zero spend, I can send a one-time 500-sat first-call grant (non-withdrawable) — just say the word and I'll DM it (kept out of this thread so it isn't grabbed by a passerby). After that, top up via Lightning or USDC (x402).

Happy to open the docs PR myself with you tagged for review, or you lift this in — whichever's lower-friction for the maintainers.

[babyblueviper1]

Thanks @Chris79OG — appreciate you offering to move this forward. Happy to make it turnkey: I can drop the exact content for docs/optional-tools/invinoveritas.md right here for you to lift into the PR, or open the PR myself with you tagged for review — whichever is less work for you.

To keep it aligned with how you framed it: /review stays strictly advisory — OpenAlice's deterministic guard pipeline remains the authoritative execution-safety layer. The doc would cover the env-based MCP entry, a no-secrets acceptance checklist, an honest pricing footnote, and an advisory-only disclaimer with a short code example.

Timely context, not a pitch: Robinhood just opened agentic trading to MCP agents this week — orders can fire without per-trade confirmation — and they themselves flagged liability for agent decisions as the open question. That's exactly why an advisory pre-trade second-opinion is worth having as an optional tool: the agent calls /review on a proposed order and gets an approve / approve_with_concerns / reject with ranked issues before anything executes. Same pattern, drop-in recipe if it's useful as a reference: https://github.com/babyblueviper1/invinoveritas/tree/main/integrations/robinhood

Just say which path you prefer and I'll get the content over.