MCP Client | Authorization

The MCP authorization specification (protocol version 2026-07-28) describes how a client gets an access token for a protected MCP server without any manual configuration. When MCPOptions.Authorization.Enabled is True and the server answers a request with HTTP 401 or 403, TsgcWSAPIClient_MCP discovers the authorization server, registers itself, opens the browser for the user login, gets the token and repeats the request with an Authorization: Bearer header. It works in both protocol eras over the HTTP transports.

This feature is different from MCPOptions.AuthenticationOptions.OAuth2, where you configure a token endpoint and a grant yourself. The authorization members are compiled only when OAuth2 support is enabled in the library (define SGC_OAUTH).

 

Flow

• Protected resource metadata: the client reads resource_metadata from the WWW-Authenticate header, or tries the well-known path of the endpoint and then the root. When several authorization servers are listed, the one equal to Issuer is used, otherwise the first.
• Authorization server metadata: tried in this order: oauth-authorization-server, openid-configuration with the path inserted, and the path followed by /.well-known/openid-configuration. The issuer of the metadata must be identical to the discovered issuer.
• Client registration: a pre-registered ClientId is used first. Otherwise, if the server supports client id metadata documents, ClientMetadataURL (an https URL) is sent as the client id. Otherwise, when AllowDynamicRegistration is True, the client registers with Dynamic Client Registration, sending application_type native for a loopback RedirectURL and web for any other.
• Authorization request: PKCE with S256 and the resource parameter (RFC 8707) set to the canonical URL of the MCP server. The client starts a local HTTP listener on RedirectURL and raises OnMCPAuthorizationURL with the URL the user must open. It waits up to Timeout seconds for the redirect.
• Issuer check: the iss parameter of the redirect (RFC 9207) must match the issuer, otherwise the flow stops.
• Token: the code is exchanged for a token and the original request is repeated. A request is authorized at most twice.
• Refresh: a token that expires in less than 30 seconds is refreshed before use. A 401 from the same issuer tries the refresh token before a new login.
• Step-up: a 403 with insufficient_scope starts a new authorization that requests the union of the current and the required scopes.

 

Credentials are kept per issuer, so a pre-registered client bound to one issuer is never sent to a different authorization server. Every failure is reported through OnError with a text that starts with MCP authorization:.

MCPOptions.Authorization

Property	Description
Enabled	Enables the automatic authorization. Default False.
ClientId	Client id of a pre-registered client. Optional.
ClientSecret	Client secret of a pre-registered confidential client. Optional.
Issuer	Preferred authorization server when the resource lists several. Optional.
ClientMetadataURL	https URL of the client id metadata document of your application. Optional.
AllowDynamicRegistration	Allows Dynamic Client Registration when no other registration applies. Default True.
ClientName	Client name sent with Dynamic Client Registration.
RedirectURL	Redirect URL where the local listener waits for the authorization code. Default http://127.0.0.1:33418/callback.
Timeout	Seconds to wait for the user login. Default 300.
AccessToken	Read only. Bearer token currently in use, empty until authorized.

 

Events

• OnMCPAuthorizationURL: raised with the authorization URL. Set Handled to True if your application opens it (for example in an embedded browser); otherwise the default browser is opened.
• OnMCPAuthorizationCredentials: raised with aSave False the first time an issuer is used, so you can load stored credentials into aCredentials, and with aSave True after a registration, a new token or a refresh, so you can store them.

 

TsgcAI_MCP_Client_AuthorizationCredentials has the properties Issuer (read only), ClientId, ClientSecret, AccessToken, RefreshToken, ExpiresAt, Scope and Registration (preregistered, cimd or dcr).

Sample code

procedure TForm1.FormCreate(Sender: TObject);
begin
  MCP.MCPOptions.HttpOptions.URL := 'https://mcp.example.com/mcp';
  MCP.MCPOptions.Authorization.Enabled := True;
  MCP.MCPOptions.Authorization.ClientName := 'My MCP Client';
  MCP.MCPOptions.Authorization.RedirectURL := 'http://127.0.0.1:33418/callback';
  MCP.OnMCPAuthorizationURL := MCPAuthorizationURL;
  MCP.OnMCPAuthorizationCredentials := MCPAuthorizationCredentials;
  MCP.Initialize;
end;

procedure TForm1.MCPAuthorizationURL(Sender: TObject; const aURL: string;
  var Handled: Boolean);
begin
  Log('login: ' + aURL);
  Handled := False; // open the default browser
end;

procedure TForm1.MCPAuthorizationCredentials(Sender: TObject;
  const aIssuer: string;
  const aCredentials: TsgcAI_MCP_Client_AuthorizationCredentials;
  aSave: Boolean);
begin
  if aSave then
    FStore.Values[aIssuer] := aCredentials.RefreshToken
  else
    aCredentials.RefreshToken := FStore.Values[aIssuer];
end;