Connect Firma to ChatGPT: Automate Templates & E-Signature Requests

If you want to connect Firma to ChatGPT so your AI agents can read templates, draft contracts, and orchestrate e-signature workflows, you need a Model Context Protocol (MCP) server. If your team relies on Claude for document automation, check out our guide on connecting Firma to Claude, or explore our architectural overview on connecting Firma to AI Agents for programmatic agent pipelines.

Giving a Large Language Model (LLM) read and write access to a document signing platform like Firma is a complex engineering challenge. You must handle secure webhook rotation, map rigid PDF rendering schemas, and manage stateful signing pipelines. You can either spend weeks building, hosting, and maintaining a custom Python or Node.js MCP server, or you use a managed infrastructure layer that generates these endpoints dynamically.

This guide breaks down exactly how to use Truto to generate a secure, managed MCP server for Firma, connect it natively to ChatGPT, and execute complex contract workflows using natural language.

The Engineering Reality of the Firma API

A custom MCP server is a self-hosted integration layer that translates an LLM's tool calls into REST API requests. While the MCP standard provides a predictable way for models to discover tools, implementing it against vendor APIs requires deep domain knowledge of the platform's architectural quirks.

If you decide to build a custom MCP server for Firma, you own the entire API lifecycle. Here are the specific integration challenges that break standard CRUD assumptions when working with the Firma API:

The Immutable Sent State

The Firma API enforces strict state machine rules on document lifecycles. Once a signing request is triggered via the firma_signing_requests_send endpoint, the document is locked. You cannot update the recipients, modify the document payload, or change the signature fields. If your AI agent attempts to run update_a_firma_signing_request_by_id on an active, sent document, Firma throws a hard error. Your custom server must provide explicit schema instructions to the LLM about checking a request's status before attempting an update, otherwise the agent will get stuck in an endless error loop.

XOR Partial Updates

Firma's partial update endpoints (e.g., firma_signing_requests_partial_update) have strict, non-standard constraints. You can update the document's metadata (name, description, expiration) OR you can update a single recipient - but you absolutely cannot combine both in a single HTTP request. A naive MCP tool definition will let the LLM pass both sets of arguments at once, resulting in a validation failure. The integration layer must enforce this XOR logic before the request ever reaches Firma.

Base64 PDF Payloads

Firma does not ingest raw text strings for contracts. To create a template or a signing request from scratch, the API requires the document payload to be a base64-encoded PDF. For an LLM to generate a custom contract, your MCP server must handle the intermediate step of compiling the LLM's markdown output into a PDF buffer and encoding it to base64 before executing the POST request. If you expose the raw Firma API directly, the LLM will attempt to hallucinate an invalid base64 string and the API will reject it.

How to Generate a Firma MCP Server

Instead of dealing with state machine validation and webhook secrets manually, you can use Truto to generate a production-ready Firma MCP server. This server dynamically derives tool definitions directly from the Firma API schema and handles all underlying authentication via the integrated account.

There are two ways to generate a Firma MCP server in Truto.

Method 1: Via the Truto UI

This is the fastest path for administrators configuring manual ChatGPT integrations.

1. Log into your Truto dashboard and navigate to the integrated account page for your Firma connection.
2. Click the MCP Servers tab.
3. Click Create MCP Server.
4. Define your configuration (e.g., name the server "Firma Contract Ops", set method filters, or assign specific tool tags).
5. Copy the generated MCP server URL (it will look like https://api.truto.one/mcp/abc123def456).

Method 2: Via the Truto API

For engineering teams building multi-tenant AI products, you can provision Firma MCP servers programmatically for your end-users.

Send an authenticated POST request to the Truto API:

curl -X POST https://api.truto.one/integrated-account/{integrated_account_id}/mcp \
  -H "Authorization: Bearer YOUR_TRUTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Firma Production E-Sign Server",
    "config": {
      "methods": ["read", "write"],
      "require_api_token_auth": false
    }
  }'

Truto validates that the Firma integration has documented endpoints, provisions a cryptographic token backed by Cloudflare KV, and returns the URL. This token is fully self-contained - the URL alone authenticates requests against that specific Firma tenant.

How to Connect the Firma MCP Server to ChatGPT

Once you have your Truto MCP server URL, you must register it as a tool source within your AI environment.

Method A: Via the ChatGPT UI

If you are using the ChatGPT web or desktop application, you can connect the server directly:

1. In ChatGPT, navigate to Settings > Apps > Advanced settings.
2. Enable Developer mode.
3. Under the MCP servers/Custom connectors section, click Add new server.
4. Set the Name to "Firma E-Signatures".
5. Paste the Truto MCP server URL into the Server URL field.
6. Click Save.

ChatGPT will immediately ping the /initialize JSON-RPC endpoint on the Truto server, execute tools/list, and load all available Firma capabilities into its context window.

Method B: Via Manual Config File

If you are running a custom desktop agent, Cursor, or a local development environment that supports standard MCP configuration files, you can connect using the Server-Sent Events (SSE) transport.

Add the following to your mcp_config.json file:

{
  "mcpServers": {
    "firma_production": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sse",
        "--url",
        "https://api.truto.one/mcp/YOUR_FIRM_TOKEN_HERE"
      ]
    }
  }
}

Firma Hero Tools

Truto automatically maps Firma's complex REST API into flat, deterministic JSON-RPC tools optimized for LLM function calling. Here are the highest-leverage tools your ChatGPT agent can use to orchestrate document workflows.

1. create_a_firma_template

This tool allows the LLM to generate a reusable Firma template from a base64-encoded document payload. It requires the name and document properties.

Usage note: Because ChatGPT cannot natively compile PDFs, this tool is best used in environments where an intermediate agent handles the PDF-to-base64 conversion before passing the payload to the MCP endpoint.

"I have attached a base64 string representing our standard NDA. Use the create_a_firma_template tool to upload this as a new template named 'Standard Vendor NDA 2026'. Ensure the expiration_hours is set to 72."

2. create_a_firma_signing_request

This is the core tool for initiating an e-signature workflow. It allows you to create a request using either a raw document OR a pre-existing template_id (do not pass both).

Usage note: When generating from a template, this tool creates the request in a "draft" state, meaning notifications are not yet sent to the recipients.

"Create a new signing request using the template ID 'tpl_987654'. Name it 'Acme Corp Master Service Agreement'. Add John Doe (john@acme.com) as the first recipient and Jane Smith (jane@acme.com) as the second recipient."

3. firma_signing_requests_send

This critical action tool takes a draft signing request and dispatches it via email to all configured recipients, locking the document from further updates.

Usage note: Always instruct the LLM to verify the request payload is correct before calling this tool, as the operation is irreversible.

"Take the signing request ID 'req_123abc' that we just drafted for Acme Corp and send it. Confirm how many recipients were notified once the tool returns the success message."

4. update_a_firma_template_by_id

Provides a comprehensive PUT operation to overwrite metadata, settings, recipients, and field coordinates on an existing template.

Usage note: This is a full replacement operation. The LLM must fetch the current template state via get_single_firma_template_by_id, modify the necessary properties in memory, and pass the entire object back via this tool.

"Fetch the template ID 'tpl_555xyz'. Update the description to 'Updated Q3 Sales Contract' and change the credit_cost allocation to 2, then apply the changes using the update tool."

5. firma_signing_requests_cancel

Allows the LLM to halt an active signing workflow. This soft-deletes the active request and optionally notifies the signers that the contract has been pulled.

Usage note: This tool will fail if the request status is already 'finished' or 'cancelled', or if it was never sent in the first place.

"The client requested a change to the pricing terms. Cancel the active signing request ID 'req_999def' and ensure the notify_signers flag is set to true so they know to discard the old link."

6. create_a_firma_generate_template_token

Generates a short-lived JWT token required for embedding the Firma template editor directly within your own application's iframe.

Usage note: The resulting token expires in 24 hours. This is highly useful for AI agents operating in an internal admin console, allowing them to fetch a secure URL for human-in-the-loop document review.

"We need to review the complex tables in the new employment contract template. Generate an embedded template JWT token for template ID 'tpl_444abc' and return the secure URL so our HR team can open the editor."

For a complete mapping of all endpoints, parameters, and schema definitions, review the Firma integration page.

Workflows in Action

Connecting these isolated tools into multi-step pipelines is where the MCP architecture shines. Here is how a ChatGPT-powered agent navigates Firma's specific API logic to accomplish real-world tasks.

Workflow 1: Automated Employee Onboarding

When a new hire accepts an offer, the HR team needs to track down the correct contract template, assign the correct signature fields, and dispatch the document.

"Sarah Jenkins accepted the Senior Engineer role. Retrieve the standard employment contract template, create a new signing request for her at sarah.jenkins@example.com, and send it immediately. Let me know when it expires."

Execution Steps:

1. The agent calls list_all_firma_templates filtering by the name "Standard Employment Contract".
2. Using the returned template ID, the agent calls create_a_firma_signing_request passing Sarah's email and name into the recipients array.
3. The agent verifies the returned status is draft, then calls firma_signing_requests_send using the new request ID.
4. The agent parses the expires_at timestamp from the response and outputs the confirmation to the HR user.

sequenceDiagram
    participant User as ChatGPT User
    participant ChatGPT as ChatGPT
    participant Truto as Truto MCP Server
    participant Firma as Firma API

    User->>ChatGPT: "Send standard contract to Sarah..."
    ChatGPT->>Truto: call(list_all_firma_templates)
    Truto->>Firma: GET /templates?search=Standard
    Firma-->>Truto: Return template ID 'tpl_888'
    Truto-->>ChatGPT: Result: tpl_888
    ChatGPT->>Truto: call(create_a_firma_signing_request, {template_id: 'tpl_888', recipients: [...]})
    Truto->>Firma: POST /signing-requests
    Firma-->>Truto: Return draft request ID 'req_111'
    Truto-->>ChatGPT: Result: req_111
    ChatGPT->>Truto: call(firma_signing_requests_send, {id: 'req_111'})
    Truto->>Firma: POST /signing-requests/req_111/send
    Firma-->>Truto: Success
    Truto-->>ChatGPT: Sent confirmation
    ChatGPT-->>User: "The contract has been sent and expires in 72 hours."

Workflow 2: Sales Contract Revision and Resend

A prospect spots an error in an active Master Service Agreement. Because Firma signing requests are immutable once sent, the agent must cancel the active request, duplicate the template, and generate a new pipeline.

"The prospect at GlobalTech flagged a typo in their active MSA (req_555). Cancel that request. Duplicate the MSA template, generate a new signing request for alex@globaltech.com, and give me a JWT token so I can manually fix the typo in the embedded editor before we send it."

Execution Steps:

1. The agent calls firma_signing_requests_cancel on ID 'req_555' to kill the active document.
2. The agent calls firma_templates_duplicate on the original MSA template to generate a fresh, identical draft signing request.
3. The agent identifies the new signing request ID, then calls create_a_firma_jwt_generate_signing_request.
4. The agent returns the secure JWT token to the user, pausing the workflow until a human edits the typo via the embedded UI.

flowchart TD
    A["User Prompts Agent<br>Cancel and Revise MSA"] --> B["Tool: firma_signing_requests_cancel<br>Target: req_555"]
    B --> C["Tool: firma_templates_duplicate<br>Copy base MSA template"]
    C --> D["Tool: create_a_firma_jwt_generate_signing_request<br>Generate embedded UI token"]
    D --> E["Agent Returns JWT URL<br>Awaits Human Edit"]

Security and Access Control

Exposing legally binding contract infrastructure to an autonomous LLM requires strict governance. Truto provides several configuration layers when generating the MCP server to restrict what the AI can do:

• Method Filtering: By defining methods: ["read"] during server creation, you completely remove tools like create_a_firma_signing_request and firma_signing_requests_send from the server. The LLM can audit templates and view document statuses, but it cannot dispatch legally binding agreements.
• Tag Filtering: You can configure integration tags to limit scope. For instance, filtering by ["reporting"] ensures the LLM can only access webhook configurations and user directories, preventing it from touching active signing requests.
• API Token Authentication: Setting require_api_token_auth: true means the MCP URL alone is not enough to connect. The client (e.g., your custom backend) must also inject a valid Truto API bearer token in the headers, adding a second layer of defense against leaked URLs.
• Time-To-Live (TTL): You can inject an expires_at timestamp when provisioning the server. Cloudflare KV handles the auto-expiration, ensuring temporary contractors or test agents lose Firma access exactly when scheduled.

Architecting for Production

Connecting Firma to ChatGPT transforms how teams manage document logistics. Instead of logging into a portal to manually compile PDFs, drag signature blocks, and track expiration dates, your staff can instruct an LLM to orchestrate the entire pipeline via the Firma API.

When deploying this at scale, handling rate limits is the final architectural hurdle. Factual note on rate limits: Truto does not retry, throttle, or apply backoff on rate limit errors. When the upstream Firma API returns an HTTP 429 error, Truto passes that error directly to the caller. Truto normalizes the upstream rate limit data into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) following the IETF specification. Your AI agent platform or custom client architecture is entirely responsible for reading these headers and implementing retry/backoff logic when the LLM attempts to bulk-process too many contracts at once.

By leveraging a managed MCP infrastructure layer, you bypass the boilerplate of building JSON-RPC wrappers, tracking OAuth states, and maintaining complex schema parsers, allowing your engineering team to focus entirely on the AI agent's orchestration logic.