Feature Request: OAuth2 Integration Support for Persistent Token Management

[jtmurphysr]

Feature Request: OAuth2 Integration Support for Persistent Token Management

Problem

The MCP server currently authenticates via a short-lived Webex developer bearer token (WEBEX_PUBLIC_WORKSPACE_API_KEY) that expires every 12 hours. This limits the server to interactive/demo use cases where a human is available to manually rotate the token.

Any production deployment — scheduled automation, long-running agents, CI/CD pipelines, unattended Docker services — cannot reliably use the server today because the token will expire mid-operation with no recovery path.

The README explicitly documents this limitation:

Webex Bearer tokens are short-lived. Your current token expires in 12 hours. To renew:

1. Visit: https://developer.webex.com/messaging/docs/api/v1/rooms/list-rooms

2. Login with your email

3. Copy the new bearer token

This is a manual process that doesn't scale.

Proposed Solution

Add support for Webex OAuth2 Integration authentication as an alternative to the static bearer token. This enables:

• 14-day access tokens (vs. 12-hour developer tokens)

• 90-day refresh tokens that auto-renew on use, enabling effectively perpetual operation

• Transparent token rotation — the server refreshes tokens before expiry without MCP client awareness

• Scoped permissions — Integrations define explicit OAuth scopes rather than inheriting the full user token scope

Auth Modes (Backward Compatible)

The implementation should support three auth modes, selected by which environment variables are present:

Mode | Env Vars | Token Lifetime | Use Case -- | -- | -- | -- Bearer (current) | WEBEX_PUBLIC_WORKSPACE_API_KEY | 12 hours | Dev/demo OAuth Integration | WEBEX_CLIENT_ID, WEBEX_CLIENT_SECRET, WEBEX_REFRESH_TOKEN | Perpetual (with refresh) | Production automation Bot Token | WEBEX_BOT_TOKEN | Non-expiring | Bot-scoped access

Existing deployments using WEBEX_PUBLIC_WORKSPACE_API_KEY should continue to work unchanged.

Scope

In Scope

• Token provider abstraction in lib/webex-config.js that selects auth mode based on env vars

• OAuth2 refresh middleware that intercepts 401 responses and rotates tokens transparently

• Encrypted local token storage (refresh token + current access token + expiry timestamp)

• A one-time setup command (npm run auth:setup or similar) that walks the user through the OAuth grant flow and stores the initial token pair

• Health check endpoint enhancement to report token status (mode, expiry, last refresh)

• Documentation for registering a Webex Integration at developer.webex.com

• Bot token pass-through support (non-expiring, no refresh needed)

• Unit tests for token lifecycle (refresh, expiry, fallback, error handling)

Out of Scope

• Multi-user / multi-tenant token management

• Web-based OAuth consent UI (the setup command handles the one-time grant)

• Changes to any of the 52 existing tool implementations

• Token encryption at rest beyond filesystem permissions (can be a follow-up)

Technical Notes

• The Webex token refresh endpoint is POST https://webexapis.com/v1/access_token with grant_type=refresh_token

• Access tokens expire in 14 days (1,209,600 seconds); refresh tokens in 90 days (7,776,000 seconds)

• Refreshing an access token resets the refresh token expiry timer, so continuous use means the refresh token never expires

• The existing lib/webex-config.js centralized config is the natural injection point

• All 52 tools use fetch with headers from the config — the abstraction should be transparent to them

Who This Helps

Anyone using this MCP server for:

• Scheduled/cron-driven automation against Webex data

• Long-running agentic workflows (Claude Desktop, Claude Code, custom agents)

• CI/CD pipelines that interact with Webex spaces

• Production Docker deployments (the server already has excellent containerization support)

Happy to contribute this via PR. Wanted to open the issue first to align on approach and get feedback on the auth mode design before writing code.

# Feature Request: OAuth2 Integration Support for Persistent Token Management

Problem

The MCP server currently authenticates via a short-lived Webex developer bearer token (WEBEX_PUBLIC_WORKSPACE_API_KEY) that expires every 12 hours. This limits the server to interactive/demo use cases where a human is available to manually rotate the token.

Any production deployment — scheduled automation, long-running agents, CI/CD pipelines, unattended Docker services — cannot reliably use the server today because the token will expire mid-operation with no recovery path.

The README explicitly documents this limitation:

Webex Bearer tokens are short-lived. Your current token expires in 12 hours. To renew:

1. Visit: https://developer.webex.com/messaging/docs/api/v1/rooms/list-rooms
2. Login with your email
3. Copy the new bearer token

This is a manual process that doesn't scale.

Proposed Solution

Add support for [Webex OAuth2 Integration](https://developer.webex.com/docs/integrations) authentication as an alternative to the static bearer token. This enables:

• 14-day access tokens (vs. 12-hour developer tokens)
• 90-day refresh tokens that auto-renew on use, enabling effectively perpetual operation
• Transparent token rotation — the server refreshes tokens before expiry without MCP client awareness
• Scoped permissions — Integrations define explicit OAuth scopes rather than inheriting the full user token scope

Auth Modes (Backward Compatible)

The implementation should support three auth modes, selected by which environment variables are present:

Mode	Env Vars	Token Lifetime	Use Case
Bearer (current)	WEBEX_PUBLIC_WORKSPACE_API_KEY	12 hours	Dev/demo
OAuth Integration	WEBEX_CLIENT_ID, WEBEX_CLIENT_SECRET, WEBEX_REFRESH_TOKEN	Perpetual (with refresh)	Production automation
Bot Token	WEBEX_BOT_TOKEN	Non-expiring	Bot-scoped access

Existing deployments using WEBEX_PUBLIC_WORKSPACE_API_KEY should continue to work unchanged.

Scope

In Scope

• Token provider abstraction in lib/webex-config.js that selects auth mode based on env vars
• OAuth2 refresh middleware that intercepts 401 responses and rotates tokens transparently
• Encrypted local token storage (refresh token + current access token + expiry timestamp)
• A one-time setup command (npm run auth:setup or similar) that walks the user through the OAuth grant flow and stores the initial token pair
• Health check endpoint enhancement to report token status (mode, expiry, last refresh)
• Documentation for registering a Webex Integration at developer.webex.com
• Bot token pass-through support (non-expiring, no refresh needed)
• Unit tests for token lifecycle (refresh, expiry, fallback, error handling)

Out of Scope

• Multi-user / multi-tenant token management
• Web-based OAuth consent UI (the setup command handles the one-time grant)
• Changes to any of the 52 existing tool implementations
• Token encryption at rest beyond filesystem permissions (can be a follow-up)

Technical Notes

• The Webex token refresh endpoint is POST https://webexapis.com/v1/access_token with grant_type=refresh_token
• Access tokens expire in 14 days (1,209,600 seconds); refresh tokens in 90 days (7,776,000 seconds)
• Refreshing an access token resets the refresh token expiry timer, so continuous use means the refresh token never expires
• The existing lib/webex-config.js centralized config is the natural injection point
• All 52 tools use fetch with headers from the config — the abstraction should be transparent to them

Who This Helps

Anyone using this MCP server for:

• Scheduled/cron-driven automation against Webex data
• Long-running agentic workflows (Claude Desktop, Claude Code, custom agents)
• CI/CD pipelines that interact with Webex spaces
• Production Docker deployments (the server already has excellent containerization support)

Happy to contribute this via PR. Wanted to open the issue first to align on approach and get feedback on the auth mode design before writing code.