Integrate with AI Agents using MCP

  1. Introduction
  2. Authentication
  3. Client Configuration
  4. Available Tools
  5. Error Responses
  6. Example AI Prompts
  7. Troubleshooting
  8. Compatibility

This guide is only for the self-hosted version of DocuSeal.

1

Introduction

DocuSeal provides an MCP server that allows AI agents and automation systems to interact with DocuSeal using the Model Context Protocol. With MCP, AI systems can:

  • Search document templates by name
  • Load template details including fields and signing roles
  • Create new document templates from PDF or DOCX files
  • Send documents for electronic signature with prefilled fields
  • Search and track signed or pending documents

This enables AI-native document workflows where document signing is fully automated and driven by AI agents without manual intervention.

What is MCP

MCP (Model Context Protocol) is an open standard that allows AI systems to call tools exposed by external services. Instead of manually coding API integrations, AI agents can automatically discover the tools that DocuSeal exposes and use them directly in workflows.

This means an AI system connected to the DocuSeal MCP server can understand what actions are available, what parameters each action requires, and execute them on behalf of users.

MCP Endpoint

AI systems connect to the following endpoint to discover available tools and execute actions:

For self-hosted DocuSeal, replace yourdomain.com with your own domain.

MCP Server URL 
https://yourdomain.com/mcp
2

Authentication

Authentication depends on the deployment type: self-hosted DocuSeal or DocuSeal Cloud.

Self-Hosted DocuSeal

Self-hosted installations authenticate using an MCP token. To create a token, go to Settings > MCP Server in your DocuSeal instance and click "New Token".

The token is included in the request header:

Request Header 
Authorization: Bearer YOUR_DOCUSEAL_MCP_TOKEN
3

Client Configuration

The DocuSeal MCP server works with any MCP-compatible client. Below are configuration examples for the most popular clients.

Claude Desktop / Cursor / VS Code

Add the following configuration to your MCP client settings file. Replace YOUR_DOCUSEAL_MCP_TOKEN with the token from your DocuSeal MCP Server settings page.

For self-hosted DocuSeal, replace yourdomain.com with your own domain.

MCP Client Configuration 
{
  "mcpServers": {
    "docuseal": {
      "type": "http",
      "url": "https://yourdomain.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_DOCUSEAL_MCP_TOKEN"
      }
    }
  }
}
4

Available Tools

The DocuSeal MCP server exposes the following tools:

Tool Description
search_templates Search document templates by name.
load_template Load a template with its fields and signing roles.
create_template Create a template from a PDF/DOCX file URL, or create an empty template.
send_documents Send a document template for signing to specified submitters.
search_documents Search signed or pending documents by submitter name, email, phone, or template name.

search_templates

Search document templates by name. Returns a list of matching templates with their IDs and names.

Parameters:

q string required

Search query to filter templates by name

limit integer

The number of templates to return (default 10, max 100)

Example Tool Call 
{
  "name": "search_templates",
  "arguments": {
    "q": "NDA"
  }
}
Example Response 
[
  {
    "id": 12,
    "name": "Non-Disclosure Agreement"
  },
  {
    "id": 8,
    "name": "NDA - Mutual"
  }
]

load_template

Load a template with its fields. Each field includes name, type, and the signing role name. Use this tool to inspect template details before sending documents.

Parameters:

template_id integer required

Template identifier

Example Tool Call 
{
  "name": "load_template",
  "arguments": {
    "template_id": 12
  }
}
Example Response 
{
  "id": 12,
  "name": "Non-Disclosure Agreement",
  "roles": [
    "First Party",
    "Second Party"
  ],
  "fields": [
    {
      "name": "Full Name",
      "type": "text",
      "role": "First Party"
    },
    {
      "name": "Signature",
      "type": "signature",
      "role": "First Party"
    },
    {
      "name": "Full Name",
      "type": "text",
      "role": "Second Party"
    },
    {
      "name": "Signature",
      "type": "signature",
      "role": "Second Party"
    }
  ]
}

create_template

Create a new document template from a PDF or DOCX file. Provide a URL to upload the file, or provide only a name to create an empty template and receive an edit URL where the file can be uploaded via the UI. Signature and form fields are automatically detected.

Parameters:

name string required

Template name

url string

URL of a PDF or DOCX file to upload. If omitted, an empty template is created and the returned edit_url can be used to upload a file via the UI

Example Tool Call 
{
  "name": "create_template",
  "arguments": {
    "url": "https://example.com/contract.pdf",
    "name": "Sales Agreement"
  }
}
Example Response 
{
  "id": 15,
  "name": "Sales Agreement",
  "edit_url": "https://docuseal.com/templates/15/edit"
}

send_documents

Send a document template for signing to specified submitters. Each submitter receives an email with a link to sign the document.

Parameters:

template_id integer required

Template identifier

submitters array required

List of submitters (signers). Each submitter can have: email, name, phone, role (signing role name from the template), fields (array of prefilled field values with name and value)

Example Tool Call 
{
  "name": "send_documents",
  "arguments": {
    "template_id": 12,
    "submitters": [
      {
        "email": "john@example.com",
        "name": "John Doe",
        "role": "First Party",
        "fields": [
          {
            "name": "Company Name",
            "value": "Acme Inc"
          }
        ]
      }
    ]
  }
}
Example Response 
{
  "id": 42,
  "status": "pending"
}

search_documents

Search signed or pending documents by submitter name, email, phone, or template name. Returns a list of submissions with their status and submitter details.

Parameters:

q string required

Search by submitter name, email, phone, or template name

limit integer

The number of results to return (default 10, max 100)

Example Tool Call 
{
  "name": "search_documents",
  "arguments": {
    "q": "john@example.com"
  }
}
Example Response 
[
  {
    "id": 42,
    "template_name": "Non-Disclosure Agreement",
    "status": "completed",
    "submitters": [
      {
        "email": "john@example.com",
        "name": "John Doe",
        "status": "completed"
      }
    ],
    "documents_url": "https://yourdomain.com/submissions/42"
  }
]
5

Error Responses

When a tool call fails, the response includes isError: true and a message describing the problem. Below are the possible error messages:

Tool Error Message Cause
load_template Template not found The template_id does not match any template. Use search_templates to find the correct ID
send_documents Template not found The template_id does not match any template. Use search_templates to find the correct ID
send_documents Template has no fields The template has no form fields. Open the template in DocuSeal and add fields before sending
send_documents No valid submitters provided The submitters array is empty or contains no valid entries
6

Example AI Prompts

The following natural language prompts demonstrate how AI agents can use DocuSeal MCP tools:

  • "Find my NDA template and send it to john@example.com for signing."
  • "Load the NDA template and show me what fields and roles it has."
  • "Create a new template from this PDF: https://example.com/contract.pdf"
  • "Send the sales agreement to jane@example.com with Company Name prefilled as Acme Inc."
  • "Show me all pending documents sent to @acme.com."
  • "Check if the NDA sent to john@example.com has been signed."
7

Troubleshooting

Authentication errors

Verify that your MCP token is correct. Ensure the token was created in Settings > MCP Server.

Template not found

The template_id passed to send_documents must be a valid template ID. Use search_templates first to find the correct ID.

Template has no fields

A template must have at least one field (e.g., signature, text, date) before it can be sent for signing. Open the template in DocuSeal and add the required fields.

Connection issues with self-hosted DocuSeal

Make sure your DocuSeal instance is accessible from the MCP client. The MCP endpoint must be reachable over HTTPS at https://YOUR_DOMAIN/mcp.

8

Compatibility

The DocuSeal MCP server works with any MCP-compatible client, including:

  • Claude.ai
  • Claude Desktop
  • ChatGPT
  • Cursor
  • Windsurf
  • VS Code
  • Claude Code
  • Any other MCP-compatible AI agent or client

If you are building AI-powered systems that handle contracts, agreements, or any documents that require signatures, integrate the DocuSeal MCP server to automate your document signing workflows end to end.

Learn more