Projects

A project is the top-level workspace in XCubes. Everything you build — dimensions, cubes, dashboards — lives inside a single project, and objects within the same project can freely reference each other.

What a project contains

Dimensions are the reusable item lists (Accounts, Geography, Month). They are defined once at the project level and then attached to whichever cubes need them.

Cubes are the multidimensional data grids. Each cube references two or more dimensions, one for rows and one or more for columns (and optionally page-level filters). See Cubes & coordinates.

Dashboards present cube data as visual widgets — charts, pivot tables, scorecards, and ranking cards. A dashboard can combine widgets from multiple cubes in the same project. See Dashboards.

Data tables hold the records a cube cannot: journals, registers, task lists — anything with text, dates or one row per event. They feed cubes through Links, and back several dashboard widgets directly. See Data tables.

A project also holds the supporting objects those four depend on: the cube references that let one cube read another, the mapping tables that translate a source system's codes, uploaded files, and snapshots.

Scope and sharing

Dimensions are scoped to the project: the same dimension can appear in multiple cubes, so renaming an item or adding a formula row propagates everywhere at once. Cross-cube references let formulas in one cube pull values from another cube in the same project. See Cube references.

Files

Uploaded files live at the project level too, in Files under the Data section, organised into folders one level deep. A stored file is the input to everything that reads a spreadsheet: read one of its sheets, import it into a cube, or make it the re-runnable source of a Link.

The distinction worth knowing is against files you attach to a conversation with the assistant. Those are working material and are kept for 24 hours; a file in the project Files area is permanent, and anything that accepts a conversation attachment accepts a stored file in its place. Upload the ledger export you will re-import monthly; attach the one-off you are asking a question about.

Not every file is equally useful. Spreadsheets — CSV and Excel — can be both read and imported. A PDF can be read, but importing from one means extracting its rows first. Images and Word documents are neither: XCubes stores them, and nothing can parse them into a cube.

Starting a new project

When you create a project, XCubes offers a set of starter templates (Finance, HR, SaaS, IT) that seed dimensions and cubes with a realistic structure. You can also start from scratch. Either way, the first practical step is building your dimensions before creating any cubes, because a cube cannot exist without at least one row dimension and one column dimension.

Creating a project from an agent

An agent connected over MCP creates a project with create_project:

create_project({ "name": "FY26 Budget", "description": "Rolling budget" })

It returns the new project's id, name and createdAt. Keep the id — every other tool takes it as projectId.

Two things set this tool apart from the rest of the surface:

• It is user-scoped. It takes no projectId, because it creates the one you pass to everything afterwards. The only other tools that work without a project context are list_projects (every project you can reach, with its id), get_help (this manual), and the two sample tools below.
• It creates an empty project. The starter templates are applied by the UI after the project exists; create_project gives you nothing but the container. Build the structure yourself with create_dimension and create_cube — see Build your first model — or read a template's shape first with list_templates / get_template, which cover the same four domains and return the dimensions, items and formulas to draft from. If you want a populated model rather than a structure to fill in, start from a sample instead.

Creating a project counts against your plan's project cap. When you are already at the limit the call fails with an error naming the cap and your current project count; nothing is created.

Starting from a sample

Building from scratch is rarely the fastest way to understand XCubes. The app ships a curated set of sample projects — working models with real dimensions, formulas and dashboards — and an agent can reach them directly. list_samples returns the catalog plus remainingProjects, the headroom left on your plan:

list_samples()
provision_sample({ "sampleProjectId": "<a projectId from list_samples>" })

Cloning runs in the background and takes 10 to 120 seconds, so provision_sample returns a pending job rather than a finished project. list_samples doubles as the status surface: call it again until that sample gains a myProjectId, then use that id as projectId everywhere else. A sample already being cloned returns the same job instead of starting a second copy, so re-calling while you wait is safe.

Clones still in flight count against the project cap, so provisioning several samples in a row stops at the limit rather than overshooting it.

Prefer list_projects before create_project when the work might belong in a model that already exists, and list_samples when the goal is to see what XCubes does rather than to build something specific — an agent that reaches for create_project by reflex accumulates near-empty projects and burns the cap.