Python SDK API reference

Marcopolo(
    access_token: str,                        # any Marcopolo credential; never interpreted client-side
    base_url: str = "https://mcp.marcopolo.dev",
    timeout: float = 60.0,
    max_retries: int = 2,                     # transport-level connection retries
    client_name: str | None = None,           # User-Agent override
    client_version: str | None = None,
)

Resources: client.connections, client.connection_types, client.connection_setup, client.operations, client.catalog, client.workspace.

Plain-HTTP base URLs are rejected unless loopback, because the bearer credential rides every request. The client sends X-Marcopolo-SDK-Version on every call; see compatibility.

MarcopoloNamespace(
    api_key: str,                             # namespace key, "mpk_..."
    base_url: str = "https://mcp.marcopolo.dev",
    timeout: float = 30.0,
)

The namespace key is attached only to the token-exchange request, never stored on client headers, and the exchange is never retried automatically.

Returns UserToken. Provisions the user on first issue. The tenant is derived from the email domain server-side. Consumer email domains are refused with ValidationError.

connection_types.list(search=None, category=None, auth_method=None) returns list[ConnectionType]. Filters combine. auth_method is one of manual | oauth | service_account | builtin.

Returns ConnectionType; 404 for unknown types.

Returns list[Connection] — everything visible to the principal.

Returns Connection. Invisible and missing are both 404.

Returns ConnectionConfiguration: provider settings with secret values masked.

connections.create(connection_type=, display_name=, setup_method=, fields=) returns Connection.

Non-interactive creation: declare a method from the type's setup_methods and pass its inputs as one fields mapping — the server stores values by the method definition and rejects unknown fields, missing required fields, badly shaped values (wrong type, arrays below min_items), file-backed fields (satisfied through the Marcopolo app's upload flow), wrong-method submissions, and hosted-OAuth methods with errors naming the problem. Interactive types go through connection setup. 409 when the derived name already exists.

connections.update(connection, display_name=None, configuration_patch=None) returns Connection. Patches metadata and non-secret configuration; at least one field required.

Returns ConnectionTest. Runs the provider check through the runtime. A failed check is a returned outcome, not an exception.

204 on success; requires management permission.

Returns ConnectionSharing. ShareScope.COMPANY, or ShareScope.USERS with a user list.

Returns ConnectionSharing. Symmetric with share.

Returns ConnectionSharing: shared_with_company, shared_with_users, optional warning.

connection_setup.start(connection_type=, display_name=, return_url=, client_session_id=None, requested_scopes=None) returns ConnectionSetupStart.

Starts a hosted provider authorization for the current end user. Retrying with the same client_session_id reuses the in-flight session instead of creating a duplicate.

Errors: ValidationError for an unknown or non-OAuth type or an unusable return_url; PermissionDeniedError when the principal may not create connections or the return_url origin is not registered for the namespace; APIError(503) when the provider is not configured on the deployment.

Returns ConnectionSetupSession. Missing, expired, and another principal's sessions all read as 404.

operations.query(
    connection, *,
    query_path=None, query_text=None, provider_operation=None,
    parameters=None, input_reference=None,
    inline=False, inline_limit=500,
)

Returns Operation. Exactly one source. parameters template-substitutes into the query; input_reference chains a prior result reference in as input; provider_operation is passed to the connector verbatim, in the shape its query guide documents. Synchronous: dispatched, executed, and returned terminal in one call; the execution ceiling is 300 seconds, beyond which UpstreamTimeoutError (504) is raised and nothing has completed. Raise the client timeout above the ceiling for long queries.

Returns OperationRecords: a bounded page from a materialized result; limit accepts 1–5000. ResourceGoneError (410) when the relation has been dropped — distinct from 404.

Returns CatalogDatabaseList: top-level containers. ValidationError when the connector publishes no catalog.

Returns CatalogTableList.

Returns CatalogColumnList: column names, source types, descriptions, attributes.

Returns QueryGuide: connection_name and markdown — connector-authored prose describing the provider's query syntax and provider_operation shapes. 404 when the connector publishes none.

Returns list[WorkspaceConnection]. Each entry pairs a Connection with the operations it can actually run (capabilities, e.g. query, test, describe) plus workspace_path and an optional note. Slower than connections.list() because it consults the execution workspace.