#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.zipunder 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:
- Sender business name — legal entity name.
- Sender address — street (
address_line1),postcode,city,country_code(ISO 3166 alpha-2). - Sender tax / VAT ID + contact email — tax ID with country prefix (e.g.
DE123456788);contact_emaildoubles as the return-visit login. - Recipient name — legal entity name.
- Recipient address — street, postcode, city, country code. Add
leitweg_idif German federal B2G (auto-selects XRechnung UBL). - 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. - Line items + currency — per line: description, quantity, unit price, tax rate, tax category code. Currency is ISO 4217 (
EUR,USD, …).
Optional:
jurisdictionoverride,format_override,notes(≤ 1000 chars)idempotency_key— same key + same inputs returns the original invoiceverification_token— returned byverify_email_codepayment_means— SEPAibanor USaccount_number+routing_number(not both), plus optionalbic/account_name/bank; required with an IBAN for XRechnung (BR-DE-1)delivery_date/delivery_period— mutually exclusivelocale— 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 notax_id+tax_registration_id+ an exemptEline currently returnsunsupported_kleinunternehmer; prefertax_idwhen 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:
- Per-IP rate limit at the api/ — the scribo lambda extracts the end-user IP from the incoming request (
x-vercel-forwarded-foron Vercel previews, the second-from-rightmostx-forwarded-forentry on the GCP-LB-fronted production deploy) and stamps it asx-causa-client-ipon the upstream call withx-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. - Bridge secret — the hosted /mcp lambda holds
CORE_API_INTERNAL_SECRETserver-side and stamps it asx-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 leakedCORE_API_INTERNAL_SECRETbypasses 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
- Official MCP Registry (namespace
causaprima) — remote MCP listing pointing atscribo.causaprima.ai/mcp - Smithery — remote registration
- Glama and PulseMCP likewise
#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 intocurl.