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.

OAuthDeviceAuthorizationResponse

Inherits: BaseModel

Represent a validated OAuth device-authorization response.

Attributes

device_code
type: SecretStr

Secret polling credential issued to Yera.

user_code
type: str

Short code presented to the user.

verification_uri
type: str

Page at which the user enters the code.

verification_uri_complete
type: str | None

Optional link containing the user code.

expires_in
type: int

Lifetime of the device authorization in seconds.

interval
type: int

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

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

httpx2.HTTPStatusError

If the authorization server rejects the request.

pydantic.ValidationError

If the response does not follow RFC 8628.