Start an Apache Polaris server (OSS version uses in-memory or PostgreSQL persistence); authenticate using the root credentials configured at startup to obtain a bearer token via POST /api/catalog/v1/oauth/tokens with grant_type=client_credentials
Create a catalog via POST /api/management/v1/catalogs with a JSON body specifying name, type (INTERNAL or EXTERNAL), storageConfigInfo (e.g., S3 bucket base location and IAM role ARN for credential vending), and default-base-location
Create a namespace within the catalog using the Iceberg REST spec endpoint POST /api/catalog/v1/{catalog_name}/namespaces with body {"namespace": ["my_namespace"], "properties": {}}
Register a table via POST /api/catalog/v1/{catalog_name}/namespaces/{namespace}/tables with a CreateTableRequest JSON body containing the schema (list of fields with id, name, type), partition spec, and location; Polaris returns a LoadTableResult with the metadata file location
Connect an engine such as Apache Spark using the SparkSessionExtensions and setting spark.sql.catalog.my_catalog to org.apache.iceberg.spark.SparkCatalog with catalog-impl=org.apache.iceberg.rest.RESTCatalog and uri pointing to your Polaris server URL
Known gotchas
Polaris implements the Iceberg REST Catalog spec which is versioned; verify your Iceberg client library version supports the same REST catalog spec version as your Polaris server — mismatches cause 404 errors on valid endpoints
Credential vending (temporary STS tokens for S3 access) requires Polaris to be configured with an IAM role that has STS AssumeRole permissions; without this, engines can authenticate to Polaris but fail when reading or writing actual Parquet files
Apache Polaris 1.x was in incubating status through 2025; API surface areas including management endpoints may change across minor releases — do not assume management API paths are stable across versions without checking the release notes
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp