AI Refinery SDK Integration

Step-by-step guide for discovering and deploying MCP servers from the Agent Gallery with the AI Refinery SDK.

Use the AI Refinery SDK to browse the Agent Gallery catalog, deploy Model Context Protocol (MCP) servers, and manage deployments that power your agents.

Unreleased Functionality

This functionality is currently undergoing development and beta testing and is not yet available in the public versions of the AI Refinery SDK. We estimate a mid-Nov 2025 release date.

Prerequisites

AI Refinery SDK 1.21.0 or later
API key with access to the AI Refinery
Python runtime (3.12+) or compatible environment where the SDK is installed

pip install airefinery-sdk>=1.21.0

Note: The SDK exposes both sync and async clients. The examples below rely on the async surface to simplify batching and long-running operations.

1. Connect to the Agent Gallery Catalog

from air.catalog import AsyncCatalog

catalog = AsyncCatalog(
    api_key="<API_KEY>",
    default_headers={"airefinery_account": "<ACCOUNT_SLUG>"},
)

# MCP-specific helper that sets agent_type="third-party"
mcpcatalog = AsyncCatalog(
    api_key="<API_KEY>",
    default_headers={"airefinery_account": "<ACCOUNT_SLUG>"},
    agent_type="third-party",
)

catalog exposes general-purpose helpers across all namespaces.
mcpcatalog narrows the results to MCP servers, matching the Agent Gallery inventory.

2. Discover MCP Servers

from air.mcp import catalog as mcp_catalog

all_servers = await mcp_catalog.list_mcp_servers(catalog)

search_results = await mcp_catalog.search_mcp_servers(
    catalog,
    query="digital twin",
    filters={"capabilities": ["simulation"], "vendor": "contoso"},
)

list_mcp_servers returns quick summaries (name, description, default version).
search_mcp_servers supports natural-language queries plus structured filters such as vendor, tags, or runtime requirements.

3. Inspect Configuration Details

server = await mcp_catalog.get_mcp_server(
    catalog,
    mcp_server_name="sap-digital-twin",
)

print(server.available_versions)
print(server.config_schema)

Use get_mcp_server before deploying to understand the version-specific configuration schema, runtime requirements, and certification metadata surfaced by the Agent Gallery.

4. Deploy MCP Servers from the Gallery

from air.mcp.deployments import deploy, MCPDeploymentSpec

spec = MCPDeploymentSpec(
    mcp_server_name="sap-digital-twin",
    version="1.3.5",
    config={"tenant_id": "xyz", "region": "eu-west"},
    deployment_name="sap-digital-twin-eu",
    runtime={"resources": {"cpu": "2", "memory": "4Gi"}},
    scaling={"desired_replicas": 1, "max_replicas": 3},
)

deployment = await deploy(catalog, spec)
print(deployment.deployment_id)

Pass a single MCPDeploymentSpec or a list for batch deployments; the return type mirrors your input.
The Agent Gallery validates the payload against the config_schema published for that server and version.
runtime, scaling, and network fields are optional placeholders that unlock advanced controls as they become available.

5. Operate and Monitor Deployments

from air.mcp import deployments

# List every deployment you own
existing = await deployments.list(catalog)

# Check one or many statuses
status = await deployments.get_status(catalog, deployment_id=deployment.deployment_id)

# Stop without deleting (keeps configuration for future restarts)
await deployments.stop(catalog, deployment_id=deployment.deployment_id)

# Permanently remove when finished
await deployments.delete(catalog, deployment_id=deployment.deployment_id)

stop is idempotent and keeps the deployment in a stopped state for future restarts.
delete deprovisions the MCP server and releases associated resources.
Batch operations accept lists so you can manage test and production deployments together.

6. Feed Results Back into Your Agents

When an MCP server emits output intended for downstream AI Refinery workflows, attach the required metadata so the Gallery and Refinery stay in sync:

Field	Purpose	Typical Source
`agent_id`	Ties the deployment to the Gallery registry	Environment variables or deployment config
`conversation_id`	Correlates user sessions across tools	Agent runtime
`refinery_profile`	Selects the Refinery recipe to apply	Integration settings

Add the metadata before handing off to the Refinery client:

from air.refinery import RefineryClient

refinery = RefineryClient(api_key="<API_KEY>")

await refinery.enqueue(
    payload=response_payload,
    profile=response_payload["refinery_profile"],
)