Connect DocuSign to ChatGPT: Manage users and envelope lifecycles

If you want to connect DocuSign to ChatGPT so your AI agents can read contracts, draft signature requests, update user directories, and download final PDFs, you need a Model Context Protocol (MCP) server. If your team uses Claude, check out our guide on connecting DocuSign to Claude or explore our broader architectural overview on connecting DocuSign to AI Agents.

Giving a Large Language Model (LLM) read and write access to an enterprise e-signature platform is an engineering challenge. You either spend weeks building, hosting, and maintaining a custom MCP server to translate LLM JSON arguments into DocuSign's highly specific payload structures, or you use a managed infrastructure layer.

This guide breaks down exactly how to use Truto to generate a secure, authenticated MCP server for DocuSign, connect it natively to ChatGPT, and execute complex contract workflows - including full envelope lifecycle management - using natural language.

The Engineering Reality of the DocuSign API

A custom MCP server is a self-hosted integration layer that translates an LLM's tool calls into REST API requests. While the open MCP standard provides a predictable way for models to discover tools, implementing it against vendor APIs is painful. If you decide to build a custom MCP server for DocuSign, you own the entire API lifecycle.

Here are the specific integration challenges that break standard CRUD assumptions when working with DocuSign:

The Envelope State Machine

In DocuSign, you do not simply "create a document." You create an Envelope. An Envelope is a state machine that bundles documents, recipients, and signature tabs. When an LLM wants to send a contract, it must understand this lifecycle. Creating an envelope with a status of created saves it as a draft. Creating it with a status of sent dispatches it immediately. If your AI attempts to modify a recipient on an envelope that has already moved to completed or delivered, the API will throw an error. Your MCP tool schemas must strictly define these states so the LLM understands when and how to transition them.

Document Binaries vs. JSON Metadata

LLMs operate in text. DocuSign operates in PDFs and binary streams. When you request a document download from DocuSign, the API does not return a JSON object containing the text of the contract. It returns raw binary file bytes with a Content-Disposition header. If your MCP server does not intercept this binary stream, base64-encode it, or write it to a temporary storage layer that the LLM can access via a text reference, the tool call will fail catastrophically. Truto's proxy handlers manage this translation automatically.

Complex Tab Anchoring Schemas

To tell a user where to sign, DocuSign uses "tabs" (e.g., SignHere, DateSigned, Text). These tabs must be mapped to specific recipientId values and bound to specific documentId values. Furthermore, they require either precise X/Y coordinate mapping or AutoPlace (anchor string) positioning. Exposing this nested, highly relational JSON schema to ChatGPT requires massive, perfectly annotated tool definitions. If the LLM hallucinates a recipientId that doesn't exist in the envelope array, the request fails.

Strict Rate Limits and 429 Errors

DocuSign enforces strict burst rate limits. Factual note on rate limits: Truto does not retry, throttle, or apply backoff on rate limit errors. When the upstream DocuSign API returns an HTTP 429 Too Many Requests, Truto passes that error directly to the caller. Truto normalizes the upstream rate limit information into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF specification. Your client architecture is completely responsible for handling retry and exponential backoff logic. Do not expect the MCP server to absorb these failures.

Creating the DocuSign MCP Server

Instead of building this infrastructure from scratch, you can use Truto to dynamically generate an MCP server mapped specifically to your DocuSign account.

Tool generation is dynamic and documentation-driven. Rather than hand-coding tool definitions, Truto derives them from DocuSign's resource definitions and JSON Schema documentation. Each server is scoped to a single integrated account and secured via a cryptographic token in the URL.

Method 1: Via the Truto UI

For teams who prefer visual configuration, you can generate a server directly from the dashboard.

1. Navigate to the Integrated Accounts page in your Truto environment.
2. Select your connected DocuSign account.
3. Click the MCP Servers tab.
4. Click Create MCP Server.
5. Select your desired configuration. You can filter by allowed methods (e.g., read, write) or by tags (e.g., envelopes, users).
6. Copy the generated MCP server URL. It will look like https://api.truto.one/mcp/a1b2c3d4e5f6...

Method 2: Via the API

For automated deployments, you can provision an MCP server programmatically. Make an authenticated POST request to the Truto API with your desired configuration.

curl -X POST https://api.truto.one/integrated-account/{integrated_account_id}/mcp \
  -H "Authorization: Bearer YOUR_TRUTO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "DocuSign Contracts AI",
    "config": {
      "methods": ["read", "write"],
      "tags": ["envelopes", "users"]
    }
  }'

The API returns a database record containing the configuration and the secure URL.

{
  "id": "9876-abcd-1234",
  "name": "DocuSign Contracts AI",
  "config": { 
    "methods": ["read", "write"], 
    "tags": ["envelopes", "users"] 
  },
  "expires_at": null,
  "url": "https://api.truto.one/mcp/a1b2c3d4e5f6..."
}

ChatGPT MCP Setup Guide

Once you have your Truto MCP URL, you simply need to register it with your client. The URL alone contains the routing and authentication required to expose the DocuSign tools.

Prerequisites before you start:

• A DocuSign account already connected as an Integrated Account in Truto (OAuth completed).
• A generated MCP server URL from the previous section.
• A ChatGPT Pro, Plus, Business, Enterprise, or Education account - MCP custom connectors run behind the Developer mode flag on these tiers.
• Admin permission on the ChatGPT workspace if you're adding the connector at the org level.

Method A: Via the ChatGPT UI

Follow these steps in order to wire DocuSign tools into ChatGPT:

1. Open ChatGPT settings. Click your profile avatar and navigate to Settings -> Apps -> Advanced settings.
2. Turn on Developer mode. Toggle Developer mode on. Custom MCP connectors are hidden until this flag is enabled.
3. Add a new server. Under MCP servers / Custom connectors, click Add a new server.
4. Name the connector. Enter a human-readable label such as "DocuSign (Truto)". This is the string ChatGPT will show when it picks a tool.
5. Paste the Server URL. Drop the Truto MCP URL (https://api.truto.one/mcp/<token>) into the Server URL field.
6. Save. ChatGPT immediately executes the MCP initialize handshake, calls tools/list, and displays the discovered DocuSign tools. You should see entries like create_a_docu_sign_envelope, get_single_docu_sign_envelope_by_id, and list_all_docu_sign_templates.
7. Test with a read call. In a new chat, ask ChatGPT to "list the five most recent DocuSign envelopes." If the connector is wired correctly, the model will invoke list_all_docu_sign_envelopes and return live results.

If you generated the MCP server with require_api_token_auth: true, add your Truto API token to the connector's Authorization header as Bearer <token> when prompted.

Method B: Via Manual Config File

If you are running a local multi-agent setup, Cursor, or the Claude Desktop client, you can connect via a JSON configuration file using an SSE transport wrapper.

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

Hero Tools for DocuSign

When ChatGPT requests the tool list, Truto maps DocuSign's proxy endpoints into distinct operations. Here are the highest-leverage tools available for AI agents automating e-signature workflows.

1. create_a_docu_sign_envelope

This is the core tool for initiating signature workflows. It allows the agent to build a new envelope from scratch or via a template, assigning documents, recipients, and tabs. Setting the status to created saves a draft; setting it to sent dispatches emails immediately.

"Draft a new DocuSign envelope for an NDA using template ID 88a3-4f... Assign John Doe (john@example.com) as the primary signer and leave the envelope status as 'created' so I can review it before sending."

2. get_single_docu_sign_envelope_by_id

Agents need to poll or verify state transitions. This tool retrieves the full details of a single envelope, including its status, routing order, timestamps, and active recipient data.

"Check the status of envelope ID 1234-abcd. Has the client signed it yet, or is it still sitting in the 'delivered' state?"

3. list_all_docu_sign_templates

Before drafting an envelope, an agent often needs to locate the correct underlying template. This tool lists templates associated with the account, exposing their IDs, recipient requirements, and metadata.

"List all available DocuSign templates related to 'Vendor Agreements' and tell me the required recipient roles for the most recent one."

4. list_all_docu_sign_users

This tool allows the LLM to audit the internal account roster. It can list users, check their status, verify if they have admin privileges, and inspect group affiliations.

"List all active DocuSign users in our account and flag anyone who currently has admin privileges enabled."

5. docu_sign_envelope_documents_download

Once a contract is signed, the agent can use this tool to retrieve the physical files. Passing the special value combined downloads all documents merged into a single PDF, while passing certificate retrieves only the Certificate of Completion.

"Download the combined final PDF for the completed envelope ID 9999-wxyz so we can archive it in our internal storage."

6. list_all_docu_sign_webhooks

DocuSign uses "Connect" webhooks to push real-time event data. This tool lets the agent audit current webhook configurations (URL destinations, event triggers, and failure logs) to ensure the system is properly integrated with external listening services.

"List all active DocuSign Connect webhook configurations and tell me which ones are listening for 'envelope-completed' events."

To view the complete schema definitions and the full inventory of available endpoints, visit the DocuSign integration page.

Managing Envelope Lifecycles from ChatGPT

Every DocuSign envelope moves through a defined state machine. Getting ChatGPT to reliably drive contracts end-to-end means teaching the agent when to transition, when to poll, and when to void. Below is the practical mapping between envelope states and the MCP tools an agent should reach for at each step.

The Envelope State Machine

Lifecycle Operations Mapped to MCP Tools

• Draft then review. Call create_a_docu_sign_envelope with status: "created". The envelope stays as a draft until an explicit transition.
• Dispatch a draft. Update the envelope with status: "sent" to release it to signers.
• Poll for state changes. Use get_single_docu_sign_envelope_by_id to inspect status, sentDateTime, deliveredDateTime, and completedDateTime. Agents should poll on an exponential backoff schedule - DocuSign's burst rate limits will 429 tight loops, and Truto surfaces those 429s directly.
• Send a reminder. For envelopes stuck in sent or delivered, invoke the reminder endpoint to nudge signers without altering the envelope state.
• Correct recipients or tabs. For envelopes in sent or delivered state, the correction flow lets you modify recipients before signing completes. Correction attempts on a completed envelope will return a 409.
• Void an in-flight envelope. Update the envelope with status: "voided" and supply a voidedReason. This is the only clean way to cancel a contract that hasn't reached a terminal state.
• Download final artifacts. Once the envelope reaches completed, call docu_sign_envelope_documents_download with combined for the merged PDF or certificate for the audit trail.

Guardrails for LLM-driven Transitions

Two failure modes come up repeatedly when ChatGPT drives an envelope end-to-end:

1. Illegal transitions. Attempting to update a completed or voided envelope, or setting status: "sent" on an envelope that's already dispatched, will return a 400 or 409. Instruct the agent in your system prompt to always call get_single_docu_sign_envelope_by_id before any write.
2. Hallucinated recipient IDs. During corrections, recipients must be referenced by the exact recipientId values returned by the envelope. Tell the agent to fetch the current recipient array first and reuse those IDs verbatim - do not let the model invent them.

During evaluation, restrict the MCP server to methods: ["read"] so your agent can practice reading and reasoning about lifecycle transitions without dispatching real contracts. Flip to ["read", "write"] only after the prompts behave as expected.

Workflows in Action

Let's look at how AI agents execute multi-step DocuSign operations autonomously using these generated tools.

Scenario 1: Automated HR Offer Letter Dispatch

An HR administrator wants ChatGPT to find the standard offer letter template, generate an envelope for a new candidate, and prep it for review.

"Find our standard 'Engineering Offer Letter' template. Create a new draft envelope using that template for a candidate named Jane Smith (jane.smith@example.com) as the primary signer. Do not send it yet."

sequenceDiagram
    participant User as HR Admin
    participant ChatGPT as ChatGPT
    participant Truto as Truto MCP Server
    participant DocuSign as DocuSign API

    User->>ChatGPT: "Find offer letter template & draft envelope for Jane Smith..."
    
    ChatGPT->>Truto: call list_all_docu_sign_templates(search="Engineering Offer Letter")
    Truto->>DocuSign: GET /v2.1/accounts/{id}/templates?search_text=Engineering...
    DocuSign-->>Truto: Template ID: T-555
    Truto-->>ChatGPT: Return template details

    ChatGPT->>Truto: call create_a_docu_sign_envelope(templateId="T-555", status="created", recipients=[...])
    Truto->>DocuSign: POST /v2.1/accounts/{id}/envelopes
    DocuSign-->>Truto: Envelope ID: ENV-888, Status: created
    Truto-->>ChatGPT: Return draft envelope summary
    
    ChatGPT-->>User: "Draft envelope ENV-888 has been created and is ready for your review."

What happens: ChatGPT first uses the template listing tool to perform a text search for the correct document. Upon extracting the ID, it builds a complex nested JSON payload fulfilling the template's recipient requirements. It explicitly sets the envelope state to created, ensuring the contract acts as a draft rather than blasting an unreviewed offer to the candidate.

Scenario 2: Sales Ops Deal Verification

A RevOps manager needs to verify that a client signed a contract and ensure the final PDF is logged for compliance.

"Check the status of envelope ID 1029-abcd. If it's completed, download the combined final documents and summarize who signed it and when."

sequenceDiagram
    participant User as RevOps Manager
    participant ChatGPT as ChatGPT
    participant Truto as Truto MCP Server
    participant DocuSign as DocuSign API

    User->>ChatGPT: "Check status of 1029-abcd and download if completed..."
    
    ChatGPT->>Truto: call get_single_docu_sign_envelope_by_id(id="1029-abcd")
    Truto->>DocuSign: GET /v2.1/accounts/{id}/envelopes/1029-abcd
    DocuSign-->>Truto: Status: completed, completedDateTime: 2026-10-12...
    Truto-->>ChatGPT: Return envelope metadata

    ChatGPT->>Truto: call docu_sign_envelope_documents_download(id="combined", envelope_id="1029-abcd")
    Truto->>DocuSign: GET /v2.1/accounts/{id}/envelopes/1029-abcd/documents/combined
    DocuSign-->>Truto: Binary PDF Bytes
    Truto-->>ChatGPT: Return file attachment metadata/bytes
    
    ChatGPT-->>User: "The envelope is completed. It was signed on Oct 12. I have retrieved the final PDF for your records."

What happens: ChatGPT executes a read tool to poll the state machine. Recognizing the completed status, it conditionally executes a secondary tool call, specifying the special combined string identifier required by the DocuSign API to merge all signed pages and certificates into a single download payload.

Security and Access Control

Exposing an e-signature platform to an autonomous agent requires strict governance. Truto MCP servers enforce boundaries at the infrastructure level, ensuring the AI cannot execute unauthorized actions.

• Method Filtering: By configuring the server with methods: ["read"], you completely strip the LLM of its ability to call create, update, or delete tools. The agent can audit envelopes but cannot send new contracts.
• Tag Filtering: Limit the surface area by specifying tags during server creation. For instance, setting tags: ["users"] exposes the directory tools but hides all envelope and template endpoints.
• Extra Authentication (require_api_token_auth): By default, possessing the MCP URL grants access. By setting this flag to true, the MCP client must inject a valid Truto API session token into the headers, adding a secondary layer of Identity verification before tool execution.
• Time-to-Live (expires_at): For temporary workflows or external contractor access, you can define an ISO datetime. The platform automatically drops the token at expiration, immediately cutting off the AI's access to the API without manual intervention.

Stop Hardcoding Integration Logic

The DocuSign API is immensely powerful, but writing custom JSON wrappers, handling binary document streams, and mapping envelope state logic into LLM contexts drains engineering time. By relying on dynamic MCP servers, you shift the integration burden to managed infrastructure.

Your engineers focus on building better AI agents. Truto handles the API translation, token management, and schema generation.