documenso-mcp

A team-scoped MCP server for Documenso, built with mcp-use. It lets ChatGPT and Claude list and inspect Documenso documents for a team the user chose, and will prepare and send them.

Users connect in one click: the assistant opens Documenso, the user signs in, picks a team and approves. No API token to copy, no second account. That works because Documenso itself is the OAuth server, through an OAuth 2.1 authorization server I added in a fork of Documenso.

Status (v0.3.0): read-only tools and the signing-status View, with Documenso OAuth. Tested in Claude and ChatGPT against the live demo, in Claude Code and the mcp-use Inspector, and end to end by scripts/check-oauth-flow.ts (20 checks) on both deployments. Drafting and sending come after. This is an independent project, not an official Documenso integration.

Live demo

Add either MCP URL as a custom connector in Claude or ChatGPT. Sign-ups on the demo Documenso are closed; demo accounts are available on request.

Related MCP server: SumoSign MCP Server

Tested in Claude and ChatGPT

One-click connection in real hosts against the live deployment: Documenso's consent page, then team-scoped tool calls, including a refused request for another team's document. Also tested in Claude Code and the mcp-use Inspector. All screenshots, how each host registered, revocation and what the tests found: docs/host-testing.md.

Connecting

1. Add the server as a connector in Claude or ChatGPT (https://<your-server>/mcp).

2. The host discovers Documenso from this server's metadata, registers itself, and opens Documenso.

3. Sign in to Documenso, choose the team, check the permissions, and click Allow access.

4. Ask for your documents. The assistant only ever sees the team you chose.

Tools

Signing-status View

In hosts that support MCP Apps, get-envelope-status renders a card with the status, a progress bar, what happens next, each recipient's state and a Refresh button. Refresh calls get-envelope-status again through the same signed-in, team-scoped path. The View changes nothing, and hosts without Views get the same information as text.

The View loads no external scripts, fonts, images or APIs, so it declares no extra CSP domains. Its bundle contains no server code (views/signing-status/).

How access works

• Documenso is the authorization server. This server's protected resource metadata points MCP clients at Documenso, which handles registration, sign-in, consent and tokens (ADR 0002).

• Every token is checked with Documenso before any tool code runs: it must be active and issued for this server (aud), otherwise the request gets HTTP 401. Results are cached for 30 seconds at most.

• Documenso enforces the rest on every API call: the team chosen at consent, the approved scopes, and the user's role in that team.

• This server stores nothing. No tokens, no database, no encryption keys.

Details, including revocation and known limitations: docs/auth.md.

Run locally

Requirements: Node 24 and the Documenso fork running locally (docs/local-backend.md).

1. In Documenso's .env, allow this server as an OAuth resource and restart Documenso:

   NEXT_PRIVATE_OAUTH_RESOURCES="http://localhost:3100/mcp"

2. Start this server:

   npm ci
   cp .env.example .env    # DOCUMENSO_URL=http://localhost:3000
   npm run dev

• MCP endpoint: http://localhost:3100/mcp

• Inspector: http://localhost:3100/mcp/inspector

Checks

npm run typecheck
npm test                  # 62 unit tests
npm run build             # server and View bundles

./scripts/check-auth-wiring.sh http://localhost:3100
node --env-file=.env.test.local scripts/check-oauth-flow.ts http://localhost:3100

• check-auth-wiring.sh needs no credentials. It checks the metadata, that signed-out clients can list tools and call documenso-health, and that every Documenso tool answers HTTP 401 with a challenge for missing, forged or wrong-kind tokens.

• check-oauth-flow.ts runs the real flow with two ordinary Documenso accounts (.env.test.example): discovery, registration, sign-in, consent, token exchange, every tool, team isolation between the two users, a token without the read scope (403), forged tokens (401), and revocation.

• CI runs typecheck, tests and the build on every pull request.

Deployment on Manufact or on your own server with Docker: docs/deploy.md.

Security notes

• Tokens that are not Documenso access tokens are refused before any network call; Documenso refresh tokens and API tokens are not accepted as access tokens.

• If Documenso cannot confirm a token, the request fails closed and nothing is cached.

• Documenso error bodies, which include stack traces and server paths in development, are never forwarded to the model (src/documenso/errors.ts).

• Documenso returns each recipient's signing token in envelope responses. Tools output only allowlisted fields, so signing tokens never reach the model (docs/api-map.md).

• Redirects from Documenso are refused, so a token is never sent to another host.

History

• v0.3.0: Documenso OAuth; Supabase sign-in and token linking removed (ADR 0002).

• v0.2.0: Supabase sign-in, then pasting a Documenso team API token; tested in Claude and ChatGPT (docs/host-testing.md).

License

MIT. The Documenso fork it works with is AGPL-3.0; this server only talks to it over HTTP.