Skip to content
Seal
Esc
↑↓navigate↵open⌘Jpreview
On this page

MCP Authentication

Configure OAuth authentication for the Seal MCP server

MCP Authentication

The Seal MCP server uses OAuth 2.0 via Seal’s own authorization server (Better-Auth) for secure authentication. This guide walks you through configuring OAuth access for AI assistants.

Authentication Flow

  1. Authorization Request: MCP client performs OAuth 2.0 (with dynamic client registration) and redirects to Seal’s authorization/sign-in page
  2. User Consent: You sign in with your Seal account, authorize access, and select an organization
  3. Authorization Code: Seal’s authorization server returns an authorization code to the MCP client
  4. Token Exchange: MCP client exchanges the code for an access token (a JWT)
  5. API Access: MCP client uses the access token for all API requests

Claude Desktop Setup

Add Seal to your Claude Desktop configuration file:

macOS

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "seal": {
      "url": "https://mcp.seal.nyc",
      "auth": {
        "type": "oauth",
        "authorizationUrl": "https://mcp.seal.nyc/.well-known/oauth-authorization-server"
      }
    }
  }
}

Windows

Edit %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "seal": {
      "url": "https://mcp.seal.nyc",
      "auth": {
        "type": "oauth",
        "authorizationUrl": "https://mcp.seal.nyc/.well-known/oauth-authorization-server"
      }
    }
  }
}

Linux

Edit ~/.config/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "seal": {
      "url": "https://mcp.seal.nyc",
      "auth": {
        "type": "oauth",
        "authorizationUrl": "https://mcp.seal.nyc/.well-known/oauth-authorization-server"
      }
    }
  }
}

First-Time Authorization

  1. Restart Claude Desktop after updating configuration
  2. Trigger MCP: Ask Claude to interact with Seal (e.g., “List my documents”)
  3. Authorize: Claude opens browser for authorization
  4. Sign In: Sign in to your Seal account if not already signed in
  5. Select Organization: Choose which organization to connect
  6. Grant Access: Click “Authorize” to grant Claude access
  7. Return to Claude: Browser redirects back to Claude Desktop

OAuth Scopes

The MCP server requests full API access with all scopes:

  • seal:documents:read - Read documents
  • seal:documents:write - Create, update, delete documents
  • seal:templates:read - Read templates
  • seal:templates:write - Create, update, delete templates
  • seal:recipients:read - Read recipients
  • seal:recipients:write - Manage recipients
  • seal:signatures:read - Read signatures and audit trails

Token Management

Token Storage

OAuth tokens are stored securely by the MCP client (Claude Desktop):

  • macOS: Keychain
  • Windows: Credential Manager
  • Linux: Secret Service API

Token Refresh

Access tokens expire after 1 hour. The MCP client automatically refreshes tokens using the refresh token.

Token Revocation

Revoke MCP access from your Seal account (Settings → Developer) or by disconnecting the integration in your MCP client:

  1. Sign in to the Seal app and go to Settings → Developer
  2. Find the connected MCP integration
  3. Disconnect or revoke its access
  4. Alternatively, disconnect the integration directly in your MCP client

OAuth Endpoints

Authorization Server Metadata

GET https://mcp.seal.nyc/.well-known/oauth-authorization-server

Returns OAuth 2.0 server metadata including:

  • Authorization endpoint
  • Token endpoint
  • Supported grant types
  • Supported scopes

Protected Resource Metadata

GET https://mcp.seal.nyc/.well-known/oauth-protected-resource/mcp

Returns protected resource metadata including:

  • Resource server identifier
  • Required scopes
  • Token introspection endpoint

Security Considerations

What MCP Can Access

With your authorization, the MCP server can:

  • ✓ Read all documents in your selected organization
  • ✓ Create, update, and delete documents
  • ✓ Manage recipients and send documents
  • ✓ Access templates and signatures
  • ✓ View audit trails

What MCP Cannot Access

The MCP server cannot:

  • ✗ Access other organizations you belong to
  • ✗ Change organization settings
  • ✗ Manage billing or subscriptions
  • ✗ Access your Seal account settings
  • ✗ Impersonate you in the web application

Best Practices

  1. Review Permissions: Understand what access you’re granting
  2. Monitor Activity: Check audit trails for MCP actions
  3. Revoke When Done: Revoke access if you stop using MCP
  4. Use Separate Org: Consider using a separate organization for testing
  5. Report Issues: Report suspicious activity immediately

Troubleshooting

Authorization Fails

Problem: Browser doesn’t open or authorization fails

Solutions:

  1. Check Claude Desktop configuration syntax
  2. Ensure you’re signed in to Seal
  3. Try restarting Claude Desktop
  4. Check browser console for errors

Token Expired

Problem: “Token expired” error after some time

Solution: MCP client should auto-refresh. If it doesn’t:

  1. Revoke access from your Seal account (Settings → Developer) or disconnect the integration in your MCP client
  2. Re-authorize in Claude Desktop

Wrong Organization

Problem: MCP is connected to wrong organization

Solution:

  1. Revoke access from your Seal account (Settings → Developer) or disconnect the integration in your MCP client
  2. Re-authorize and select correct organization

Permission Denied

Problem: “Permission denied” errors for certain actions

Solution:

  1. Check your role in the organization
  2. Ensure you have required permissions
  3. Contact organization admin if needed

API Key Fallback

For stdio mode (local development), you can use API keys instead of OAuth:

{
  "mcpServers": {
    "seal": {
      "command": "node",
      "args": ["/path/to/mcp-server/dist/index.js"],
      "env": {
        "SEAL_API_KEY": "ak_your_api_key_here"
      }
    }
  }
}

Next Steps

Was this page helpful?