yera.setup.mcp

Presentation-independent setup operations for MCP servers.

Symbols

def add_device_authorized_mcp_server — Authorize, import, and persist one device-authorized MCP server.
def add_header_authorized_mcp_server — Store header secrets, then import, persist, and enable one MCP server.
def add_mcp_server — Import, persist, and enable one MCP server for a profile.
def authorize_mcp_device_setup — Authorize and persist an MCP OAuth device grant.
def build_mcp_oauth_setup — Compose browser OAuth around an active callback session.
def delete_mcp_server — Remove one MCP server from Yera, with its tools and stored secrets.
def loopback_mcp_oauth_setup — Open the dependencies for one browser-based MCP OAuth attempt.
class MCPOAuthSetup — Dependencies required to authorize one MCP connection.
def popular_mcp_servers — Return Yera's curated remote MCP server suggestions.

add_device_authorized_mcp_server

add_device_authorized_mcp_server(
    server_name: str,
    config: MCPServerConfig,
    profile: Profile,
    authorization_id: str,
    client_profile: MCPOAuthClientProfile,
    secret_store: SecretStore,
    interaction: OAuthDeviceInteraction,
    oauth_http_client: httpx2.AsyncClient,
    mcp_http_client: httpx2.AsyncClient | None = None,
    catalogue: SQLiteMCPCatalogue | None = None,
    sleep: Callable[[float], Awaitable[None]] = anyio.sleep,
) → None

Authorize, import, and persist one device-authorized MCP server.

Parameters

server_name
type: str

Name used to expose and configure the server.

config
type: MCPServerConfig

Validated Streamable HTTP server configuration.

profile
type: Profile

Profile in which the server will be enabled.

authorization_id
type: str

Stable identity used for stored OAuth state.

client_profile
type: MCPOAuthClientProfile

Registered public device-authorization profile.

secret_store
type: SecretStore

Protected store receiving issued OAuth tokens.

interaction
type: OAuthDeviceInteraction

Presentation implementation showing verification details.

oauth_http_client
type: httpx2.AsyncClient

Client used for OAuth endpoint requests.

mcp_http_client
type: httpx2.AsyncClient | None = None

Optional caller-owned MCP transport client.

catalogue
type: SQLiteMCPCatalogue | None = None

Optional caller-owned MCP catalogue.

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

Awaitable delay implementation used between token requests.

add_header_authorized_mcp_server

add_header_authorized_mcp_server(
    server_name: str,
    config: MCPServerConfig,
    profile: Profile,
    headers: Mapping[str, str],
    secret_store: SecretStore,
    catalogue: SQLiteMCPCatalogue | None = None,
) → None

Store header secrets, then import, persist, and enable one MCP server.

The header values are owned by the connection rather than a credential group, so the server works in every project. Each attempt stores its values under a fresh owner, so a server being replaced keeps its own values until the new configuration is written; they are then deleted as stale. If anything fails, the new values are deleted and the previous connection is left untouched.

Parameters

server_name
type: str

Name used to expose and configure the server.

config
type: MCPServerConfig

Validated Streamable HTTP server configuration.

profile
type: Profile

Profile in which the server will be enabled.

headers
type: Mapping[str, str]

Header values keyed by header name.

secret_store
type: SecretStore

Protected store receiving the header values.

catalogue
type: SQLiteMCPCatalogue | None = None

Optional caller-owned MCP catalogue.

add_mcp_server

add_mcp_server(
    server_name: str,
    config: MCPServerConfig,
    profile: Profile,
    catalogue: SQLiteMCPCatalogue | None = None,
    http_client: httpx2.AsyncClient | None = None,
    oauth_setup: MCPOAuthSetup | None = None,
    secret_store: SecretStore | None = None,
) → None

Import, persist, and enable one MCP server for a profile.

The live server is imported before configuration is changed, ensuring an unreachable server or unsupported schema cannot leave a new connection in the user's configuration.

Parameters

server_name
type: str

Name used to expose and configure the server.

config
type: MCPServerConfig

Validated Streamable HTTP server configuration.

profile
type: Profile

Profile in which the server will be enabled.

catalogue
type: SQLiteMCPCatalogue | None = None

Optional caller-owned MCP catalogue.

http_client
type: httpx2.AsyncClient | None = None

Optional caller-owned HTTP client.

oauth_setup
type: MCPOAuthSetup | None = None

Optional dependencies for completing OAuth authorization.

secret_store
type: SecretStore | None = None

Optional protected OAuth storage override.

authorize_mcp_device_setup

authorize_mcp_device_setup(
    server_name: str,
    server_url: str,
    authorization_id: str,
    client_profile: MCPOAuthClientProfile,
    secret_store: SecretStore,
    interaction: OAuthDeviceInteraction,
    http_client: httpx2.AsyncClient,
    sleep: Callable[[float], Awaitable[None]] = anyio.sleep,
) → MCPOAuthAuth

Authorize and persist an MCP OAuth device grant.

Parameters

server_name
type: str

Yera name of the MCP connection.

server_url
type: str

Streamable HTTP endpoint being authorized.

authorization_id
type: str

Stable identity used for stored OAuth state.

client_profile
type: MCPOAuthClientProfile

Registered public device-authorization profile.

secret_store
type: SecretStore

Protected store receiving issued OAuth tokens.

interaction
type: OAuthDeviceInteraction

Presentation implementation showing verification details.

http_client
type: httpx2.AsyncClient

Client used for OAuth endpoint requests.

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

Awaitable delay implementation used between token requests.

Returns

type: MCPOAuthAuth

Persistable OAuth authentication configuration.

build_mcp_oauth_setup

build_mcp_oauth_setup(
    authorization_id: str,
    secret_store: SecretStore,
    callback_session: OAuthCallbackSession,
    browser_opener: Callable[[str], bool] = webbrowser.open,
    fallback_handler: Callable[[OAuthAuthorizationRequest], Awaitable[None]] | None = None,
    client_profile: str | None = 'yera',
) → MCPOAuthSetup

Compose browser OAuth around an active callback session.

Parameters

authorization_id
type: str

Stable identity used for stored OAuth state.

secret_store
type: SecretStore

Protected store receiving OAuth protocol secrets.

callback_session
type: OAuthCallbackSession

Active local or hosted callback session.

browser_opener
type: Callable[[str], bool] = webbrowser.open

Function opening the transient authorization URL.

fallback_handler
type: Callable[[OAuthAuthorizationRequest], Awaitable[None]] | None = None

Optional presenter used when browser opening fails.

client_profile
type: str | None = 'yera'

Optional predefined OAuth client profile name.

Returns

type: MCPOAuthSetup

OAuth setup ready for MCP connection authorization.

delete_mcp_server

delete_mcp_server(
    server_name: str,
    secret_store: SecretStore,
    catalogue: SQLiteMCPCatalogue | None = None,
) → bool

Remove one MCP server from Yera, with its tools and stored secrets.

The server leaves global configuration and every profile first, then the tool catalogue, and its secrets are deleted last. A failure part-way can leave an unused secret, but never a configured server without its credentials. Credential-group values used by static headers are left alone, because they belong to the user's group.

Parameters

server_name
type: str

Name of the configured server to remove.

secret_store
type: SecretStore

Protected store holding the connection's secrets.

catalogue
type: SQLiteMCPCatalogue | None = None

Optional caller-owned MCP catalogue.

Returns

type: bool

Whether a configured server with that name was removed.

Raises

MCPInvalidConfigError

If the global MCP configuration is invalid.

loopback_mcp_oauth_setup

loopback_mcp_oauth_setup(
    authorization_id: str,
    secret_store: SecretStore,
    browser_opener: Callable[[str], bool] = webbrowser.open,
    fallback_handler: Callable[[OAuthAuthorizationRequest], Awaitable[None]] | None = None,
    timeout_seconds: float = 300,
    client_profile: str | None = 'yera',
    callback_host: str = '127.0.0.1',
    callback_port: int = 0,
) → AsyncIterator[MCPOAuthSetup]

Open the dependencies for one browser-based MCP OAuth attempt.

Parameters

authorization_id
type: str

Stable identity used for stored OAuth state.

secret_store
type: SecretStore

Protected store receiving OAuth protocol secrets.

browser_opener
type: Callable[[str], bool] = webbrowser.open

Function opening the transient authorization URL.

fallback_handler
type: Callable[[OAuthAuthorizationRequest], Awaitable[None]] | None = None

Optional presenter used when browser opening fails.

timeout_seconds
type: float = 300

Maximum time to wait for the OAuth callback.

client_profile
type: str | None = 'yera'

Predefined OAuth client profile, defaulting to Yera's canonical public identity. Pass None to use DCR without CIMD.

callback_host
type: str = '127.0.0.1'

Loopback interface receiving the OAuth redirect.

callback_port
type: int = 0

Fixed callback port, or 0 for an ephemeral port.

MCPOAuthSetup

Dependencies required to authorize one MCP connection.

Attributes

authorization_id
type: str

Stable identity used for stored OAuth state.

client_metadata
type: OAuthClientMetadata

OAuth client declaration supplied to the MCP SDK.

secret_store
type: SecretStore

Protected store receiving OAuth protocol secrets.

interaction
type: OAuthInteraction | None

Optional user-facing authorization interaction.

client_profile
type: str | None

Optional predefined OAuth client profile name.