#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 a 6-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 durable — re-download any time from any device by calling get_invoice.

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)

Fetches metadata + a fresh signed download URL for a previously generated invoice. Tenant-scoped — cross-tenant lookups return 404.

#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

#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 a 6-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

• Official MCP Registry (namespace causaprima) — remote MCP listing pointing at scribo.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 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.