Developers

Umovi integration platform

MCP OAuth

Delegated authorization code flow, PKCE, discovery metadata and user scopes.

MCP uses delegated OAuth for an Umovi user. This is different from the REST Integration API's provider-scoped client_credentials flow.

Discovery

The MCP server publishes protected-resource metadata at:

https://u-agent.m-cloud.pl/.well-known/oauth-protected-resource
https://u-agent.m-cloud.pl/.well-known/oauth-protected-resource/mcp

It points clients to the Umovi authorization server, which is the Umovi API origin:

https://u-api.m-cloud.pl/.well-known/oauth-authorization-server

Sign-in and consent pages are shown on the Umovi auth portal; the authorization endpoint redirects the user there.

Clients should use discovery metadata instead of hardcoding authorization, token, registration, revocation or JWKS endpoints.

Flow

  1. The MCP client discovers protected-resource and authorization-server metadata.
  2. A public client can register through Dynamic Client Registration when required by the host.
  3. The user is redirected to Umovi authorization with an OAuth resource indicator and PKCE S256 challenge.
  4. The user signs in and approves requested scopes.
  5. The client exchanges the authorization code for access and refresh tokens.
  6. The gateway validates the token signature, issuer and audience, then checks tool scopes. Protected booking/account operations also enforce the token’s resource binding in Umovi.

Public clients use token_endpoint_auth_method: none; there is no distributable client secret.

Resource and token lifecycle

Use the exact resource value returned by protected-resource metadata in authorization and token requests. In this development environment it is https://u-agent.m-cloud.pl, whereas the MCP transport endpoint ends in /mcp. These are different values.

Authorization codes are single-use and valid for five minutes. Access tokens expire after 15 minutes (expires_in: 900). Refresh tokens expire after 30 days and rotate on use: persist the replacement token atomically and serialize refresh requests. A consumed, invalid or expired refresh token returns invalid_grant; reconnect when no valid refresh token remains. Revocation invalidates the submitted refresh token; do not assume an already issued access token disappears immediately.

Scopes

ScopeAllows
bookings:readList bookings, details and booking conversations.
bookings:writeCreate, confirm, repeat, reschedule, cancel and message within bookings.
places:readList saved places.
places:writeSave or remove places.

repeat_booking and reschedule_booking_to_first_available require both bookings:read and bookings:write. check_availability and find_next_available_slot have a public path, but supplying rescheduleBookingId requires bookings:write. Read the required scope combinations from each tool descriptor.

Provider discovery, public profiles and ordinary availability do not require delegated user authorization.

The server can return a WWW-Authenticate challenge describing missing scopes. A protected tools/call can also return isError: true with _meta["mcp/www_authenticate"], structuredContent.authRequired: true and requiredScopes. Inspect the MCP result even when the HTTP request succeeds. Clients should request incremental authorization rather than asking for every permission at first connection.