Assinafy MCP — Client Reference

A hosted Model Context Protocol Streamable HTTP server for system-to-system integrations with the Assinafy electronic-signature platform. The MCP server is a thin, multi-tenant proxy in front of the public Assinafy REST API (https://api.assinafy.com.br/v1). Every request carries the caller's API key and account ID; no per-tenant state is stored on the MCP server itself.

• Endpoint: https://mcp.assinafy.com.br/mcp
• Transport: MCP Streamable HTTP (stateless)
• Protocol version: 2025-11-25
• Auth: per-request HTTPS headers (or per-call _meta / arguments.auth)

Endpoint methods

The /mcp endpoint accepts two HTTP methods:

| Method | Purpose | |---|---| | GET /mcp | Returns a small JSON manifest: server name, version, MCP protocol version, transport, statelessness, and the full list of registered tools (name, title, description, annotations). Useful for capability discovery, browser smoke tests, and uptime probes. | | POST /mcp | The JSON-RPC entry point for all MCP operations (initialize, tools/list, tools/call, etc.). |

GET /mcp sample:

curl -sS https://mcp.assinafy.com.br/mcp

{
  "name": "assinafy-mcp-server",
  "version": "0.1.0",
  "protocol": "2025-11-25",
  "transport": "streamable-http",
  "stateless": true,
  "status": "ok",
  "tools": [
    {
      "name": "assinafy_list_documents",
      "title": "List Documents",
      "description": "List documents in an Assinafy workspace with optional pagination and search.",
      "annotations": { "readOnlyHint": true, "openWorldHint": true, "title": "List Documents" }
    }
    // ... 39 more
  ]
}

The server runs in stateless mode: there is no initialize handshake to persist, no Mcp-Session-Id to track, and GET /mcp does not open an SSE stream — clients fire each tools/call as a self-contained POST with the required headers.

Required headers

Every POST must include the following headers:

| Header | Required | Notes | |---|---|---| | Content-Type: application/json | yes | JSON-RPC 2.0 payload. | | Accept: application/json, text/event-stream | yes | MCP returns each response as a single SSE message event over text/event-stream. | | MCP-Protocol-Version: 2025-11-25 | yes | Required by the MCP spec on every request to a Streamable HTTP server. | | X-Api-Key | yes | Your Assinafy API key. Matches the official Assinafy REST API auth header. | | X-Assinafy-Account-Id | yes | Your workspace (account) ID. | | X-Assinafy-Webhook-Secret | conditional | Only required for assinafy_verify_webhook_signature, and only when secret is not passed inline as a tool argument. |

Bearer-token authentication is not supported.

The public mcp.assinafy.com.br host sits behind Cloudflare; clients without a recognisable User-Agent header may be challenged. Standard SDKs and curl send one by default — urllib-style minimal clients should set one explicitly.

Per-call credentials (no HTTP headers)

Clients that cannot attach custom headers (most browser embeds, some hosted chat platforms) can supply the same three credentials per tools/call. The server checks, in order: HTTP headers → _meta → arguments.auth → arguments.assinafy → arguments.credentials.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "assinafy_list_documents",
    "_meta": {
      "api_key": "<ASSINAFY_API_KEY>",
      "account_id": "<ASSINAFY_ACCOUNT_ID>"
    },
    "arguments": {}
  }
}

Recognised keys (snake_case or camelCase): api_key / apiKey / x_api_key, account_id / accountId, webhook_secret / webhookSecret. Any tool that accepts an explicit account_id argument uses that value over the header/_meta value for the single call.

Calling tools

Every operation flows through standard JSON-RPC tools/call. The HTTP response body is one SSE frame containing the JSON-RPC result.

curl -sS -X POST https://mcp.assinafy.com.br/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2025-11-25' \
  -H "X-Api-Key: $ASSINAFY_API_KEY" \
  -H "X-Assinafy-Account-Id: $ASSINAFY_ACCOUNT_ID" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "assinafy_list_documents",
      "arguments": { "page": 1, "per_page": 20 }
    }
  }'

Raw response:

event: message
data: {"jsonrpc":"2.0","id":1,"result":{"content":[{"type":"text","text":"<JSON>"}],"structuredContent":{...}}}

For object-returning tools the result has both:

• result.content[0].text — the JSON payload as a string.
• result.structuredContent — the same payload as a JSON object.

For tools that return a bare array (e.g. assinafy_get_document_activities) the MCP SDK only populates result.content[0].text; clients should parse it with JSON.parse when they need the array. Plain-text results (delete confirmations, etc.) are returned only as content[0].text.

Failed tool calls return result.isError: true with a human-readable message in result.content[0].text:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "isError": true,
    "content": [{ "type": "text", "text": "API error 400: ..." }]
  }
}

The example payloads in the per-tool reference below show the structuredContent object (or content[0].text for plain-text / array results). The wrapping envelope is omitted for brevity.

Important: file upload requires server-side filesystem access

assinafy_upload_document reads the PDF directly from the MCP server's local filesystem using the supplied file_path. This works for self-hosted deployments (you control the path), but on the public hosted endpoint at https://mcp.assinafy.com.br/mcp a remote client cannot place a file where the server can read it.

Public hosted clients have two options:

1. Upload via the Assinafy REST API directly (POST /v1/accounts/{account_id}/documents) and then use the MCP tools (assinafy_get_document, assinafy_create_assignment, …) to drive the rest of the workflow.
2. Self-host this MCP server alongside whatever ingestion pipeline produces the PDF, so the server-side filesystem path is meaningful.

Every other tool works end-to-end against the public endpoint.

Document lifecycle quick reference

| Status | Meaning | |---|---| | uploading | File still being received. | | uploaded | File received, awaiting metadata extraction. | | metadata_processing | Backend extracting fields/pages. | | metadata_ready | Ready for signing setup. | | pending_signature | Assignment created; waiting on signers. | | expired | Assignment expired without completion. | | certificating | Final signing artifact is being generated. | | certificated | Fully signed; signed PDF + certificate page available. | | rejected_by_signer | A signer rejected the document. | | rejected_by_user | The sender cancelled the request. | | failed | Processing failed. |

assinafy_wait_document_ready returns when the document reaches any of metadata_ready, pending_signature, or certificated.

---

Tool reference

All 40 tools, organized by resource. Each entry lists arguments (verified against the input schema in tools/*.go) and the response shape observed against the live REST API. Where the underlying API enum is case-sensitive this is called out — Assinafy's API rejects "email" and accepts "Email".

Documents

assinafy_upload_document

Upload a PDF (max 25 MB) by server-side filesystem path. See the upload note above; only practical for self-hosted MCP deployments.

| Argument | Type | Required | Description | |---|---|---|---| | file_path | string | yes | Absolute path on the MCP server's filesystem. | | account_id | string | no | Override the account ID for this call. | | metadata | object | no | Arbitrary JSON metadata to attach to the document. |

Response (structuredContent):

{
  "resource": "document",
  "id": "2222bbbb2222bbbb2222bbbb2222",
  "account_id": "aaaa0000aaaa0000aaaa0000",
  "name": "sample_contract.pdf",
  "status": "uploaded",
  "artifacts": {
    "original": "https://api.assinafy.com.br/v1/documents/2222bbbb2222bbbb2222bbbb2222/download/original"
  },
  "pages": [],
  "created_at": "2026-05-11T23:25:38Z",
  "updated_at": "2026-05-11T23:25:38Z",
  "is_closed": false
}

Immediately after upload, status is usually uploaded or metadata_processing and pages is empty. Call assinafy_wait_document_ready to block until the backend finishes extracting page metadata.

assinafy_list_documents

| Argument | Type | Required | Description | |---|---|---|---| | page | int | no | 1-based page number. | | per_page | int | no | Results per page (max 100). | | search | string | no | Filter by document name. | | sort | string | no | Sort field; prefix - for descending (e.g. -created_at). | | account_id | string | no | Override account ID. |

Response:

{
  "data": [
    {
      "id": "1111aaaa1111aaaa1111aaaa111",
      "account_id": "aaaa0000aaaa0000aaaa0000",
      "name": "Sample Agreement.pdf",
      "status": "certificated",
      "is_closed": true,
      "created_at": "2025-03-13T14:24:20Z",
      "updated_at": "2025-03-13T14:26:51Z"
    }
  ],
  "meta": { "current_page": 1, "last_page": 2, "per_page": 3, "total": 4 }
}

assinafy_get_document

| Argument | Type | Required | |---|---|---| | document_id | string | yes |

Response (abridged — assignment.items is included when an assignment exists and contains the full field-placement data the signing UI uses):

{
  "resource": "document",
  "id": "1111aaaa1111aaaa1111aaaa111",
  "account_id": "aaaa0000aaaa0000aaaa0000",
  "name": "Sample Agreement.pdf",
  "status": "certificated",
  "is_closed": true,
  "signing_url": "https://app.assinafy.com.br/sign/1111aaaa1111aaaa1111aaaa111",
  "artifacts": {
    "original": "https://api.assinafy.com.br/v1/documents/.../download/original",
    "thumbnail": "https://api.assinafy.com.br/v1/documents/.../thumbnail",
    "certificated": "https://api.assinafy.com.br/v1/documents/.../download/certificated",
    "certificate-page": "https://api.assinafy.com.br/v1/documents/.../download/certificate-page",
    "bundle": "https://api.assinafy.com.br/v1/documents/.../download/bundle"
  },
  "assignment": {
    "id": "3333cccc3333cccc3333cccc333",
    "sender_email": "sender@example.com",
    "method": "collect",
    "expires_at": null,
    "message": null,
    "signers": [
      { "id": "4444dddd4444dddd4444dddd444", "full_name": "...", "email": "...", "has_accepted_terms": true }
    ],
    "copy_receivers": [],
    "items": [ /* per-page field placements with signer + display_settings */ ],
    "summary": {
      "signer_count": 1,
      "completed_count": 1,
      "signers": [ { "id": "...", "full_name": "...", "email": "...", "completed": true } ]
    },
    "signing_urls": [
      { "signer_id": "4444dddd4444dddd4444dddd444", "url": "https://app.assinafy.com.br/sign/...?email=..." }
    ]
  },
  "created_at": "2025-03-13T14:24:20Z",
  "updated_at": "2025-03-13T14:26:51Z"
}

The assignment.artifacts URLs follow the document's lifecycle: certificated / certificate-page / bundle only appear once the document reaches certificated.

assinafy_delete_document

Deletes the document (and any active assignment) in one call.

| Argument | Type | Required | |---|---|---| | document_id | string | yes |

Response (content[0].text):

Document deleted successfully

assinafy_get_document_activities

Chronological event log. Returns a bare JSON array in content[0].text (no structuredContent).

| Argument | Type | Required | |---|---|---| |