How to connect Lumin PDF MCP with Codex

Return profile information for the currently authenticated Lumin user (the identity bound to this MCP session / integration). Call this first to confirm who the agent is acting as and to debug auth failures. Accepts no arguments and never queries other users. Returns: { user: { id, name, email } }. Next: get_workspace_info. For long-form rules, fetch the lumin://docs/auth resource.

Return metadata for the current Lumin workspace (id, name, owner, your role, member and space counts). Call before upload_file_to_lumin, lumin_post_agreement, or any listing tool that needs a location scope, so the agent can populate location.type / space_id correctly. For long-form rules, fetch the lumin://docs/auth resource.

Create or ingest a document in Lumin. Two mutually-exclusive branches selected by method: - 'file-upload' — provide a hosted document_data.file_url (HTTPS, downloadable). Supported types: PDF, DOCX, XLSX, PPTX, DOC, XLS, PNG, JPEG. Size limits: 20 MB (free) / 200 MB (paid). - 'template' — provide a document_data.template_id that must start with 'pdf_'. AgreementGen (ag_) and Sign templates are rejected with 400 invalid_argument — use lumin_generate_document_from_template or lumin_post_agreement for those. Location: location.type is 'personal' / 'space' / 'workspace'; space_id is required when type = 'space'; optional folder_id. Next: lumin_send_signature_request_from_file or a template-based send/generate tool. For long-form rules, fetch the lumin://docs/auth resource.

Retrieve a Lumin document by its ID, including its name, preview URL, and MIME type. Use after upload_file_to_lumin to re-fetch a document reference. Does not return a downloadable file URL. For long-form rules, fetch the lumin://docs/auth resource.

Convert a markdown string into a PDF. Returns a temporary signed download URL (~30 minutes); download or re-ingest via upload_file_to_lumin (method 'file-upload') before it lapses if long-term storage is needed, or pass it to lumin_send_signature_request_from_file as file_url. Field tags (self-closing, inline in the markdown body): <signature-field />, <initials-field />, <date-field />, <text-field />. Do not invent other tags. When to use: the document body text has been drafted and a PDF artifact is needed. Do not use when a stable PDF URL already exists — pass that directly to upload_file_to_lumin or lumin_send_signature_request_from_file. For long-form rules, fetch the lumin://docs/templates resource.

Paginated list of templates in the workspace, including AgreementGen (type 'lumin') and Sign/PDF (type 'pdf') variants. Filter by location; when location = 'space', space_id is required. Sort format: '{field}:{direction}' where field is created_at / updated_at / name and direction is asc / desc (default 'updated_at:desc'). Use the returned template_id with lumin_get_template_details, lumin_generate_document_from_template, or lumin_send_signature_request_from_template. For long-form rules, fetch the lumin://docs/templates resource.

Full detail for a single template: type ('pdf' / 'lumin'), location, signing_type, signer_roles (with groups and preassigned_signer for AG), tags, fields, variables (AG), collections (AG row-loop / table-repeat markers), plus AG-only signature-request defaults viewers and custom_email. Use before send: call this before lumin_send_signature_request_from_template or lumin_generate_document_from_template to discover required tag/field/variable/collection keys and preassigned signer/viewer defaults. For long-form rules, fetch the lumin://docs/templates resource.

Materialize a document (not a signature request) from a template. Returns a signed download URL (~30 minutes). Prefill maps by template type: tags — Sign templates only ([text-merge|req|sender|Object.Field] markers); fields — all template types (form-field prefill); variables — AG templates only; collections — AG templates only (row-loop / table-repeat, max 100 items per collection and 50 collections per request; silently ignored on other types). Unknown collection keys are discarded silently; malformed shape returns 400 invalid_argument. Call lumin_get_template_details first to discover the required keys. For long-form rules, fetch the lumin://docs/templates resource.

Create and send a signature request from one or more hosted PDF files. Supply exactly one of: file_url (single hosted PDF, max 20 MB) or file_urls (multiple hosted PDFs, merged before send, max 20 MB each). The file_url from lumin_markdown2pdf can be used directly. Signing types: SAME_TIME (default, parallel) or ORDER (sequential by signers[].group, group starts at 1 and is required on every signer when ORDER). Text-tag mode: use_text_tags = true parses [field_type|requirement|actor|Object.Field] markers inside the PDF body and converts them into interactive form fields. Side effects: sends email invitations — confirm the recipient list with the user first. After success, poll get_signature_request_on_lumin_by_id. For long-form rules, fetch the lumin://docs/signature-requests resource.

Create and send a signature request from a Lumin template in one step. Call lumin_get_template_details first to discover signer roles and required tag/field/variable/collection keys. Prefill maps by template type: tags — Sign templates; fields — all template types; variables — AG only; collections — AG only (max 100 items per collection, 50 collections). Signers: signers[].signer_role must match a role defined on the template. AG-only overrides (template type 'lumin'): signing_type, signers[].group, viewers, and custom_email fall back to template values when omitted and override them for this send when supplied. Supplying signing_type or signers[].group on Sign/PDF templates returns 400 signing_type_override_not_allowed / 400 signer_group_override_not_allowed. Overrides never mutate the source template. Side effects: sends email invitations — confirm the recipient list with the user first. After success, poll get_signature_request_on_lumin_by_id. For long-form rules, fetch the lumin://docs/signature-requests resource.

Non-destructive fetch of status, signer completion, timestamps, and document references for a signature request. Recommended polling cadence 15-60s with exponential backoff; never poll faster than 5s. Status enum: WAITING_FOR_PROCESSING, NEED_TO_SIGN, WAITING_FOR_OTHERS, APPROVED, REJECTED, CANCELLED, FAILED. Terminal statuses: APPROVED, REJECTED, CANCELLED, FAILED. For long-form rules, fetch the lumin://docs/signature-requests resource.

Extend or shorten the expiry on an in-flight signature request. Only permitted while status is NEED_TO_SIGN or WAITING_FOR_OTHERS and the caller is the request creator — otherwise returns 409 conflict. For long-form rules, fetch the lumin://docs/signature-requests resource.

Send a reminder email to selected pending signers of a signature request. Only signers currently in NEED_TO_SIGN are emailed; already-signed signers are returned with email_status BOUNCE. Rate limit: 10 reminder emails per signer per day (email_status EXCEED_DAILY_LIMIT). The response includes a per-email outcome. Side effects: sends emails — confirm the recipient list with the user first. For long-form rules, fetch the lumin://docs/signature-requests resource.

Return a single-use signing URL for a specific signer of a signature request. Use to embed signing inside a host app or hand the link to the signer directly instead of relying on the emailed link. The returned view_url honours the request's expiry and is single-use per signer. Returns 404 signer_email_not_found if the email is not a signer on the request. For long-form rules, fetch the lumin://docs/signature-requests resource.

Cancel (void) a signature request. Sets status = CANCELLED; recipients can no longer complete signing but the audit trail is preserved (read-only, not recoverable). Requires explicit user confirmation of both the request id and the intent to cancel before calling. For long-form rules, fetch the lumin://docs/signature-requests resource.

Fetch a downloadable file for a signature request. Preconditions by file_type: - 'agreement' (default) — no precondition; returns the current/final agreement PDF. - 'coc' — requires status APPROVED and a Certificate of Completion exists. - 'merged' — requires status APPROVED and both artifacts exist (agreement then CoC as a single PDF). Returns a signed URL that expires in ~30 minutes. Errors: 409 signature_request_not_approved when 'coc' / 'merged' is requested before approval; 400 coc_unavailable / 400 merged_unavailable when the artifact does not exist. For long-form rules, fetch the lumin://docs/signature-requests resource.

Create a new AgreementGen document from an AG template (method 'template'). agreement_data takes template_id plus optional prefill (variables, fields, collections), CRM linked_objects, and signature-request defaults stored on the agreement (signer_roles with groups and preassigned signers, signing_type, viewers, custom_email) that pre-fill the Review & Send flow. Defaults fall back to template values when omitted; supplying overrides never mutates the source template. Placement: agreement_data.location is 'personal' / 'space' / 'workspace' (space_id required when type = 'space'). Omit it to create in the caller's personal list — the agreement does not inherit the template's location, so pass it explicitly to keep a Space template's output visible to the Space. Returns the agreement ID, preview URL, resolved location, and a download link. For long-form rules, fetch the lumin://docs/templates resource.

Return a signed download URL for the current PDF representation of an AgreementGen document. The URL expires in ~30 minutes; re-call this tool to regenerate it. For long-form rules, fetch the lumin://docs/templates resource.