About SignNow API

The SignNow REST API empowers users to deliver a seamless eSignature experience for signers, preparers, and senders. Pre-fill documents, create embedded branded workflows for multiple signers, request payments, and track signature status in real-time. Ensure signing is simple, secure, and intuitive on any device. **What you can do with the SignNow API**: * Send documents and document groups for signature in a role-based order * Create reusable templates from documents * Pre-fill document fields with data * Collect payments as part of the signing flow * Embed the document sending, signing, or editing experience into your website, application, or any system of record * Track signing progress and download the completed documents

--- # SignNow MCP Server > A Model Context Protocol (MCP) server that gives AI agents secure, structured access to **SignNow** eSignature workflows — templates, embedded signing, invites, status tracking, and document downloads — over **STDIO** or **Streamable HTTP**. > mcp-name: io.github.signnow/sn-mcp-server --- ## Table of contents * [Features](#features) * [Quick start](#quick-start) * [Prerequisites](#prerequisites) * [Quick run (uvx)](#quick-run-uvx) * [1. Setup Environment Variables](#1-setup-environment-variables) * [2. Install and Run](#2-install-and-run) * [Local/Remote (HTTP)](#localremote-http) * [Docker](#docker) * [Docker Compose](#docker-compose) * [Configuration](#configuration) * [Authentication options](#authentication-options) * [SignNow & OAuth settings](#signnow--oauth-settings) * [Production key management](#production-key-management) * [Client setup](#client-setup) * [VS Code — GitHub Copilot (Agent Mode) / Cursor](#vs-code--github-copilot-agent-mode--cursor) * [Claude Desktop](#claude-desktop) * [Glama (hosted MCP)](#glama-hosted-mcp) * [MCP Inspector (testing)](#mcp-inspector-testing) * [Tools](#tools) * [FAQ / tips](#faq--tips) * [Examples](#examples) * [Useful resources](#useful-resources) * [Sample apps](#sample-apps) * [API documentation](#api-documentation) * [SignNow API Helper MCP](#signnow-api-helper-mcp) * [License](#license) --- ## Features * **Templates & groups** * Browse all templates and template groups * Create documents or groups from templates (one-shot flows included) * **Invites & embedded UX** * Email invites and ordered recipients * **Embedded signing/sending/editor** links for in-app experiences * **Status & retrieval** * Check invite status and step details * Download final documents (single or merged) * Read normalized document/group structure for programmatic decisions * **Transports** * **STDIO** (best for local clients) * **Streamable HTTP** (best for Docker/remote) --- ## Quick start ### Prerequisites - SignNow account. Create a [free developer account](https://www.signnow.com/developers). - SignNow Credentials: You will need your account email, password, and the application Basic Authorization Token. [Getting started](https://docs.signnow.com/docs/signnow/get-started). - An active SignNow API application. - Python 3.11+ installed on your system (check with python3 --version) - UVX installed (check with uvx --version). Recommended for the quickest setup. - Environment variables configured - If your client supports Streamable HTTP, you can use the pre-deployed server URL `https://mcp-server.signnow.com/mcp` instead of running it locally. ### Quick run (uvx) If you use `uv`, you can run the server without installing the package: ```bash uvx --from signnow-mcp-server sn-mcp serve ``` ### 1. Setup Environment Variables ```bash # Create .env file with your SignNow credentials # You can copy from env.example if you have the source code # Or create .env file manually with required variables (see Environment Variables section below) ``` ### 2. Install and Run #### Option A: Install from PyPI (Recommended) ```bash # Install the package from PyPI pip install signnow-mcp-server # Run MCP server in standalone mode sn-mcp serve ``` #### Option B: Install from Source (Development) ```bash # 1) Clone & configure git clone https://github.com/signnow/sn-mcp-server.git cd sn-mcp-server cp .env.example .env # fill in your values in .env # 2) Install (editable for dev) pip install -e . # 3) Run as STDIO MCP server (recommended for local tools & Inspector) sn-mcp serve ``` > STDIO is ideal for desktop clients and local testing. ### Local/Remote (HTTP) ```bash # Start HTTP server on 127.0.0.1:8000 sn-mcp http # Custom host/port sn-mcp http --host 0.0.0.0 --port 8000 # Dev reload sn-mcp http --reload ``` By default, the **Streamable HTTP** MCP endpoint is served under `/mcp`. Example URL: ``` http://localhost:8000/mcp ``` ### Docker ```bash # Build docker build -t sn-mcp-server . # Run HTTP mode (recommended for containers) docker run --env-file .env -p 8000:8000 sn-mcp-server sn-mcp http --host 0.0.0.0 --port 8000 ``` > STDIO inside containers is unreliable with many clients. Prefer HTTP when using Docker. ### Docker Compose ```bash # Only the MCP server docker-compose up sn-mcp-server # Both services (if defined) docker-compose up ``` --- ## Configuration Copy `.env.example` → `.env` and fill in values. All settings are validated via **pydantic-settings** at startup. ### Authentication options **1) API Key / Access Token (simplest)** ``` SIGNNOW_ACCESS_TOKEN= # or equivalently: SIGNNOW_API_KEY= ``` [Generate an API key →](https://docs.signnow.com/docs/signnow/authentication#generate-an-api-key) **2) Username / Password** ``` SIGNNOW_USER_EMAIL= SIGNNOW_PASSWORD= SIGNNOW_API_BASIC_TOKEN= ``` **3) OAuth 2.0 (for hosted/advanced scenarios)** ``` SIGNNOW_CLIENT_ID= SIGNNOW_CLIENT_SECRET= # + OAuth server & RSA settings below ``` > When running via some desktop clients, only user/password may be supported. #### Per-request access token (HTTP transport) For multi-tenant / proxy deployments, a wrapping backend can attach the **raw SignNow access token per request** via a dedicated HTTP header — no env config, and without reusing `Authorization` (which carries the MCP/OAuth bearer): ``` X-SignNow-Access-Token: ``` - Value is the **raw token** — no `Bearer ` prefix. - Resolved per request; nothing is cached or stored (stateless). - **Precedence:** an env-configured `SIGNNOW_ACCESS_TOKEN` (Option 1) still wins. To use the header as a true per-request credential, do **not** also set `SIGNNOW_ACCESS_TOKEN` — otherwise every request collapses to the env token. The header outranks a generic `Authorization: Bearer`. - HTTP transport only (`sn-mcp http`). It is **not** exposed as a tool argument, so the token never enters the model's context or conversation logs. Send over HTTPS. ### SignNow & OAuth settings ``` # SignNow endpoints (defaults shown) SIGNNOW_APP_BASE=https://app.signnow.com SIGNNOW_API_BASE=https://api.signnow.com # OAuth server (if you enable OAuth mode) OAUTH_ISSUER= ACCESS_TTL=3600 REFRESH_TTL=2592000 ALLOWED_REDIRECTS= # RSA keys for OAuth (critical in production) OAUTH_RSA_PRIVATE_PEM= OAUTH_JWK_KID= ``` ### Production key management If `OAUTH_RSA_PRIVATE_PEM` is missing in production, a new RSA key will be generated on each restart, **invalidating all existing tokens**. Always provide a persistent private key via secrets management in prod. --- ## Client setup ### VS Code — GitHub Copilot (Agent Mode) / Cursor Create `.vscode/mcp.json` / `.cursor/mcp.json` in your workspace: **STDIO (local):** ```json { "servers": { "signnow": { "command": "sn-mcp", "args": ["serve"], "env": { "SIGNNOW_USER_EMAIL": "${env:SIGNNOW_USER_EMAIL}", "SIGNNOW_PASSWORD": "${env:SIGNNOW_PASSWORD}", "SIGNNOW_API_BASIC_TOKEN": "${env:SIGNNOW_API_BASIC_TOKEN}" } } } } ``` **STDIO (uvx — no local install):** ```json { "servers": { "signnow": { "command": "uvx", "args": ["--from", "signnow-mcp-server", "sn-mcp", "serve"], "env": { "SIGNNOW_USER_EMAIL": "${env:SIGNNOW_USER_EMAIL}", "SIGNNOW_PASSWORD": "${env:SIGNNOW_PASSWORD}", "SIGNNOW_API_BASIC_TOKEN": "${env:SIGNNOW_API_BASIC_TOKEN}" } } } } ``` **HTTP (remote or Docker):** ```json { "servers": { "signnow": { "type": "http", "url": "http://localhost:8000/mcp" } } } ``` Then open Chat → **Agent mode**, enable the **signnow** tools, and use them in prompts. Note: The same configuration applies in Cursor — add it under MCP settings (STDIO or HTTP). For STDIO, you can also use `uvx` as shown above. ### Claude Desktop Use Desktop Extensions or the manual MCP config (Developer → Edit config). Steps: 1. Open Claude Desktop → Developer → Edit config 2. Add a new server entry under `mcpServers` 3. Save and restart Claude Desktop Examples: **STDIO (local install):** ```json { "mcpServers": { "signnow": { "command": "sn-mcp", "args": ["serve"], "env": { "SIGNNOW_USER_EMAIL": "${env:SIGNNOW_USER_EMAIL}", "SIGNNOW_PASSWORD": "${env:SIGNNOW_PASSWORD}", "SIGNNOW_API_BASIC_TOKEN": "${env:SIGNNOW_API_BASIC_TOKEN}" } } } } ``` **STDIO (uvx — no local install):** ```json { "mcpServers": { "signnow": { "command": "uvx", "args": ["--from", "signnow-mcp-server", "sn-mcp", "serve"], "env": { "SIGNNOW_USER_EMAIL": "${env:SIGNNOW_USER_EMAIL}", "SIGNNOW_PASSWORD": "${env:SIGNNOW_PASSWORD}", "SIGNNOW_API_BASIC_TOKEN": "${env:SIGNNOW_API_BASIC_TOKEN}" } } } } ``` **HTTP (remote or Docker):** ```json { "mcpServers": { "signnow": { "type": "http", "url": "http://localhost:8000/mcp" } } } ``` Then enable the server in Claude’s chat and start using the tools. ### Glama (hosted MCP) Deploy and run this server on Glama with minimal setup: Steps: 1. Open the server page on Glama: [sn-mcp-server on Glama](https://glama.ai/mcp/servers/@mihasicehcek/sn-mcp-server) 2. Click the red "Deploy Server" button 3. In environment variables, provide: - `SIGNNOW_USER_EMAIL` - `SIGNNOW_PASSWORD` - `SIGNNOW_API_BASIC_TOKEN` - (other variables can be left as defaults) 4. Create an access token in Glama and copy the endpoint URL. It will look like: ``` https://glama.ai/endpoints/{someId}/mcp?token={glama-mcp-token} ``` Use this HTTP MCP URL in any client that supports HTTP transport (e.g., VS Code/Cursor JSON config or Claude Desktop HTTP example above). ### MCP Inspector (testing) Great for exploring tools & schemas visually. ```bash # Start Inspector (opens UI on localhost) npx @modelcontextprotocol/inspector # Connect (STDIO): run your server locally and attach sn-mcp serve # Or connect (HTTP): use http://localhost:8000/mcp ``` You can list tools, call them with JSON args, and inspect responses. --- ## Tools Each tool is described concisely; use an MCP client (e.g., Inspector) to view exact JSON schemas. * **`list_all_templates`** — List templates & template groups with simplified metadata. Supports `limit`/`offset` pagination (default: 50 items per page). * **`list_contacts`** — Search CRM contacts by name, email, or phone. Returns id, email, first/last name, and company. Use before `send_invite` to resolve a recipient's email address by their name. Supports `per_page` (default 15, max 100). * **`list_documents`** — Browse your documents, document groups and statuses. Supports `limit`/`offset` pagination (default: 50 items per page). * **`create_from_template`** — Make a document or a group from a template/group. * **`create_template`** — Convert a document or document group into a reusable template for signing. * **`send_invite`** — Email invites (documents or groups), ordered recipients supported. Auto-detects freeform documents (no fields) — omit `role` for freeform recipients. Pass `self_sign=True` (with no `orders`) to sign the document yourself: the tool resolves your email server-side and returns a `SendInviteResponse` whose optional `link` field holds a ready-to-open signing link (also populated when a freeform recipient email matches the authenticated user). For template/template group it auto-creates document/document group first. * **`create_embedded_invite`** — Embedded signing session without email delivery for documents/groups/templates. For template/template group it auto-creates document/document group first. * **`create_embedded_sending`** — Embedded “sending/management” experience for documents/groups/templates. For template/template group it auto-creates document/document group first. * **`create_embedded_editor`** — Embedded editor link to place/adjust fields for documents/groups/templates. For template/template group it auto-creates document/document group first. * **`send_invite_from_template`** — One-shot: create from template and invite. * **`create_embedded_sending_from_template`** — One-shot: template → embedded sending. * **`create_embedded_editor_from_template`** — One-shot: template → embedded editor. * **`create_embedded_invite_from_template`** — One-shot: template → embedded signing. * **`get_invite_status`** — Current invite status/steps for document or group. Covers field invites and freeform invites (field path preferred when both exist). Response includes `invite_mode` (`field` or `freeform`). For freeform document groups, signer emails come from the group `documents` list (`signature_requests`). * **`get_document_download_link`** — Direct download link (merged output for groups). * **`get_signing_link`** — Get signing link for a document or document group. * **`get_document`** — Normalized document/group structure with field values, plus the folder the entity is stored in (`folder_id`/`folder_name`) at v3.0. * **`update_document_fields`** — Prefill text fields in individual documents. * **`upload_document`** — Upload a file from a local file path (`file_path`), public URL (`file_url`), or MCP resource attachment (`resource_uri`). Set `kind='template'` (default `'document'`) to store it as a reusable template instead of a regular document (the returned `document_id` is then a template ID and `next_steps` switch to the template follow-ups). For `file_path`, the resolved path must stay within the configured safe base directory (by default, the user's home directory); paths outside that base fail validation. Supported: PDF, DOC, DOCX, PNG, JPG, JPEG. Max 40 MB. Returns `document_id`, `filename`, `source`. * **`send_invite_reminder`** — Send a signing reminder to pending signers on a document or document group. * **`cancel_invite`** — Cancel all active (pending) signing invites on a document or document group. Auto-detects entity type and invite type (field vs freeform). Returns status: `cancelled`, `completed` (already done), or `invite_not_sent`. * **`update_invite_recipient`** — Replace the signing recipient on a pending field invite. Finds the pending invite for the current signer and swaps in a new email. Supports both documents and document groups. Only field invites — freeform/embedded are unsupported. * **`view_document`** — Generate a read-only embedded view link for a document or document group. In MCP Apps-compatible clients the document renders inline; in other hosts the link is returned as a clickable URL. * **`rename_entity`** — Rename a document, document group, template, or template group. Auto-detects entity type when not provided. * **`signnow_skills`** — Query the bundled SignNow skill library. Omit `skill_name` to list all available skills with descriptions; provide `skill_name` (e.g. `signnow101`) to fetch the full Markdown body. Use `signnow101` to learn SignNow entity types, invite types, and tool mappings. * List mode example: `{"skills": [{"name": "signnow101", "description": "SignNow 101 concepts reference... (description truncated for brevity)"}]}` * Fetch mode example: `{"name": "signnow101", "body": "# SignNow 101 — Concepts Reference\n..."}` > Tip: Start with `signnow_skills` (no arguments) to discover available skills, then `list_all_templates` → `create_from_template` → `create_embedded_*` / `send_invite`, then `get_invite_status` and `get_document_download_link`. --- ## FAQ / tips * **STDIO vs Docker?** Prefer **STDIO** for local dev; inside Docker, use **HTTP**. * **Sandbox vs production?** Start with SignNow’s sandbox/dev credentials; production requires proper OAuth and persistent RSA private key. * **Where do I see exact tool schemas?** Use **MCP Inspector** or your client’s “tool details” view. * **Where are examples?** See `examples/` in this repo for starter integrations. --- ## Examples The `examples/` directory contains working examples of how to integrate the SignNow MCP Server with popular AI agent frameworks: - **[LangChain](examples/langchain/langchain_example.py)** - Integration with LangChain agents using `langchain-mcp-adapters` - **[LlamaIndex](examples/llamaindex/llamaindex_example.py)** - Integration with LlamaIndex agents using `llama-index-tools-mcp` - **[SmolAgents](examples/smolagents/stdio_demo.py)** - Integration with SmolAgents framework using native MCP support Each example demonstrates how to: - Start the MCP server as a subprocess - Convert MCP tools to framework-specific tool formats - Create agents that can use SignNow functionality - Handle environment variable configuration To run an example: ```bash # Make sure you have the required dependencies installed pip install langchain-openai langchain-mcp-adapters # for LangChain example pip install llama-index-tools-mcp # for LlamaIndex example pip install smolagents # for SmolAgents example # Set up your .env file with SignNow credentials and LLM configuration # Then run the example python examples/langchain/langchain_example.py python examples/llamaindex/llamaindex_example.py python examples/smolagents/stdio_demo.py ``` --- ## Useful resources ### Sample apps Explore ready-to-use sample apps to quickly test preparing, signing, and sending documents from your software using the SignNow API. Try the [sample apps](https://docs.signnow.com/docs/signnow/sample-apps). ### API documentation Find technical details on SignNow API requests, parameters, code examples, and possible errors. Learn more about the API functionality in detailed guides and use cases. Read the [API documentation](https://docs.signnow.com/docs/signnow/welcome). ### SignNow API Helper MCP Connect your AI to access API docs, generate code for complex signing workflows, and troubleshoot integration errors automatically. [Access the API Helper MCP](https://github.com/signnow/sn-api-helper-mcp) --- ## License MIT — see [LICENSE.md](./LICENSE.md). --- **About** SignNow MCP Server — maintained by the SignNow team. Issues and contributions welcome via GitHub pull requests. ---