MCP Tools Reference

The HyperAI MCP server exposes 34 tools across five feature groups. All tools run under your own account after OAuth sign-in, so results are scoped to the containers, projects, and datasets you can access. List tools return 30 items per page.

You normally don't call these tools yourself — your AI assistant picks them based on what you ask for. This page is a reference for understanding what the assistant can and cannot do.

Confirmation before writes

The assistant does not run write operations silently. Before creating a container (compute_create_job), restarting one (compute_restart_workspace), or creating a dataset entry (dataset_create), it restates what it is about to do — including the billing consequence — and waits for your explicit go-ahead, even when you named the resource yourself. Issuing a personal access token (user_create_personal_access_token) and deleting a dataset (dataset_delete) require your explicit approval of the concrete values; the assistant will not do either on "you decide". In batch or "just get it done" flows, the assistant keeps deletions out of the flow and uses reversible actions such as stopping a container instead — unless you explicitly named the resource to delete.

User

Tools for querying your own account — profile, quota, billing, usage, and subscriptions — and for managing personal access tokens. They always operate on the signed-in account and take no username parameter.

user_get_profile

Get your account profile: username, display name, email, registration date, roles, membership status, balance, and the organizations you belong to. An organization's ID (not its display name) is what the username parameter of the compute and dataset tools accepts — both to list that organization's resources (e.g. compute_list_jobs) and to create and manage them under the organization (e.g. compute_create_job). Useful for verifying the connection. For an organization's capability flags, seat quota, and members, use the org_get and org_list_members tools.

No parameters.

user_get_quota

Get your storage quota (used / total / remaining), prepaid compute minutes per resource type, and account limits such as how many containers can run at once per resource and GPU type, and the number of datasets and projects.

Three things are easy to confuse. Balance is money (see user_get_profile). Quota is prepaid subscription minutes plus storage (this tool). Limitations are caps on concurrency and counts (this tool). Zero remaining minutes for a resource is not by itself a blocker — it only means the prepaid subscription is used up, and pay-as-you-go usage still charges your balance for any resource you can afford. Whether a container can actually start is decided at creation time by the checks compute_create_job runs (affordability, cluster capacity, per-resource limits, runtime, project, billing plan); quota is never one of them.

No parameters.

user_list_transactions

List billing transactions — recharges, charges, subscription renewals, refunds, and transfers — newest first. Each amount carries its own currency.

Parameters:

• type — filter by direction: recharge (deposits, gifts, vouchers), spend (charges), refund, transfer (transfers between accounts), or all (default)
• page — page number

user_list_usages

List resource usage records, newest first. Compute records carry a duration; serving records are billed as (end − start) × replica count; storage records carry the size change that counts against your storage quota.

Parameters:

• page — page number

user_list_subscriptions

List your subscriptions across all categories — membership, storage expansion, prepaid compute, one-time permanent compute purchases, and organization seats — with plan, price per period, validity, and auto-renewal status. An active subscription with auto-renewal enabled is charged automatically at the end of each period.

Canceling a subscription is only possible in the HyperAI console, not through this tool.

No parameters.

user_get_spend_analysis_guide

Returns a guide for analyzing account spending. Assistants should read it before answering spending questions ("why did my balance drop", "what am I paying for"), so they collect the right data from the other user tools first.

No parameters.

user_list_personal_access_tokens

List your personal access tokens (PATs) — long-lived API credentials — with name, creation and expiry dates, and last-used time. The token plaintext is never included: it is shown exactly once, when the token is created. An empty list does not prove no token was ever created (revoked tokens are hidden), and a listed token is not necessarily usable — expired tokens remain in the list, so check expiresAt.

No parameters.

user_create_personal_access_token

Create a personal access token for your own account. A PAT survives password changes and logouts; it stops working only when revoked or expired.

Issuing a token is an approval-tier operation: a PAT is equivalent to your account password, so the assistant restates the token name and its expiry — the expires_at it will pass, or the 90-day default when omitted — and waits for your explicit approval before calling. It will not issue a token on "you decide", nor as a side step of another task.

Parameters:

• name — a label for the token, at most 30 characters; identification only, it plays no part in authentication
• expires_at — optional expiry as an ISO 8601 UTC instant (e.g. 2026-11-15T00:00:00Z); must be in the future. Omit for the default of 90 days from creation.

user_revoke_personal_access_token

Revoke a personal access token. After revoking, the tool re-reads the list to verify the token is gone.

Parameters:

• id — the token's ID from user_list_personal_access_tokens, not the token plaintext
• confirm_name — must match the token's exact name

Compute

Tools for working with compute containers and projects — the same objects you see in the Gear section of the console. Tools that operate on a specific container or project accept an optional username: pass an organization's ID to work on that organization's resources, and pass the same value on every call about the same container.

compute_list_jobs

List your workspace and task containers, newest first. Each entry is one run of a project.

Parameters:

• username — optional; an organization you belong to (your organizations are listed by user_get_profile). Omit to list your own containers.
• status — running / succeeded / failed / cancelled / all (default all)
• q — substring match on container names
• page — page number

compute_list_projects

List projects.

Parameters:

• username — optional; an organization you belong to (your organizations are listed by user_get_profile)
• q — substring match on project names
• page — page number

compute_list_resources

List available compute resource tiers (GPU/CPU) with specs, whether your balance can afford each, and current load.

Parameters:

• username — optional

compute_list_plans

List billing plans: pay-as-you-go and time-boxed packages with durations and prices.

Parameters:

• resource — optional; a resource name from compute_list_resources

compute_list_runtimes

List available container runtime environments (images), excluding deprecated ones.

Parameters:

• username — optional

compute_get_job

Get full details of a container, including its access URL. Secret values are masked.

Parameters:

• job_id_or_url — a container ID or a console container URL
• username — optional; the organization that owns the container. Omit for your own.

compute_get_job_metrics

Get summarized system and custom metrics of a container (latest / min / max / average).

Parameters:

• job_id — container ID

compute_get_project

Get project details plus its container execution history (workspace and task runs).

Parameters:

• project_id_or_url — a project ID or a console URL
• status — filter the execution history: running / succeeded / failed / cancelled / all
• page — page number
• username — optional; the organization that owns the project. Omit for your own.

compute_get_job_readme

Read a container's README as rendered HTML.

Parameters:

• job_id_or_url — a container ID, a project ID, or a console URL

compute_get_job_notebook

Read a container's notebook content.

Parameters:

• job_id_or_url — a container ID, a project ID, or a console URL

compute_get_create_job_guide

Returns the recommended step-by-step workflow for creating a container (billing, data binding, environment variables, ports, creating under an organization). Assistants should read this before calling compute_create_job.

No parameters.

compute_create_job

Create a new workspace container. Billing starts as soon as the container starts, so the assistant restates the plan (resource, image, project, billing) and waits for your explicit go-ahead before calling — even when you named the resource yourself.

Parameters:

• resource — required; a resource name from compute_list_resources
• runtime — required; a runtime name from compute_list_runtimes
• project_id / new_project_name — exactly one of the two: create in an existing project, or create a new project
• description — optional container description
• plan_id — optional; a time-boxed billing plan from compute_list_plans. Omit for pay-as-you-go.
• auto_renew — whether a time-boxed plan renews automatically (default true)
• idle_timeout_minutes — auto-stop after idle time (default 30, 0 disables)
• env — environment variables, a list of {name, value, secret}; value may be text, a number, or a boolean
• data_bindings — data to mount, a list of {source, mount_path, writable}
• ports — custom port mappings, a list of {port, name}
• username — optional; an organization ID (its ID, not its display name) to create the container under that organization. The container is billed to the organization's balance, and every follow-up call about it must pass the same username. Omit to create under your own account.

A few rules the tool enforces, matching the console's behavior:

• Data bindings mount at /input0 through /input4 (read-only sources such as datasets and models) and /output (only a previous container output of the form <owner>/jobs/<job-id>/output can be bound there). See Data Binding.
• Environment variables must not use the reserved OPENBAYES_ prefix, and names containing TOKEN / SECRET / KEY / PASSWORD must be marked as secret. See Environment Variables.
• Environment variable values follow the platform's JSON typing: numeric and boolean settings are sent as numbers and booleans ({ "name": "NCCL_SHM_DISABLE", "value": 1 }), and the container still sees them as the usual text. The platform rejects a plain-text value whose text is itself JSON ("1", "true", "[1]") and creates nothing — the tool coerces "1"-style text to the typed value when that is lossless and rejects the rest before calling the platform. Secret values are sent untouched.
• Port 8080 is reserved for the container's built-in service and cannot be mapped. See Custom Port Mapping.
• The chosen resource must be affordable with your current balance and not at full load, and the chosen billing plan must belong to that resource.

compute_stop_job

Stop a running container.

Parameters:

• job_id — exact container ID; URLs are rejected
• username — optional; the organization that owns the container. Omit for your own.

compute_restart_workspace

Restart a stopped workspace container with its previous configuration. Restarting resumes billing at the previous resource's rate, so the assistant restates the container, its resource, and the billing consequence and waits for your explicit go-ahead — even when you asked for the restart yourself.

Parameters:

• job_id — container ID
• username — optional; the organization that owns the workspace — restarting bills the organization's balance. Omit for your own.

compute_update_project

Update project settings: name, description, idle timeout, and tags.

Parameters:

• project_id_or_url — a project ID or a console URL
• name — optional new name
• description — optional new description
• idle_timeout_minutes — optional; applies project-wide, 0 disables
• add_tags / remove_tags — optional tag lists; tags are validated against the platform catalog
• username — optional; the organization that owns the project. Omit for your own.

compute_update_job_ports

Add or remove custom port mappings on a container. A mapped port gets a publicly reachable URL, so opening a port publishes whatever listens on it to the internet — the assistant should confirm with you before opening one. Port 8080 is reserved and cannot be mapped.

Parameters:

• job_id — container ID
• add_ports — a list of {port, name}
• remove_ports — a list of port numbers to remove
• username — optional; the organization that owns the container. Omit for your own.

Resources

Tools for discovering public content on the platform.

resources_search_public_projects

Search public projects (tutorials and community projects), filterable by tags. Each result carries a clone count as a popularity signal, and a public project can be cloned as the starting point of a new container.

Parameters:

• q — search keywords
• tags — a list of tag names to filter by
• sort — result order: LAST_ACTIVE_AT_DESC (default) / LAST_ACTIVE_AT_ASC / CLONE_COUNT_DESC / CLONE_COUNT_ASC; use CLONE_COUNT_DESC to surface the most popular projects
• page — page number

Dataset

Tools for managing datasets and models — searching, inspecting, creating entries, updating metadata, and deleting. Uploading data is not covered here: that happens in the web console or with the bayes CLI.

dataset_search

Search datasets and models — your own and public ones — in one call. Each result includes the binding name to use as a data_bindings source in compute_create_job.

Parameters:

• q — search keywords
• category — dataset / model / all (default all)
• username — optional; search under an organization instead of your own account
• tags — a list of tag names to filter public results by; tags are a platform-controlled vocabulary matched exactly
• page — page number for your own results
• public_page — page number for public results

dataset_get

Get the full details of a dataset or model in one call: metadata, owner, permissions, every version, and the selected version's README as rendered HTML. Each version carries the binding name to use as a data_bindings source in compute_create_job; the top-level size spans all versions.

Parameters:

• dataset_id_or_url — a dataset/model ID or a console URL; a trailing version segment in the URL is honored
• version — optional version number; overrides the version in the URL

dataset_create

Create a new, empty dataset or model entry — a metadata shell with no versions and no data. Every call creates a new entry, so check with dataset_search first to avoid duplicates. The assistant restates the entry (name, kind, owner, tags) and waits for your explicit go-ahead before calling.

Parameters:

• name — required entry name
• kind — dataset / model (default dataset)
• description — optional description
• tags — optional tag list; tags must be existing names from the platform tag catalog (case-sensitive)
• username — optional; create under an organization instead of your own account

dataset_update

Update a dataset's or model's metadata: name, description, kind, and tags. Pass only the fields to change. Organization-owned entries work directly — the owner is resolved automatically.

Parameters:

• dataset_id_or_url — a dataset/model ID or a console URL
• name — optional new name
• description — optional new description
• kind — optional; change between dataset and model
• add_tags / remove_tags — optional tag lists; tags are validated against the platform catalog before anything is written

dataset_delete

Permanently delete a dataset or model, including every version and all uploaded data. After deleting, the tool re-reads the entry to verify it is gone.

Parameters:

• dataset_id_or_url — a dataset/model ID or a console URL
• confirm_name — must match the entry's exact current name

Org

Tools for querying the organizations you belong to. All three are read-only — inviting members, changing roles, and leaving an organization are console operations. An organization's ID doubles as the username parameter of the compute and dataset tools — to list that organization's resources (compute_list_jobs, dataset_search) and to create and manage them under the organization (compute_create_job, dataset_create).

org_list

List the organizations you belong to, with your role in each (OWNER / MEMBER / PENDING) and per-organization capability flags such as canCreateProject and canCreateInvitation. Whether you can do something in an organization is answered by the capability flags, not the role.

No parameters.

org_get

Get one organization's details: profile (display name, description, type, locked state), seat quota (used / total / remaining), and your capability flags in that organization.

Parameters:

• org_id — the organization's ID, not its display name

org_list_members

List an organization's members, 30 per page: username, display name, role, and join date, plus whether you can remove each member or change their role. Rows with the PENDING role are outstanding invitations.

Parameters:

• org_id — the organization's ID
• page — page number