yera.tools.mcp.oauth_device

OAuth device-authorization support for MCP connections.

Symbols

def authorize_mcp_device — Authorize an MCP connection using the OAuth device grant.
def authorize_mcp_device_profile — Authorize an MCP connection through a predefined device profile.
class OAuthDeviceAuthorizationResponse — Represent a validated OAuth device-authorization response.
def poll_device_token — Poll an OAuth token endpoint for an approved device authorization.
def present_device_authorization — Present safe device-verification instructions to the user.
def request_device_authorization — Start device authorization for a public OAuth client.

authorize_mcp_device

authorize_mcp_device(
    http_client: httpx2.AsyncClient,
    server_name: str,
    server_url: str,
    authorization_server: str,
    device_authorization_endpoint: str,
    token_endpoint: str,
    client_id: str,
    scopes: tuple[str, ...],
    interaction: OAuthDeviceInteraction,
    sleep: Callable[[float], Awaitable[None]] = anyio.sleep,
    clock: Callable[[], float] = monotonic,
) → OAuthToken

Authorize an MCP connection using the OAuth device grant.

Parameters

http_client
type: httpx2.AsyncClient

Client used for OAuth endpoint requests.

server_name
type: str

Yera name of the MCP connection.

server_url
type: str

Streamable HTTP endpoint being authorized.

authorization_server
type: str

Issuer performing authorization.

device_authorization_endpoint
type: str

Endpoint issuing the device code.

token_endpoint
type: str

Endpoint polled for issued tokens.

client_id
type: str

Public identifier registered for Yera.

scopes
type: tuple[str, ...]

OAuth scopes requested for the MCP connection.

interaction
type: OAuthDeviceInteraction

Presentation implementation showing verification details.

sleep
type: Callable[[float], Awaitable[None]] = anyio.sleep

Awaitable delay implementation used between token requests.

clock
type: Callable[[], float] = monotonic

Monotonic clock used to enforce local expiry.

Returns

type: OAuthToken

Validated OAuth tokens issued after user approval.

authorize_mcp_device_profile

authorize_mcp_device_profile(
    http_client: httpx2.AsyncClient,
    profile: MCPOAuthClientProfile,
    server_name: str,
    server_url: str,
    interaction: OAuthDeviceInteraction,
    sleep: Callable[[float], Awaitable[None]] = anyio.sleep,
    clock: Callable[[], float] = monotonic,
) → OAuthToken

Authorize an MCP connection through a predefined device profile.

Parameters

http_client
type: httpx2.AsyncClient

Client used for OAuth endpoint requests.

profile
type: MCPOAuthClientProfile

Registered public device-authorization profile.

server_name
type: str

Yera name of the MCP connection.

server_url
type: str

Streamable HTTP endpoint being authorized.

interaction
type: OAuthDeviceInteraction

Presentation implementation showing verification details.

sleep
type: Callable[[float], Awaitable[None]] = anyio.sleep

Awaitable delay implementation used between token requests.

clock
type: Callable[[], float] = monotonic

Monotonic clock used to enforce local expiry.

Returns

type: OAuthToken

Validated OAuth tokens issued after user approval.

Raises

TypeError

If the profile does not use device authorization.

MCPAuthenticationError

If the profile has no deployed client ID.

RuntimeError

If the profile is missing a required device-flow endpoint.

OAuthDeviceAuthorizationResponse

Inherits: BaseModel

Represent a validated OAuth device-authorization response.

Fields

device_code
type: pydantic.types.SecretStr (required)

Secret polling credential issued to Yera.

user_code
type: str (required)

Short code presented to the user.

verification_uri
type: str (required)

Page at which the user enters the code.

verification_uri_complete
type: str | None = None

Optional link containing the user code.

expires_in
type: int (required)

Lifetime of the device authorization in seconds.

interval
type: int = 5

Minimum polling interval in seconds.

poll_device_token

poll_device_token(
    http_client: httpx2.AsyncClient,
    endpoint: str,
    client_id: str,
    authorization: OAuthDeviceAuthorizationResponse,
    sleep: Callable[[float], Awaitable[None]] = anyio.sleep,
    clock: Callable[[], float] = monotonic,
) → OAuthToken

Poll an OAuth token endpoint for an approved device authorization.

Parameters

http_client
type: httpx2.AsyncClient

Client used to call the authorization server.

endpoint
type: str

OAuth token endpoint.

client_id
type: str

Public identifier registered for Yera.

authorization
type: OAuthDeviceAuthorizationResponse

Device authorization containing the polling credential.

sleep
type: Callable[[float], Awaitable[None]] = anyio.sleep

Awaitable delay implementation used between requests.

clock
type: Callable[[], float] = monotonic

Monotonic clock used to enforce local expiry.

Returns

type: OAuthToken

Validated OAuth tokens issued by the authorization server.

Raises

MCPOAuthDeviceDeniedError

If the user denies authorization.

MCPOAuthDeviceExpiredError

If the device code expires locally or at the authorization server.

MCPOAuthDeviceError

If the endpoint returns another terminal OAuth device-flow error.

httpx2.HTTPStatusError

If the token endpoint rejects the request.

pydantic.ValidationError

If the token response is invalid.

present_device_authorization

present_device_authorization(
    interaction: OAuthDeviceInteraction,
    server_name: str,
    server_url: str,
    authorization_server: str,
    scopes: tuple[str, ...],
    response: OAuthDeviceAuthorizationResponse,
) → None

Present safe device-verification instructions to the user.

Parameters

interaction
type: OAuthDeviceInteraction

Presentation implementation receiving the instructions.

server_name
type: str

Yera name of the MCP connection.

server_url
type: str

Streamable HTTP endpoint being authorized.

authorization_server
type: str

Issuer performing device authorization.

scopes
type: tuple[str, ...]

OAuth scopes requested for the MCP connection.

response
type: OAuthDeviceAuthorizationResponse

Validated device-authorization response.

request_device_authorization

request_device_authorization(
    http_client: httpx2.AsyncClient,
    endpoint: str,
    client_id: str,
    scopes: tuple[str, ...] = (),
) → OAuthDeviceAuthorizationResponse

Start device authorization for a public OAuth client.

Parameters

http_client
type: httpx2.AsyncClient

Client used to call the authorization server.

endpoint
type: str

Device-authorization endpoint.

client_id
type: str

Public identifier registered for Yera.

scopes
type: tuple[str, ...] = ()

OAuth scopes requested for the MCP connection.

Returns

type: OAuthDeviceAuthorizationResponse

Validated device authorization and verification instructions.

Raises

MCPOAuthDeviceError

If the authorization endpoint returns an OAuth device-flow error.

httpx2.HTTPStatusError

If the authorization server rejects the request.

pydantic.ValidationError

If the response does not follow RFC 8628.