@agentmailbox/mcp-auth

OAuth2 Client Credentials wrapper for MCP servers. Enables M2M (machine-to-machine) authentication with AgentMailbox.

Installation

No installation required! Use npx to run directly:

npx @agentmailbox/mcp-auth <mcp-url> <token-endpoint> [scope]

Usage with Claude Desktop

Add to your claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "agentmail": {
      "command": "npx",
      "args": [
        "-y",
        "@agentmailbox/mcp-auth",
        "https://mcp.agentmailbox.to/tenant/YOUR_TENANT/mailbox/YOUR_MAILBOX",
        "https://auth.agentmailbox.to/oauth2/token",
        "mcp-api/email.full"
      ],
      "env": {
        "MCP_OAUTH_CLIENT_ID": "your-client-id",
        "MCP_OAUTH_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Replace:

• YOUR_TENANT - Your AgentMailbox tenant codename (e.g., peach)
• YOUR_MAILBOX - The mailbox username (e.g., admin)
• your-client-id - Your OAuth2 Client ID from the credentials page
• your-client-secret - Your OAuth2 Client Secret

Arguments

| Argument | Required | Description | |----------|----------|-------------| | mcp-url | Yes | The MCP server URL | | token-endpoint | Yes | The OAuth2 token endpoint | | scope | No | OAuth2 scope (default: mcp-api/email.full) |

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | MCP_OAUTH_CLIENT_ID | Yes | Your OAuth2 client ID | | MCP_OAUTH_CLIENT_SECRET | Conditional | Your OAuth2 client secret (or use file-based secret) | | MCP_OAUTH_CLIENT_SECRET_FILE | Conditional | Path to file containing client secret (more secure) | | MCP_DISABLE_CERT_PINNING | No | Set to "true" to disable certificate pinning (for corporate proxies) | | MCP_DEBUG | No | Set to "true" to enable debug logging (never logs secrets) |

Note: Either MCP_OAUTH_CLIENT_SECRET or MCP_OAUTH_CLIENT_SECRET_FILE must be provided.

Using File-Based Secrets (Recommended for Production)

For enhanced security, store your client secret in a file instead of an environment variable:

# Create a secret file with restricted permissions (avoids shell history)
read -rs SECRET && printf '%s' "$SECRET" > ~/.agentmail-secret && unset SECRET
chmod 600 ~/.agentmail-secret

Then configure:

{
  "env": {
    "MCP_OAUTH_CLIENT_ID": "your-client-id",
    "MCP_OAUTH_CLIENT_SECRET_FILE": "/Users/you/.agentmail-secret"
  }
}

Security Features

This package implements several security measures:

| Feature | Description | |---------|-------------| | HTTPS Enforcement | All endpoints must use HTTPS (localhost allowed for development) | | Certificate Pinning | SPKI pinning for AgentMailbox domains (Amazon Root CAs) | | Environment Isolation | Child processes receive minimal environment variables | | File-Based Secrets | Option to read secrets from files instead of environment variables | | Response Size Limits | Prevents memory exhaustion from malicious responses (100KB max) | | Token Validation | Validates JWT token format before use | | Error Sanitization | Removes sensitive data from error messages | | Pinned Dependencies | Uses pinned version of mcp-remote | | Exponential Backoff | Automatic retries with jitter to prevent thundering herd | | Security Headers | Advisory checks for HSTS and X-Content-Type-Options (logs warnings in debug mode) |

Certificate Pinning

Certificate pinning is enabled by default for AgentMailbox domains (auth.agentmailbox.to, mcp.agentmailbox.to). This helps mitigate many MITM scenarios by validating that certificates are signed by expected root CAs.

If you're behind a corporate proxy that performs TLS inspection, you may need to disable pinning:

{
  "env": {
    "MCP_DISABLE_CERT_PINNING": "true"
  }
}

Warning: Only disable certificate pinning if you understand the security implications.

Troubleshooting

Enable debug logging to diagnose connection issues:

{
  "env": {
    "MCP_DEBUG": "true"
  }
}

Debug logs are written to stderr and include timestamps. Sensitive data (tokens, secrets) is never logged.

How It Works

1. Reads client credentials from environment variables or secret file
2. Fetches an OAuth2 access token using the Client Credentials flow (with automatic retries)
3. Validates the token response (size limits, JWT format, security headers)
4. Passes the token to mcp-remote via environment variable
5. Forwards all MCP communication to the AgentMailbox server

Requirements

• Node.js 18 or later
• mcp-remote (installed automatically via npx)

License

MIT