Following system theme

#Scribo MCP Server

The official Scribo Model Context Protocol server is a hosted endpoint at:

https://scribo.causaprima.ai/mcp

It speaks MCP over Streamable HTTP with JSON-RPC 2.0. Any MCP-aware client — Claude Desktop, Cursor, Cline, ChatGPT App, OpenAI Codex CLI, Smithery's remote registry, your own client — can call it directly. No npm install, no local process to manage.

#Install

#Claude Desktop & Claude.ai (web)

In Claude Desktop or claude.ai, open Customize → Connectors, click the + next to Connectors, choose Add custom connector, and paste:

  • Name: Scribo
  • URL: https://scribo.causaprima.ai/mcp

Save. Scribo's four tools (create_invoice, verify_email_code, get_invoice, list_supported_jurisdictions) appear in the connector list for any new chat. Ask: "draft an invoice for 3 days of consulting at €1,200/day to Acme GmbH" — Scribo collects the missing fields, verifies the sender email, and returns a download link.

On Team/Enterprise plans, an org owner may need to add the connector once at Organization settings → Connectors before it shows up for members.

Skill alternative. Prefer a plain-bash setup without a JSON-RPC connector in the loop? Upload scribo-skill.zip under Settings → Customize → Skills instead — see the Skill guide. The same upload covers Claude.ai chat, Claude Desktop, and Cowork.

Alternative — config file (Claude Desktop only). Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or the equivalent on your OS:

{
  "mcpServers": {
    "scribo": {
      "transport": "http",
      "url": "https://scribo.causaprima.ai/mcp"
    }
  }
}

Restart Claude Desktop.

#Cursor

Add to ~/.cursor/mcp.json (or workspace .cursor/mcp.json):

{
  "mcpServers": {
    "scribo": {
      "url": "https://scribo.causaprima.ai/mcp"
    }
  }
}

#Cline

Add to ~/Library/Application Support/Cline/MCP/cline_mcp_settings.json (macOS):

{
  "mcpServers": {
    "scribo": {
      "transport": "streamable-http",
      "url": "https://scribo.causaprima.ai/mcp"
    }
  }
}

#OpenAI Codex CLI

Add to ~/.codex/config.toml (or .codex/config.toml in a trusted project):

[mcp_servers.scribo]
url = "https://scribo.causaprima.ai/mcp"

Restart Codex. Scribo's four tools (create_invoice, verify_email_code, get_invoice, list_supported_jurisdictions) become available in the session. Codex CLI only configures Streamable HTTP servers via config.toml — there is no codex mcp add equivalent for HTTP servers.

#Generic MCP client

Configure your client for a remote MCP server with:

  • URL — https://scribo.causaprima.ai/mcp
  • Transport — Streamable HTTP (MCP spec ≥ 2025-03-26; the older HTTP+SSE transport is not supported)
  • Auth — none

#Tools

#create_invoice(input)

Generates the invoice. The LLM collects seven required fields from the user:

  1. Sender business name — legal entity name.
  2. Sender address — street (address_line1), postcode, city, country_code (ISO 3166 alpha-2).
  3. Sender tax / VAT ID + contact email — tax ID with country prefix (e.g. DE123456788); contact_email doubles as the return-visit login.
  4. Recipient name — legal entity name.
  5. Recipient address — street, postcode, city, country code. Add leitweg_id if German federal B2G (auto-selects XRechnung UBL).
  6. Recipient email — recipient.contact_email. Required — Scribo refuses to draft without it. This is the accounts-payable / billing email; the address we deliver the invoice to and where the recipient's transparency / opt-out link is sent.
  7. Line items + currency — per line: description, quantity, unit price, tax rate, tax category code. Currency is ISO 4217 (EUR, USD, …).

Optional:

  • jurisdiction override, format_override, notes (≤ 1000 chars)
  • idempotency_key — same key + same inputs returns the original invoice
  • verification_token — returned by verify_email_code
  • payment_means — SEPA iban or US account_number + routing_number (not both), plus optional bic / account_name / bank; required with an IBAN for XRechnung (BR-DE-1)
  • delivery_date / delivery_period — mutually exclusive
  • locale — BCP-47; language of the verification + notification emails
  • sender contact_name / contact_phone — required for German XRechnung (BR-DE-5/6)
  • sender tax_registration_id — German Steuernummer; satisfies BR-CO-26 when there is no VAT ID, but the § 19 UStG shape of no tax_id + tax_registration_id + an exempt E line currently returns unsupported_kleinunternehmer; prefer tax_id when the seller has one

If the sender email has not been verified yet, returns a structured verification_required error with { challenge_id, email_hint, next_tool: "verify_email_code" } and sends a verification email containing an 8-character code. Ask the user to paste the code, call verify_email_code({ challenge_id, code }), then retry create_invoice with the same arguments plus the returned verification_token. The hosted endpoint is stateless, so the token must be passed back in the retry.

Rate-limit and block failures are returned as structured tool errors, not JSON-RPC transport failures. The error object includes code, http_status, any retry_after_seconds / reset_at metadata, and a short hint. Tenant quota errors use tenant_invoice_quota_exceeded; repeated tenant hard-limit hits return tenant_soft_blocked until details.auto_lift_at.

After verification succeeds, returns { invoice_id, document_id, format, download_url, download_url_expires_at, validator_summary, magic_link_sent } — plus, for XRechnung outputs only, preview_url / preview_url_expires_at (human-readable PDF rendering of the XML) and a submission object with manual-upload hints for the German B2G portals. The download URL is signed and expires 15 minutes later (download_url_expires_at); the copy in the sender's confirmation email lasts 30 days. Call get_invoice for a fresh one.

The output format is picked from the priority chain described in /docs/jurisdictions.

#verify_email_code({ challenge_id, code })

Redeems the code from the verification email and returns { ok, verification_token, expires_at }. Pass that verification_token into create_invoice when retrying the invoice request, and keep threading the same token into later create_invoice calls for the same sender email until it expires.

#get_invoice(invoice_id, verification_token?, sender_email?)

Fetches metadata and a fresh signed download URL (valid 15 minutes) for an invoice the caller sent. It needs the sender's verification: the session's cached token, a verification_token, or, with sender_email, a new verification code exactly as create_invoice sends one. Another sender's invoice and an unknown ID both return not found, and so do invoices created inside the Causa Prima app, which are served only there behind its sign-in.

#list_supported_jurisdictions()

Returns [{ jurisdiction, formats, default_format }].

#Prompts

The server also registers five MCP workflow prompts (prompts/list / prompts/get) — clients that surface prompts show them as slash-command-style starters:

generate_invoice (guided field collection), german_b2b_invoice (ZUGFeRD), german_b2g_xrechnung (Leitweg-ID + payment details), us_plain_pdf_invoice, and redownload_invoice. All are localized; each walks the model through the required fields and the verification flow.

#Widget

create_invoice returns an inline invoice-card widget resource (per the OpenAI Apps SDK widget protocol). MCP clients that render widgets — currently the ChatGPT App and any other Apps-SDK-aware host — display the generated invoice as a card with sender, recipient, totals, format badge, and a download button. Clients that don't render widgets still receive the structured JSON response.

#Format coverage

Jurisdiction Default format Notes
Germany (B2B) ZUGFeRD COMFORT PDF/A-3 hybrid with embedded EN 16931 CII XML. zugferd_basic available via format_override.
Germany (B2G) XRechnung UBL Auto-selected when recipient.leitweg_id is set. xrechnung_cii available via format_override if your Invopop dashboard has a CII workflow provisioned.
United States Plain PDF No XML, no compliance friction. Renders payment details (IBAN or US account + ABA routing) when payment_means is supplied.
France Factur-X Phase 2 — coming soon.
Spain Facturae Phase 2 — coming soon.
Belgium / NL / LU / AT Peppol BIS 3.0 UBL Phase 2 — coming soon.

#Account model

Your sender.contact_email is the login identifier across Scribo surfaces. Before the first invoice for that email is generated through MCP, Scribo sends a verification email with both a web link and an 8-character code. MCP clients use the code path: create_invoice → verification_required → verify_email_code → retry create_invoice with verification_token. The web link is for browser-based verification at scribo.causaprima.ai.

Same email across MCP, CLI, Skill, and Web → same account.

#Security model

scribo.causaprima.ai/mcp is an open Streamable HTTP endpoint — anyone on the internet can POST a JSON-RPC payload. Two gates sit between that and the core-api:

  1. Per-IP rate limit at the api/ — the scribo lambda extracts the end-user IP from the incoming request (x-vercel-forwarded-for on Vercel previews, the second-from-rightmost x-forwarded-for entry on the GCP-LB-fronted production deploy) and stamps it as x-causa-client-ip on the upstream call with x-causa-client-ip-relay-secret. The api/ only trusts that header when the relay secret matches; otherwise it derives IP from the public request. Abuse is bucketed against the end user, not the scribo lambda's egress IP.
  2. Bridge secret — the hosted /mcp lambda holds CORE_API_INTERNAL_SECRET server-side and stamps it as x-causa-internal-secret. The api/'s /internal/scribo/* controller verifies (timing-safe) before doing anything else; an external caller hitting api.causaprima.ai directly cannot forge it. A leaked CORE_API_INTERNAL_SECRET bypasses the api/'s bridge-secret gate for the entire /internal/scribo/* surface. The secret is stored as a per-project Vercel env (scribo project) and replicated into the staging/production GKE namespaces via Secret Manager. Rotate quarterly at minimum; rotate immediately on any suspected leak, departing-engineer access, or CI/lambda env exfil.

#Privacy

Sender, recipient, and invoice content flow through Invopop (Madrid) for generation. Web-chat traffic additionally flows through Anthropic via the Vercel AI Gateway. Both have DPAs; both are listed on /compliance.

#Listings

#Machine-readable metadata

Public registry-facing assets for the Scribo MCP server live at github.com/causa-prima-ai/scribo-mcp:

  • server.json — MCP Registry metadata.
  • schemas/ — JSON Schema (Draft 2020-12) for each tool's input.
  • examples/ — sample JSON-RPC 2.0 tool-call payloads you can pipe straight into curl.

#See also

  • Skill — bash + curl + jq alternative for Claude Code / OpenAI Codex sessions; calls /api/v1/* directly.
  • CLI — npm package for terminal / CI use; calls /api/v1/* directly.
  • API — the underlying HTTP contract every Scribo surface shares.