# Integrate with AI Agents using MCP

This guide is only for the [self-hosted version](https://www.docuseal.com/on-premises.md) of DocuSeal.

## 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
```

## 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
```

## 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"
      }
    }
  }
}
```

## 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"
  }
}
```

### 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
  }
}
```

### 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"
  }
}
```

### 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"
          }
        ]
      }
    ]
  }
}
```

### 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"
  }
}
```

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

## 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."_

## 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`.

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

- [REST API Reference](https://www.docuseal.com/docs/api.md)