signdocs

SignDocs Brasil — MCP Server

A Model Context Protocol server for the SignDocs Brasil e-signature API. It lets MCP-capable AI clients (Claude Desktop, Claude Code, Cursor, …) create signing sessions, manage multi-signer envelopes, upload/download documents, verify signatures, and manage webhooks — the same action catalog as the official n8n, Zapier, and Make.com integrations.

It is a thin adapter over the official @signdocs-brasil/api SDK, which owns OAuth2 token exchange, caching, retries, and error handling.

Install

npm install -g @signdocs-brasil/mcp-server   # or run on demand with npx

Credentials

Create an API credential in the SignDocs dashboard (app.signdocs.com.br → API) and expose it as environment variables:

Variable	Required	Default	Notes
SIGNDOCS_CLIENT_ID	yes	—	OAuth2 client id
SIGNDOCS_CLIENT_SECRET	yes	—	OAuth2 client secret
SIGNDOCS_ENVIRONMENT	no	hml	hml (staging) or production
SIGNDOCS_BASE_URL	no	derived	override the resolved base URL
SIGNDOCS_SCOPES	no	full set	space-separated scope override

Start in hml. HML data expires after ~7 days and is safe for testing. Switch to production only when you intend to create real, legally-binding signatures.

Connect an AI client

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "signdocs": {
      "command": "npx",
      "args": ["-y", "@signdocs-brasil/mcp-server"],
      "env": {
        "SIGNDOCS_CLIENT_ID": "your_client_id",
        "SIGNDOCS_CLIENT_SECRET": "your_client_secret",
        "SIGNDOCS_ENVIRONMENT": "hml"
      }
    }
  }
}

Claude Code:

claude mcp add signdocs \
  -e SIGNDOCS_CLIENT_ID=your_client_id \
  -e SIGNDOCS_CLIENT_SECRET=your_client_secret \
  -e SIGNDOCS_ENVIRONMENT=hml \
  -- npx -y @signdocs-brasil/mcp-server

Tools

Tool	Action	Safety
create_signing_session	Create single-signer session, returns signingUrl	⚠️ binding + quota
get_signing_session_status	Poll session status	read
get_signing_session	Full session bootstrap	read
list_signing_sessions	List by status	read
cancel_signing_session	Cancel a session	⚠️ irreversible
resend_signing_session_otp	Resend OTP	write
create_envelope	Multi-signer envelope	⚠️ binding + quota
get_envelope	Envelope details	read
add_session_to_envelope	Add a signer, returns signingUrl	⚠️ binding + quota
get_envelope_combined_stamp	Combined stamped PDF URL	read
upload_document	Attach a PDF to a transaction	write
download_document	Presigned download URLs	read
list_transactions	Search/list transactions	read
get_transaction	Transaction details	read
cancel_transaction	Cancel a transaction	⚠️ irreversible
get_evidence	Cryptographic evidence	read
verify_evidence	Public evidence verification	read
verify_envelope	Public envelope verification	read
verify_document	Detect signatures in a PDF	⚠️ PROD-only + quota
register_webhook / list_webhooks / delete_webhook / test_webhook	Webhook management	mixed

⚠️ tools carry destructiveHint annotations and a warning in their description so compliant clients prompt the human before invoking them. Annotations are only hints — review your client's auto-approval settings.

Not yet exposed

Trust sessions (/v1/trust-sessions) and resend-invite are not in @signdocs-brasil/api v1.6.1 yet; they'll be added when the SDK supports them. Digital ICP-Brasil A1 signing runs through the lower-level transaction/advance flow rather than a hosted-session profile.

Resources

The server exposes grounding resources the model can read on demand:

• signdocs://quickstart — the minimal signing flow + safety notes
• signdocs://policy-profiles — valid policyProfile values and CUSTOM steps
• signdocs://webhook-events — all subscribable event types

Remote HTTP transport (multi-tenant)

The same tools are also served over Streamable HTTP so a single deployment can serve many AI agents/tenants — each authenticates per session with its own SignDocs credentials (no shared secret baked into the server).

npm run start:http        # or: signdocs-mcp-http   (listens on PORT, default 3000)
# or containerized:
docker build -t signdocs-mcp . && docker run -p 3000:3000 signdocs-mcp

Endpoint: POST /mcp (Streamable HTTP). Auth is required on the MCP initialize request, via the Authorization header:

• Authorization: Bearer <token> — a SignDocs OAuth2 access token (from /oauth2/token), passed straight through to the API.
• Authorization: Basic base64(clientId:clientSecret) — the server runs the client_credentials exchange for you.
• X-SignDocs-Client-Id + X-SignDocs-Client-Secret — the same client credentials as two plain headers (no base64), for header-only clients that can't transform values.

Pick the environment per session with X-SignDocs-Environment: hml|production (defaults to the server's configured default).

The server behaves as an OAuth 2.0 Resource Server: it serves GET /.well-known/oauth-protected-resource (RFC 9728, pointing at the SignDocs authorization server) and answers an unauthenticated initialize with 401 + WWW-Authenticate. The SignDocs API remains the authoritative token validator. GET /healthz is an unauthenticated health probe.

Example client config (Bearer):

{
  "mcpServers": {
    "signdocs-remote": {
      "type": "http",
      "url": "https://your-host.example/mcp",
      "headers": {
        "Authorization": "Bearer <signdocs_access_token>",
        "X-SignDocs-Environment": "hml"
      }
    }
  }
}

Server env vars: PORT, HOST, SIGNDOCS_ENVIRONMENT (default env), MCP_PUBLIC_URL (for resource metadata behind a proxy), MCP_CORS_ORIGIN, MCP_DNS_REBINDING_PROTECTION=true + MCP_ALLOWED_HOSTS / MCP_ALLOWED_ORIGINS (recommended in production).

Sessions are held in process memory, so run a single instance or use sticky routing. For multi-instance/serverless, front it with sticky sessions or swap the session map for a shared store + EventStore (resumability). Deploying onto the existing external-api Lambda + API Gateway as a NestedStack is the intended production path.

AWS Lambda

For serverless hosting, @signdocs-brasil/mcp-server/lambda exports createLambdaHandler — an API Gateway HTTP API v2 handler that runs the MCP transport statelessly (one server per invocation, no session store), with the same Bearer/Basic auth. SignDocs hosts this on mcp-hml.signdocs.com.br / mcp.signdocs.com.br.

import { createLambdaHandler } from '@signdocs-brasil/mcp-server/lambda';
export const handler = createLambdaHandler({ defaultEnvironment: 'hml' });

Development

npm install
npm run build      # tsc → dist/
npm test           # vitest (pure unit tests, no network)
npm run inspect    # build + launch MCP Inspector against the stdio server

Roadmap

• v0.1: local stdio server, full tool catalog, env credentials.
• v0.2 (this release): remote Streamable-HTTP transport with per-session, per-tenant auth (Bearer passthrough or Basic client-credentials) and OAuth Resource Server discovery. Tool layer is shared between both transports.
• Next: deploy the HTTP transport onto external-api (Lambda + API Gateway NestedStack); optional edge JWT validation + shared-store sessions for horizontal scale.