Python SDK API reference

Marcopolo(
    access_token: str,                        # an API token from Developer Tools, or a namespace user token
    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 covered here: client.connections, client.connection_types, client.connection_setup, client.operations, client.catalog, client.workspace, and client.toolkit (see Agent toolkit).

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.

For platforms with a namespace provisioned by Marcopolo; most callers authenticate with an API token and don't need it. See MarcoPolo Namespace with Per-User Workspaces.

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), wrong-method submissions, and hosted-OAuth methods with errors naming the problem. Use hosted connection setup for OAuth methods, or authorize them in the web app. 409 when the derived name already exists.

FileUpload.from_path(path)
FileUpload.from_bytes(filename, content)
FileUpload.create_empty()        # only where the field's file spec sets allow_create_empty

The value for a file-backed setup field (one whose SetupField.file spec is set). Serialized as {"filename", "content_base64"} or {"create_empty": true}; the server validates the extension and decoded size against the published spec. A server-side path is never accepted.

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=None, client_session_id=None, requested_scopes=None) returns ConnectionSetupStart.

Without return_url, the provider returns the user to MarcoPolo's completion page. With a dedicated MarcoPolo namespace, return_url can point to your application on an origin registered for that namespace; Google Drive does not support this return path.

Retrying with the same client_session_id reuses an 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 caller may not create connections or the return origin is not registered; ServiceUnavailableError (503) when the provider is not configured on the deployment.

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

operations.query(
    connection_name, *,
    source,
    parameters=None, input_reference=None,
    inline=False, inline_limit=500,
)

Returns Operation. source names exactly one kind:

parameters template-substitutes into the query; input_reference chains a prior result reference in as input; a provider operation's definition 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. Continue with next_offset while it is not None. ResourceGoneError (410) when the relation has been dropped — distinct from 404.

offset = 0
while offset is not None:
    page = await client.operations.records(operation_id, limit=500, offset=offset)
    consume(page.rows)
    offset = page.next_offset

Reads the requested depth in one call: databases with only connection, tables with database, and columns with both database and table. Returns the matching list model below. table without database raises ValueError.

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 WorkspaceConnectionListResponse: connections, count, customer, and next_actions. Each entry in connections 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.

Returns WorkspaceShellResult. Runs a command in the user's persistent workspace and waits up to timeout seconds (1–300). A command that outlives timeout keeps running and returns status="running"; poll it with workspace.shell(f"execution status {result.execution_id}"), whose stdout is the polled execution's record as JSON (status, failure, and an outcome with exit_code, stdout_tail, stderr_tail). A workspace permits one background command at a time. A command that ran and failed returns status="failed"; only a command that never ran raises.

Returns list[ToolDefinition]: name, description, input_schema, and result_schema (JSON Schema) for each agent tool. The catalog is bundled with the SDK release, so this makes no network request. Argument and result schemas are derived from the public API contract.

Invokes the SDK resource method bound to name and returns its ordinary typed result or raises its ordinary error. An unknown name raises ValueError. Common data workflow tools include:

Returns list[StructuredTool]: asynchronous LangChain tools, usable directly by LangGraph's ToolNode and create_react_agent. Requires the langchain extra (pip install "marcopolo-sdk[langchain]", langchain-core>=0.3.79,<2).

• Arguments are validated against each tool's published input schema before the call.
• Results are returned as JSON message content, with the same data as the ToolMessage artifact.
• Failed executions and recoverable request errors become error ToolMessages the model can act on; a running shell execution keeps its execution_id and next_actions.
• AuthenticationError, SDKVersionUnsupportedError, TransportError, and ResponseValidationError raise to application code.