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.
System tools any authenticated caller can invoke. Useful for connectivity and identity checks; they don't read or change application data.
| Tool | What it does |
|---|---|
health | Returns server status. Useful as a connectivity check. |
whoami | Returns the authenticated user (id, username, email) derived from the bearer token. |
mcp:readRead-only tools. None of these change state on Primitive.
| Tool | What it does |
|---|---|
get_organization | Fetch a single organization by slug or id. |
list_organizations | List organizations the authenticated user can see. |
get_team | Fetch a single team. |
list_teams | List teams within an organization. |
get_member | Fetch a single membership record. |
list_members | List members of an organization. |
get_team_member | Fetch one team-member row (team viewers and org admins). |
list_team_members | List team-member rows of an organization; filter by team, member, role. |
get_invitation | Fetch a single pending invitation. |
list_invitations | List pending invitations for an organization. |
| Tool | What it does |
|---|---|
get_project | Fetch a single project. |
list_projects | List projects across the user's organizations. |
get_job | Fetch a single job. |
list_jobs | List jobs within a project. |
get_job_settings | Fetch the run configuration for a job, with its schedules. |
list_job_settings | List job settings records. |
get_job_config_file | Fetch one job config file (.primitive/*.yaml): the raw YAML and its parse error. |
list_job_config_files | List job config files. Filter by project, commit, or parse error. |
get_job_run | Fetch a single job run. |
list_job_runs | List job runs. Filter by job, node, reservation, or job settings. |
get_job_run_logs | Fetch the tail of a job run's log output. |
| Tool | What it does |
|---|---|
get_hardware | Fetch a registered hardware host. |
list_hardware | List hardware visible to the caller. Filter by hardware type, team, parent, or controller flag. |
get_hardware_type | Fetch a hardware type definition. |
list_hardware_types | List hardware types. |
get_capability | Fetch a single capability definition. |
list_capabilities | List capabilities. Filter by the node that holds them. |
get_operating_system | Fetch an operating system definition. |
list_operating_systems | List operating systems. |
get_reservation | Fetch a single hardware reservation. |
list_reservations | List hardware reservations in an organization (defaults to default org). Filter by node, team, or a start or end time range. |
list_virtual_machine_profiles | List the virtual machines of an organization with their cloud state (defaults to default org). |
list_aws_instance_profiles | List 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_vpcs | List 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_config | Fetch one VPC config: the VPC that Primitive launches virtual machines into in a region. No ARN. |
list_vpc_configs | List the VPC configs of an organization (defaults to default org). Filter by cloud account, region, source, status, or VPC id. |
get_hardware_version | Fetch one system_info snapshot of a node (driver and package versions). |
get_bulk_hardware_add_request | Fetch one CSV import of nodes, with the count of rows that succeeded, failed, or still run. |
list_bulk_hardware_add_requests | List the CSV imports of nodes in an organization (defaults to default org). |
get_hardware_add_request | Fetch one CSV row of a node import: its status, why it failed, and the node it created. |
list_hardware_add_requests | List the CSV rows of node imports (defaults to default org). Filter by import or status. |
| Tool | What it does |
|---|---|
list_alert_metrics | List the metrics an alert policy can watch, with units and suggested thresholds. |
get_alert_policy | Fetch one alert policy by id. |
list_alert_policies | List the alert policies the caller can view, filtered by organization, tier, hardware type, or node. |
list_effective_alert_policies | Show the policy that applies to each metric for an organization, hardware type, or node (org admin only). |
get_hardware_alert_status | List the configurable alerts that fire on a node now. |
| Tool | What it does |
|---|---|
get_file | Fetch a single file's metadata. |
list_files | List files within scope. |
| Tool | What it does |
|---|---|
get_github_app_install | Fetch a GitHub App installation you are a member of. Its id is the install id that create_project takes. |
list_github_app_installs | List the GitHub App installations you are a member of. |
list_github_installation_repositories | List the repositories an installation can read (first 100). Each call makes 2 live GitHub API requests. |
get_git_commit | Fetch 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_commits | List the git commits of the projects you can view, newest first. Filter by project, sha prefix, branch, or repository. |
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).
| Tool | What it does |
|---|---|
get_active_plan | Fetch the active subscription plan for the organization. |
get_billing_info | Fetch billing address / contact info, including tax ID and invoice email. |
get_invoice | Fetch a single invoice. Returns a short-lived PDF download URL — treat it as a bearer credential. |
list_invoices | List invoices for the organization. |
get_subscription | Fetch the current Stripe subscription. |
list_payment_methods | List saved payment methods (card brand, last 4 digits, expiry). |
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.
id, in the same direction.status, severity, and level sort
alphabetically.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:writeThese tools change real state. Recommend human-in-the-loop approval before each call.
| Tool | What it does |
|---|---|
update_organization | Update an organization's settings. |
update_organization_settings | Turn node auto-update and beta agent versions on or off for an organization (org admin only). |
delete_organization | Delete an organization. |
update_team | Update a team's settings. |
delete_team | Delete a team. |
add_team_member | Add an organization member to a team as ADMIN or MEMBER (org admin only). |
update_team_member | Change a team member's role; the last team admin stays (org admin only). |
remove_member | Remove a user from an organization. |
set_member_role | Change a member's role. |
create_invitation | Invite a new member by email. |
revoke_invitation | Cancel a pending invitation. |
| Tool | What it does |
|---|---|
update_project | Update a project's settings. |
delete_project | Delete a project. |
update_job | Update a job definition. |
delete_job | Delete a job. |
update_job_settings | Update the run configuration of a job, including its required capabilities. |
create_job_schedule | Add a crontab or interval schedule to a job. Each firing starts a job run. |
delete_job_schedule | Delete one schedule of a job. |
start_job_run | Start a job run on the hardware you name. |
rerun_job_run | Start a job run again with the same inputs. |
cancel_job_run | Cancel an in-flight job run. |
| Tool | What it does |
|---|---|
delete_hardware | Unregister a hardware host. |
rename_hardware | Change a host's display name. |
set_hardware_capabilities | Replace the capability set on a host. |
set_hardware_default_jobs | Replace the default-jobs list for a host. |
set_hardware_maintenance_state | Quarantine a host or hold it for maintenance, or undo. |
set_hardware_state | Set the health, availability, or OS-install flag. |
set_hardware_type | Assign a hardware type to a host, or clear it. The save can start an OS-install or provisioning job run. |
update_hardware_type | Update a hardware type definition. |
delete_hardware_type | Delete a hardware type. |
update_capability | Update a capability definition. |
delete_capability | Delete a capability. |
update_operating_system | Update an operating system definition, including its ISO, checksum, and boot files. |
delete_operating_system | Delete an operating system. |
create_reservation | Reserve a hardware host. |
release_reservation | Release a held reservation. |
create_virtual_machine | Launch an EC2 virtual machine, optionally with an allowlisted IAM instance profile. |
create_bulk_hardware_add_request | Import nodes into an organization from an uploaded CSV. One row adds one node with its interfaces and credentials. |
start_diagnosis | Run the diagnosis round trip on a node: 5 queued job runs that reinstall its OS twice and take the node for hours. |
| Tool | What it does |
|---|---|
create_alert_policy | Create an alert policy for one metric at one tier (org admin; GLOBAL needs the staff permission). |
update_alert_policy | Change an alert policy. Send null for a threshold to clear it. |
delete_alert_policy | Delete an alert policy; the target then inherits from the next broader tier. |
| Tool | What it does |
|---|---|
update_file | Update file metadata. |
delete_file | Delete a file (soft delete). |
delete_files | Delete several files at once; if one id fails, no file changes. |
| Tool | What it does |
|---|---|
update_notification | Mark one of your notifications seen or archived. |
archive_notifications | Archive up to 100 of your notifications. All or none. |
unarchive_notifications | Move up to 100 of your notifications out of the archive. All or none. |
update_notification_settings | Turn your notification email on or off, or set its address. |
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.