Security

How the Unduit API MCP server protects credentials, authenticates requests, and manages tokens.

Authentication layers

Layer 1 — MCP OAuth

All MCP requests require a valid OAuth 2.1 bearer token with the mcp:tools scope. Unauthenticated MCP requests are rejected before any tool handler runs.

Layer 2 — Unduit API credentials

During first-time OAuth authorization, Unduit API credentials are collected via a secure browser onboarding form and mapped to your OAuth principal. They are stored encrypted and never returned to the AI client.

Layer 3 — Unduit bearer token

When a tool executes, the MCP server obtains or refreshes a cached Unduit API bearer token using the stored credentials. Tokens are not fetched on every request — they are cached until near expiry with per-credential concurrency locks.

What is never exposed to AI clients

client_id or client_secret in tool arguments
Unduit API bearer tokens
Other users' credential mappings
Encrypted credential storage keys

OAuth scopes

Scope	Purpose
mcp:tools	Required to invoke MCP tools
unduit:credentials:write	Required for credential onboarding during OAuth authorization
unduit:credentials:admin	Optional — allows admin credential update via PUT /oauth/credentials

Credential storage

Credentials are stored in MongoDB, mapped by OAuth principal ID
Secrets are encrypted at rest using CREDENTIAL_ENCRYPTION_KEY in production
Token metadata (expiry, refresh status) is stored per credential identity

Updating credentials

To rotate Unduit API credentials for an already-mapped OAuth principal:

Re-authorize with update_credentials=true or prompt=login
Or use PUT /oauth/credentials with an admin-scoped bearer token

Environment isolation

Use the production MCP server URL that matches your Unduit API environment.