MCP tools
An AI client connected to Waldur's MCP server can call the tools on this page. To connect one, see Connect AI clients over MCP.
Every tool only reads. None of them changes anything in Waldur. A tool sees what you see in the portal, with your roles in organizations and projects. Your client lists each tool with its full input and output schemas, so this page only summarizes them.
Which tools your client lists
Your client may list fewer tools than this page:
get_user_overviewis listed only for staff and support users.- With a personal access token, a tool is listed only if the token holds the
permissions the same REST call needs.
get_user_overviewneedsSUPPORT.ACCESSorSTAFF.ACCESS. Every other tool works with any token the server accepts. chart_costsis not listed when the portal hides prices.search_docsis not listed when documentation search is turned off, or when no documentation is loaded.
How tools match names and limit results
- An input ending in
_uuid, or nameduuid, matches exactly. - An input ending in
_name, or namedsearch, matches part of the name, ignoring case, unless its description says the name must be exact. When a name matches several projects or resources,get_projectandget_resourcereturn them inmatches, so your client can ask you which one you mean. - Most lists return at most 15 items. When more match,
_truncatedis true and_total_countgives the number. Narrow the request with more inputs to see the rest. - A result has a one-line summary, the data as JSON text, and the same data as structured content that follows the tool's output schema.
Organizations and projects
list_organizations
Lists the organizations you have access to.
| Input | Type | Description |
|---|---|---|
search |
string | Part of the name or abbreviation. |
uuid |
string | One organization's UUID. |
Returns organizations, each with its UUID, name, abbreviation and your role, and
total.
list_projects
Lists the projects you have access to.
| Input | Type | Description |
|---|---|---|
organization_uuid |
string | Only this organization's projects. |
organization_name |
string | The organization's name, when its UUID is not known. |
search |
string | Part of the project name. |
uuid |
string | One project's UUID. |
Returns projects, each with its UUID, name, organization and your role, and total.
get_project
Shows one project: its organization, dates, and team members with their roles.
| Input | Type | Description |
|---|---|---|
project_uuid |
string | The project's UUID. |
project_name |
string | The project's name, when its UUID is not known. |
Returns project, organization and team. When you may not see the project's
team, team is null and restricted_fields lists team: the team is hidden from you,
which doesn't mean it has no members.
get_project_quota
Shows a project's quota limits and current usage.
| Input | Type | Description |
|---|---|---|
project_uuid |
string | The project's UUID. |
project_name |
string | The project's name, when its UUID is not known. |
Returns project and quotas, each with its name, limit and usage.
Resources
get_project_resources
Lists resources with their state, offering and backend ID. Terminated resources are left out.
| Input | Type | Description |
|---|---|---|
project_uuid |
string | Only this project's resources. |
project_name |
string | The project's name, when its UUID is not known. |
search |
string | Part of the resource name or backend ID. |
uuid |
string | One resource's UUID. |
Returns resources, each with its UUID, name, state, offering, category, project,
backend ID, plan and creation date, and total.
get_resource
Shows one resource: its state, offering, plan, limits, project, last error message and recent events.
| Input | Type | Description |
|---|---|---|
resource_uuid |
string | The resource's UUID. |
resource_name |
string | The resource's name, when its UUID is not known. Terminated resources are skipped. |
project_name |
string | Narrows a resource_name search to one project. |
Returns resource, offering, plan, project, organization and
recent_events.
get_resource_usage
Shows a resource's usage of each component, such as CPU hours or storage, in the current billing period.
| Input | Type | Description |
|---|---|---|
resource_uuid |
string | The resource's UUID. |
resource_name |
string | The resource's name, when its UUID is not known. |
Returns resource, components and the billing period. When you may not see the
usage, components is null and restricted_fields lists components.
explain_resource_paused_reason
Explains why a resource is paused: a cost policy, SLURM usage over its grace limit, the project's grace period, or a manual pause. It also says when the resource is not paused, and when its project has ended although the resource is not paused.
| Input | Type | Description |
|---|---|---|
resource_uuid |
string | The resource's UUID. |
resource_name |
string | The resource's name, when its UUID is not known. |
project_name |
string | Tells resources with the same name apart. |
Returns resource, project with its end date and grace period, primary_cause,
and the numbers behind it in attribution and policy_details.
Orders
list_orders
Lists marketplace orders to create, update or terminate resources.
| Input | Type | Description |
|---|---|---|
project_uuid |
string | Only orders in this project. |
project_name |
string | The project's name, when its UUID is not known. |
resource_uuid |
string | Only orders for this resource. |
customer_uuid |
string | Only orders placed by this organization. |
customer_name |
string | The organization's name, when its UUID is not known. |
offering_uuid |
string | Only orders for this offering. |
offering_name |
string | The offering's name, when its UUID is not known. |
state |
array of strings | Only orders in these states: pending-consumer, pending-provider, pending-project, pending-start-date, executing, done, erred, canceled or rejected. pending stands for every pending-* state. |
Returns orders, each with its UUID, type, state, offering, resource, project,
organization, cost, creator, creation date and error message, and total.
get_order
Shows one order: its state, error message, who created and reviewed it, and when.
| Input | Type | Description |
|---|---|---|
order_uuid |
string | Required. The order's UUID. |
Returns order, created_by, consumer_reviewed_by, provider_reviewed_by,
offering, plan, resource, project and organization.
Costs, invoices and credit
chart_costs
Shows an organization's or a project's monthly costs: the cost incurred, the credit and compensation applied, and the net cost. The last month is the current one, as an estimate.
| Input | Type | Description |
|---|---|---|
customer_uuid |
string | The organization's UUID. |
customer_name |
string | The organization's name, when its UUID is not known. |
project_uuid |
string | The project's UUID. |
project_name |
string | The project's name, when its UUID is not known. |
months |
integer | How many months, from 1 to 24. Default 12. |
With both an organization and a project, the organization only narrows which project is meant.
Returns the organization or project, currency, months with the costs of each
month, and total_price.
list_invoices
Lists monthly invoices with their state and totals.
| Input | Type | Description |
|---|---|---|
customer_uuid |
string | Only this organization's invoices. |
customer_name |
string | The organization's name, when its UUID is not known. |
year |
integer | Only invoices for this year. |
month |
integer | Only invoices for this month, from 1 to 12. |
state |
array of strings | Only invoices in these states: pending, pending_finalization, created, paid or canceled. created means issued and not paid. |
Returns invoices, each with its UUID, number, organization, year, month, state,
price, tax, total, invoice date and due date, and total.
explain_invoice_compensations
Explains the credit compensations and manual adjustments on a project's invoice, and counts terminated resources that still added to it.
| Input | Type | Description |
|---|---|---|
project_uuid |
string | The project's UUID. |
project_name |
string | The project's name, when its UUID is not known. |
year |
integer | The invoice's year. Default: the latest invoice. |
month |
integer | The invoice's month. Default: the latest invoice. |
Returns project, invoice_summary, per_resource with each resource's gross cost,
compensation and net cost, manual_adjustments and concealed_resource_count.
explain_project_credit_balance
Explains a project's credit: how much was allocated, how much has been spent this month and in total, and whether the project is overdrawn. It also shows the organization's credit.
| Input | Type | Description |
|---|---|---|
project_uuid |
string | The project's UUID. |
project_name |
string | The project's name, when its UUID is not known. |
Returns project, customer, project_credit and customer_credit.
get_customer_credit_overview
Shows an organization's credit, and each of its projects' credit, spending, balance and whether it is overdrawn.
| Input | Type | Description |
|---|---|---|
customer_uuid |
string | The organization's UUID. |
customer_name |
string | The organization's name, when its UUID is not known. |
Returns customer, customer_credit, projects and overdrawn_count. When the
project list is cut short, _total_project_count gives the number of projects.
list_overdrawn_projects
Lists projects that have spent more than their credit.
| Input | Type | Description |
|---|---|---|
customer_name |
string | Only this organization's projects. Without it, all the projects you can see. |
Returns overdrawn_projects, each with its project, organization, credit, spending
to date and the amount it is over by.
Marketplace
These tools cover the offerings you could order in the portal. For staff and support users, that is every active or paused offering.
list_categories
Lists the marketplace categories that hold at least one offering you could order. It takes no inputs, and returns every such category.
Returns categories, each with its UUID, title and number of offerings.
search_offerings
Searches the marketplace offerings by keyword.
| Input | Type | Description |
|---|---|---|
keyword |
string | Required. One word or term, matched against names, descriptions, categories, tags, plans and components. |
category_uuid |
string | Only offerings in this category. |
category_name |
string | The category's exact title, when its UUID is not known. |
type |
string | Only offerings of this type, such as OpenStack.Tenant. |
limit |
integer | How many offerings to return, up to 15. |
Returns offerings, each with its name, UUID, category, provider, country,
description, starting price and portal link, and total. has_access_url marks the
offerings that also publish a direct access link.
get_offering
Shows one offering, with its plans, components, attributes and links.
| Input | Type | Description |
|---|---|---|
uuid |
string | The offering's UUID. |
name |
string | The offering's exact name, when its UUID is not known. |
Returns offering, with its description, plans, components, attributes, tags, access
URL, getting-started text, documentation, helpdesk and privacy policy links, and portal
link.
compare_offerings
Compares two or more offerings by provider, category, description and starting price.
| Input | Type | Description |
|---|---|---|
uuids |
array of strings | The offerings' UUIDs. |
names |
array of strings | The offerings' exact names, when their UUIDs are not known. |
Returns offerings, and in missing the ones it did not find.
Documentation
search_docs
Searches the Waldur user and administrator documentation, which is this site.
| Input | Type | Description |
|---|---|---|
query |
string | Required. English keywords for the feature or task, up to 300 characters. |
Returns sections, each with its title, breadcrumb, excerpt, link and whether the
feature it describes is on in your portal, and in switched_off_here the features that
are off.
Support
get_user_overview
Shows another user's organizations and projects with their roles, resource counts, pending orders and recent errors. Only staff and support users get this tool.
| Input | Type | Description |
|---|---|---|
user_email |
string | Required. The user's email address. |
Returns user, organizations, projects, resources, pending_orders and
recent_errors.