zoom-mcp

Zoom MCP server built from the skeleton pattern with:

• Multi-user token management.

• Vault as the persistent secret store.

• Postgres as the persistent configuration store.

• Admin-gated mutation tools through MCP_ADMIN_AUTH_KEY.

• Dedicated Zoom tools plus generic full-coverage API execution.

• Query suggestion and schema discovery tooling for LLM workflows.

Architecture

Runtime components:

1. src/index.js: Starts stdio MCP transport.

2. src/http/index.js: Starts HTTP MCP transport with auth/rate controls.

3. src/bootstrap/runtime.js: Creates shared runtime dependencies.

4. src/services/vault.js: Persistent secret access in Vault.

5. src/services/configStore.js: Persistent config access in Postgres.

6. src/services/zoomTokenStore.js: User token + OAuth client persistence.

7. src/services/targetService.js: Zoom API and OAuth token refresh client.

8. src/mcp/server.js: MCP tool registration and auth gate enforcement.

9. src/config/zoomApiCatalog.js: Endpoint catalog for discovery/suggestions.

Core Guarantees

• Secrets are persisted in Vault, including user access/refresh tokens and OAuth client credentials.

• Configuration is persisted in Postgres, including non-secret token metadata and arbitrary user-scoped config keys.

• All user token operations are multi-user and scoped by userId.

• Mutating tools require authorizationKey when MCP_ADMIN_AUTH_KEY is configured.

• Full Zoom API coverage is available through zoom_api_request.

Tool Catalog

All tools return MCP text content with JSON:

{
  "ok": true,
  "status": 200,
  "data": {}
}

Error shape (isError=true):

{
  "ok": false,
  "status": 401,
  "error": "Unauthorized: invalid authorizationKey for mutating operation"
}

Read-only tools

• zoom_connection_info

• zoom_scope_info

• zoom_schema_discovery

• zoom_query_suggestion

• zoom_token_get_metadata

• zoom_oauth_client_get_metadata

• zoom_production_auth_env_readiness

• zoom_config_get

• zoom_config_list

• zoom_users_list

• zoom_user_get

• zoom_meetings_list

• zoom_meeting_get

• zoom_meeting_notes_get

• zoom_webinars_list

• zoom_recordings_list

• zoom_report_user_meetings

• zoom_phone_users_list

• zoom_phone_call_logs_list

• zoom_chat_channels_list

• zoom_chat_messages_list

• zoom_rooms_list

• zoom_room_get

Mutating tools (admin-gated when MCP_ADMIN_AUTH_KEY is set)

• zoom_token_upsert

• zoom_token_delete

• zoom_oauth_client_upsert

• zoom_seed_initial_oauth_vault_state

• zoom_production_auth_env_upsert

• zoom_bootstrap_production_auth

• zoom_token_refresh

• zoom_config_set

• zoom_config_delete

• zoom_meeting_create

• zoom_meeting_update

• zoom_meeting_delete

• zoom_webinar_create

• zoom_webinar_delete

• zoom_chat_channel_create

• zoom_api_request for POST|PUT|PATCH|DELETE

Tool Definition Quality Fields

zoom_query_suggestion returns toolSchemas with enriched metadata for each tool including:

• When the tool should and should not be used.

• Read-only, mutating, or high-risk classification.

• Required permissions and prerequisites.

• Environment-selection behavior.

• Parameter formats and constraints.

• Expected response shape.

• Common failure conditions.

• Recommended prerequisite and follow-up tools.

• Safety warnings for destructive operations.

• Short valid invocation examples.

Query Suggestion and Schema Discovery

Use these first in LLM workflows:

• zoom_query_suggestion: recommends tool execution order and safety checks.

• zoom_schema_discovery: searches endpoint catalog by category/method/path/text.

The catalog is broad and the fallback zoom_api_request tool provides full endpoint surface execution against Zoom REST APIs.

Multi-user Token Model

Vault secret path for user tokens:

• ${APP_NAME}/users/${normalizedUserId}/zoom/oauth/tokens

Stored fields:

• accessToken

• refreshToken

• tokenType

• scope

• expiresAt

• accountId

Postgres metadata key:

• zoom.oauth.token.meta

OAuth client secret path:

• ${APP_NAME}/zoom/oauth/client

Postgres metadata key:

• zoom.oauth.client.meta

Deployment Auth Setup With MCP Tools

These tools are designed for LLM-driven deployment preparation workflows:

1. Bootstrap all deployment auth setup in one call:

• zoom_bootstrap_production_auth

2. Seed initial OAuth client secret and per-user tokens in Vault:

• zoom_seed_initial_oauth_vault_state

3. Persist production MCP_ADMIN_AUTH_KEY and HTTP auth vars before deployment:

• zoom_production_auth_env_upsert

4. Validate readiness before rollout:

• zoom_production_auth_env_readiness

Recommended order for a new production environment:

1. Run zoom_bootstrap_production_auth for one-shot setup.

2. Run zoom_production_auth_env_readiness and confirm ready=true.

zoom_production_auth_env_upsert persists:

• Secrets in Vault path ${APP_NAME}/deployment/production/http-auth-secrets.

• Non-secret HTTP auth config in Postgres key deployment.production.http.auth (default user scope).

Environment Variables

Use .env.example as source of truth. Key groups:

• App and admin auth: APP_NAME, MCP_SERVER_NAME, MCP_ADMIN_AUTH_KEY

• User scope defaults: MCP_CONFIG_DEFAULT_USER_ID

• Postgres persistence: POSTGRES_*

• Vault persistence: VAULT_*

• Zoom API: ZOOM_API_BASE_URL, ZOOM_OAUTH_TOKEN_URL, ZOOM_API_TIMEOUT_MS

• HTTP transport and auth: MCP_HTTP_*

Local Development

1. Install dependencies:

npm ci

2. Start infrastructure and HTTP MCP:

docker compose up -d

3. Start stdio MCP mode:

npm run start:stdio

4. Run tests:

npm test

External Services Mode

Use docker-compose.external.yml for environments where Vault and Postgres are already provided.

• This is an app-only compose path.

• Requires external POSTGRES_* and VAULT_* values.

• Minimum required examples: POSTGRES_HOST, POSTGRES_PORT, POSTGRES_DB, POSTGRES_USER, POSTGRES_PASSWORD, VAULT_ADDR, and VAULT_TOKEN.

Security Notes

• Never place OAuth access/refresh tokens in Postgres.

• Keep MCP_ADMIN_AUTH_KEY enabled in non-local environments.

• Use least-privilege Zoom OAuth scopes per workload.

• For destructive endpoints, prefer dedicated tools and validate ids before execution.