Logo
  • Documentation
  • GPU RMA Diagnostic Toolkit — User Guide
MCP Server
  • Primitive MCP
  • Available MCP tools
  • Managing connected applications
  • Security best practices
  • Troubleshooting

Available MCP tools

Every tool Primitive MCP exposes, split by required scope.

Most tools on Primitive MCP fall under one of two scopes. Clients request the scope set they need at connect time, and the user sees the scope list on the OAuth consent screen.

  • mcp:read — read-only inspection. Safe to grant broadly for general-purpose agents. Org admins should note that billing and invoice tools live under mcp:read and return sensitive data — see the Billing section before granting mcp:read to cloud-hosted or web-browsing agents.
  • mcp:write — state-changing actions. Confirm before granting; require human approval for each call.

A small set of utility tools (health, whoami) are unscoped — they don't require either mcp:read or mcp:write. They're listed first below.

Unscoped

System tools any authenticated caller can invoke. Useful for connectivity and identity checks; they don't read or change application data.

ToolWhat it does
healthReturns server status. Useful as a connectivity check.
whoamiReturns the authenticated user (id, username, email) derived from the bearer token.

mcp:read

Read-only tools. None of these change state on Primitive.

Organizations and teams

ToolWhat it does
get_organizationFetch a single organization by slug or id.
list_organizationsList organizations the authenticated user can see.
get_teamFetch a single team.
list_teamsList teams within an organization.
get_memberFetch a single membership record.
list_membersList members of an organization.
get_team_memberFetch one team-member row (team viewers and org admins).
list_team_membersList team-member rows of an organization; filter by team, member, role.
get_invitationFetch a single pending invitation.
list_invitationsList pending invitations for an organization.

Projects and jobs

ToolWhat it does
get_projectFetch a single project.
list_projectsList projects across the user's organizations.
get_jobFetch a single job.
list_jobsList jobs within a project.
get_job_settingsFetch the run configuration for a job, with its schedules.
list_job_settingsList job settings records.
get_job_config_fileFetch one job config file (.primitive/*.yaml): the raw YAML and its parse error.
list_job_config_filesList job config files. Filter by project, commit, or parse error.
get_job_runFetch a single job run.
list_job_runsList job runs. Filter by job, node, reservation, or job settings.
get_job_run_logsFetch the tail of a job run's log output.

Hardware

ToolWhat it does
get_hardwareFetch a registered hardware host.
list_hardwareList hardware visible to the caller. Filter by hardware type, team, parent, or controller flag.
get_hardware_typeFetch a hardware type definition.
list_hardware_typesList hardware types.
get_capabilityFetch a single capability definition.
list_capabilitiesList capabilities. Filter by the node that holds them.
get_operating_systemFetch an operating system definition.
list_operating_systemsList operating systems.
get_reservationFetch a single hardware reservation.
list_reservationsList hardware reservations in an organization (defaults to default org). Filter by node, team, or a start or end time range.
list_virtual_machine_profilesList the virtual machines of an organization with their cloud state (defaults to default org).
list_aws_instance_profilesList the IAM instance profiles in a cloud account's AWS account (live AWS, cached 60 s). The name is what create_virtual_machine takes. No ARN.
list_aws_vpcsList the VPCs and subnets in a cloud account's AWS region (live AWS, cached 60 s). Refuses a region outside the account's allowed regions.
get_vpc_configFetch one VPC config: the VPC that Primitive launches virtual machines into in a region. No ARN.
list_vpc_configsList the VPC configs of an organization (defaults to default org). Filter by cloud account, region, source, status, or VPC id.
get_hardware_versionFetch one system_info snapshot of a node (driver and package versions).
get_bulk_hardware_add_requestFetch one CSV import of nodes, with the count of rows that succeeded, failed, or still run.
list_bulk_hardware_add_requestsList the CSV imports of nodes in an organization (defaults to default org).
get_hardware_add_requestFetch one CSV row of a node import: its status, why it failed, and the node it created.
list_hardware_add_requestsList the CSV rows of node imports (defaults to default org). Filter by import or status.

Alerts

ToolWhat it does
list_alert_metricsList the metrics an alert policy can watch, with units and suggested thresholds.
get_alert_policyFetch one alert policy by id.
list_alert_policiesList the alert policies the caller can view, filtered by organization, tier, hardware type, or node.
list_effective_alert_policiesShow the policy that applies to each metric for an organization, hardware type, or node (org admin only).
get_hardware_alert_statusList the configurable alerts that fire on a node now.

Files

ToolWhat it does
get_fileFetch a single file's metadata.
list_filesList files within scope.

GitHub

ToolWhat it does
get_github_app_installFetch a GitHub App installation you are a member of. Its id is the install id that create_project takes.
list_github_app_installsList the GitHub App installations you are a member of.
list_github_installation_repositoriesList the repositories an installation can read (first 100). Each call makes 2 live GitHub API requests.
get_git_commitFetch a git commit of a project you can view. Its id is the commit_id that start_job_run takes. Does not call GitHub.
list_git_commitsList the git commits of the projects you can view, newest first. Filter by project, sha prefix, branch, or repository.

Billing

Billing tools return financial data — invoice PDFs, payment-method metadata, tax IDs, billing addresses — and are only accessible to users with billing permissions in Primitive (typically org admins). Treat them with the same caution as mcp:write in agentic workflows, especially with cloud-hosted agents or anything that processes untrusted content. Billing data may also be regulated personal data in some jurisdictions (e.g., a sole trader's tax ID is personal data under GDPR).

ToolWhat it does
get_active_planFetch the active subscription plan for the organization.
get_billing_infoFetch billing address / contact info, including tax ID and invoice email.
get_invoiceFetch a single invoice. Returns a short-lived PDF download URL — treat it as a bearer credential.
list_invoicesList invoices for the organization.
get_subscriptionFetch the current Stripe subscription.
list_payment_methodsList saved payment methods (card brand, last 4 digits, expiry).

Sort order and pages

Each paged list_* tool takes an order_by argument. The value is one field name, with a leading - for descending order, for example created_at, -created_at, or name. Each tool accepts a fixed list of fields; the tool schema lists them, and the tool refuses any other value with the list of allowed values. Without order_by, a tool keeps its usual order.

  • Rows with the same value sort by id, in the same direction.
  • Rows with no value (null) come last, in both directions.
  • Text-coded states such as status, severity, and level sort alphabetically.
  • A next_cursor works only with the order_by and the tool that made it. To change the order, start again with no cursor.

These tools return a computed or live list and take no order_by: list_alert_metrics, list_effective_alert_policies, list_aws_instance_profiles, list_aws_vpcs, and list_github_installation_repositories.

mcp:write

These tools change real state. Recommend human-in-the-loop approval before each call.

Organizations and teams

ToolWhat it does
update_organizationUpdate an organization's settings.
update_organization_settingsTurn node auto-update and beta agent versions on or off for an organization (org admin only).
delete_organizationDelete an organization.
update_teamUpdate a team's settings.
delete_teamDelete a team.
add_team_memberAdd an organization member to a team as ADMIN or MEMBER (org admin only).
update_team_memberChange a team member's role; the last team admin stays (org admin only).
remove_memberRemove a user from an organization.
set_member_roleChange a member's role.
create_invitationInvite a new member by email.
revoke_invitationCancel a pending invitation.

Projects and jobs

ToolWhat it does
update_projectUpdate a project's settings.
delete_projectDelete a project.
update_jobUpdate a job definition.
delete_jobDelete a job.
update_job_settingsUpdate the run configuration of a job, including its required capabilities.
create_job_scheduleAdd a crontab or interval schedule to a job. Each firing starts a job run.
delete_job_scheduleDelete one schedule of a job.
start_job_runStart a job run on the hardware you name.
rerun_job_runStart a job run again with the same inputs.
cancel_job_runCancel an in-flight job run.

Hardware

ToolWhat it does
delete_hardwareUnregister a hardware host.
rename_hardwareChange a host's display name.
set_hardware_capabilitiesReplace the capability set on a host.
set_hardware_default_jobsReplace the default-jobs list for a host.
set_hardware_maintenance_stateQuarantine a host or hold it for maintenance, or undo.
set_hardware_stateSet the health, availability, or OS-install flag.
set_hardware_typeAssign a hardware type to a host, or clear it. The save can start an OS-install or provisioning job run.
update_hardware_typeUpdate a hardware type definition.
delete_hardware_typeDelete a hardware type.
update_capabilityUpdate a capability definition.
delete_capabilityDelete a capability.
update_operating_systemUpdate an operating system definition, including its ISO, checksum, and boot files.
delete_operating_systemDelete an operating system.
create_reservationReserve a hardware host.
release_reservationRelease a held reservation.
create_virtual_machineLaunch an EC2 virtual machine, optionally with an allowlisted IAM instance profile.
create_bulk_hardware_add_requestImport nodes into an organization from an uploaded CSV. One row adds one node with its interfaces and credentials.
start_diagnosisRun the diagnosis round trip on a node: 5 queued job runs that reinstall its OS twice and take the node for hours.

Alerts

ToolWhat it does
create_alert_policyCreate an alert policy for one metric at one tier (org admin; GLOBAL needs the staff permission).
update_alert_policyChange an alert policy. Send null for a threshold to clear it.
delete_alert_policyDelete an alert policy; the target then inherits from the next broader tier.

Files

ToolWhat it does
update_fileUpdate file metadata.
delete_fileDelete a file (soft delete).
delete_filesDelete several files at once; if one id fails, no file changes.

Notifications

ToolWhat it does
update_notificationMark one of your notifications seen or archived.
archive_notificationsArchive up to 100 of your notifications. All or none.
unarchive_notificationsMove up to 100 of your notifications out of the archive. All or none.
update_notification_settingsTurn your notification email on or off, or set its address.

Inspecting the live toolset

The toolset evolves. To see exactly what your client can call right now, connect and ask the agent to list its tools — or run whoami to confirm the connection is live.

On This Page

Unscopedmcp:readOrganizations and teamsProjects and jobsHardwareAlertsFilesGitHubBillingSort order and pagesmcp:writeOrganizations and teamsProjects and jobsHardwareAlertsFilesNotificationsInspecting the live toolset
Logo

© 2026 Primitive Instruments Corporation.
All rights reserved.

DocsBrandContactCareersPrivacy PolicyTerms of Service
Logo