{
  "markdown": "# SignDocs Brasil — MCP Server\n\nA [Model Context Protocol](https://modelcontextprotocol.io) server for the\n**SignDocs Brasil** e-signature API. It lets MCP-capable AI clients (Claude\nDesktop, Claude Code, Cursor, …) create signing sessions, manage multi-signer\nenvelopes, upload/download documents, verify signatures, and manage webhooks —\nthe same action catalog as the official n8n, Zapier, and Make.com integrations.\n\nIt is a thin adapter over the official [`@signdocs-brasil/api`](https://www.npmjs.com/package/@signdocs-brasil/api)\nSDK, which owns OAuth2 token exchange, caching, retries, and error handling.\n\n## Install\n\n```bash\nnpm install -g @signdocs-brasil/mcp-server   # or run on demand with npx\n```\n\n## Credentials\n\nCreate an API credential in the SignDocs dashboard (app.signdocs.com.br → API)\nand expose it as environment variables:\n\n| Variable | Required | Default | Notes |\n|---|---|---|---|\n| `SIGNDOCS_CLIENT_ID` | yes | — | OAuth2 client id |\n| `SIGNDOCS_CLIENT_SECRET` | yes | — | OAuth2 client secret |\n| `SIGNDOCS_ENVIRONMENT` | no | `hml` | `hml` (staging) or `production` |\n| `SIGNDOCS_BASE_URL` | no | derived | override the resolved base URL |\n| `SIGNDOCS_SCOPES` | no | full set | space-separated scope override |\n\n> Start in `hml`. HML data expires after ~7 days and is safe for testing.\n> Switch to `production` only when you intend to create real, legally-binding\n> signatures.\n\n## Connect an AI client\n\n**Claude Desktop** (`claude_desktop_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"signdocs\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@signdocs-brasil/mcp-server\"],\n      \"env\": {\n        \"SIGNDOCS_CLIENT_ID\": \"your_client_id\",\n        \"SIGNDOCS_CLIENT_SECRET\": \"your_client_secret\",\n        \"SIGNDOCS_ENVIRONMENT\": \"hml\"\n      }\n    }\n  }\n}\n```\n\n**Claude Code**:\n\n```bash\nclaude mcp add signdocs \\\n  -e SIGNDOCS_CLIENT_ID=your_client_id \\\n  -e SIGNDOCS_CLIENT_SECRET=your_client_secret \\\n  -e SIGNDOCS_ENVIRONMENT=hml \\\n  -- npx -y @signdocs-brasil/mcp-server\n```\n\n## Tools\n\n| Tool | Action | Safety |\n|---|---|---|\n| `create_signing_session` | Create single-signer session, returns `signingUrl` | ⚠️ binding + quota |\n| `get_signing_session_status` | Poll session status | read |\n| `get_signing_session` | Full session bootstrap | read |\n| `list_signing_sessions` | List by status | read |\n| `cancel_signing_session` | Cancel a session | ⚠️ irreversible |\n| `resend_signing_session_otp` | Resend OTP | write |\n| `create_envelope` | Multi-signer envelope | ⚠️ binding + quota |\n| `get_envelope` | Envelope details | read |\n| `add_session_to_envelope` | Add a signer, returns `signingUrl` | ⚠️ binding + quota |\n| `get_envelope_combined_stamp` | Combined stamped PDF URL | read |\n| `upload_document` | Attach a PDF to a transaction | write |\n| `download_document` | Presigned download URLs | read |\n| `list_transactions` | Search/list transactions | read |\n| `get_transaction` | Transaction details | read |\n| `cancel_transaction` | Cancel a transaction | ⚠️ irreversible |\n| `get_evidence` | Cryptographic evidence | read |\n| `verify_evidence` | Public evidence verification | read |\n| `verify_envelope` | Public envelope verification | read |\n| `verify_document` | Detect signatures in a PDF | ⚠️ PROD-only + quota |\n| `register_webhook` / `list_webhooks` / `delete_webhook` / `test_webhook` | Webhook management | mixed |\n\n⚠️ tools carry `destructiveHint` annotations **and** a warning in their\ndescription so compliant clients prompt the human before invoking them.\nAnnotations are only hints — review your client's auto-approval settings.\n\n### Not yet exposed\nTrust sessions (`/v1/trust-sessions`) and `resend-invite` are not in\n`@signdocs-brasil/api` v1.6.1 yet; they'll be added when the SDK supports them.\nDigital ICP-Brasil A1 signing runs through the lower-level transaction/advance\nflow rather than a hosted-session profile.\n\n## Resources\n\nThe server exposes grounding resources the model can read on demand:\n\n- `signdocs://quickstart` — the minimal signing flow + safety notes\n- `signdocs://policy-profiles` — valid `policyProfile` values and CUSTOM steps\n- `signdocs://webhook-events` — all subscribable event types\n\n## Remote HTTP transport (multi-tenant)\n\nThe same tools are also served over **Streamable HTTP** so a single deployment\ncan serve many AI agents/tenants — each authenticates per session with its own\nSignDocs credentials (no shared secret baked into the server).\n\n```bash\nnpm run start:http        # or: signdocs-mcp-http   (listens on PORT, default 3000)\n# or containerized:\ndocker build -t signdocs-mcp . && docker run -p 3000:3000 signdocs-mcp\n```\n\n**Endpoint:** `POST /mcp` (Streamable HTTP). Auth is required on the MCP\n`initialize` request, via the `Authorization` header:\n\n- `Authorization: Bearer <token>` — a SignDocs OAuth2 access token (from\n  `/oauth2/token`), passed straight through to the API.\n- `Authorization: Basic base64(clientId:clientSecret)` — the server runs the\n  `client_credentials` exchange for you.\n- `X-SignDocs-Client-Id` + `X-SignDocs-Client-Secret` — the same client credentials\n  as two plain headers (no base64), for header-only clients that can't transform values.\n\nPick the environment per session with `X-SignDocs-Environment: hml|production`\n(defaults to the server's configured default).\n\nThe server behaves as an **OAuth 2.0 Resource Server**: it serves\n`GET /.well-known/oauth-protected-resource` (RFC 9728, pointing at the SignDocs\nauthorization server) and answers an unauthenticated `initialize` with `401` +\n`WWW-Authenticate`. The SignDocs API remains the authoritative token validator.\n`GET /healthz` is an unauthenticated health probe.\n\nExample client config (Bearer):\n\n```json\n{\n  \"mcpServers\": {\n    \"signdocs-remote\": {\n      \"type\": \"http\",\n      \"url\": \"https://your-host.example/mcp\",\n      \"headers\": {\n        \"Authorization\": \"Bearer <signdocs_access_token>\",\n        \"X-SignDocs-Environment\": \"hml\"\n      }\n    }\n  }\n}\n```\n\n**Server env vars:** `PORT`, `HOST`, `SIGNDOCS_ENVIRONMENT` (default env),\n`MCP_PUBLIC_URL` (for resource metadata behind a proxy), `MCP_CORS_ORIGIN`,\n`MCP_DNS_REBINDING_PROTECTION=true` + `MCP_ALLOWED_HOSTS` / `MCP_ALLOWED_ORIGINS`\n(recommended in production).\n\n> Sessions are held in process memory, so run a single instance or use sticky\n> routing. For multi-instance/serverless, front it with sticky sessions or swap\n> the session map for a shared store + EventStore (resumability). Deploying onto\n> the existing `external-api` Lambda + API Gateway as a NestedStack is the\n> intended production path.\n\n### AWS Lambda\n\nFor serverless hosting, `@signdocs-brasil/mcp-server/lambda` exports\n`createLambdaHandler` — an API Gateway HTTP API v2 handler that runs the MCP\ntransport **statelessly** (one server per invocation, no session store), with the\nsame Bearer/Basic auth. SignDocs hosts this on `mcp-hml.signdocs.com.br` /\n`mcp.signdocs.com.br`.\n\n```ts\nimport { createLambdaHandler } from '@signdocs-brasil/mcp-server/lambda';\nexport const handler = createLambdaHandler({ defaultEnvironment: 'hml' });\n```\n\n## Development\n\n```bash\nnpm install\nnpm run build      # tsc → dist/\nnpm test           # vitest (pure unit tests, no network)\nnpm run inspect    # build + launch MCP Inspector against the stdio server\n```\n\n## Roadmap\n\n- **v0.1:** local stdio server, full tool catalog, env credentials.\n- **v0.2 (this release):** remote Streamable-HTTP transport with per-session,\n  per-tenant auth (Bearer passthrough or Basic client-credentials) and OAuth\n  Resource Server discovery. Tool layer is shared between both transports.\n- **Next:** deploy the HTTP transport onto `external-api` (Lambda + API Gateway\n  NestedStack); optional edge JWT validation + shared-store sessions for\n  horizontal scale.\n",
  "bytes": 7755,
  "sha": "fcf407a67c48203661c3d104b2718c210bd909a4d09cb336bf604a9c1dcb5441",
  "repo_slug": "signdocsbrasil/signdocs-mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_br_com_signdocs_mcp_server_1defe981/readme"
}