Serveur MCP YorkHost

Le serveur MCP expose vos services à un assistant IA : Claude (web, desktop, Claude Code), ChatGPT, Cursor, VS Code… Chaque outil correspond à une route de l'API : mêmes permissions, mêmes restrictions de services, même journal (visible dans Clés API de votre espace client, source « MCP »).

• URL du serveur : https://api.yorkhost.fr/client/mcp
• Transport : Streamable HTTP, sans état
• Authentification : connexion à votre compte YorkHost (OAuth), ou en-tête Authorization: Bearer <clé API>

La double authentification doit être active sur votre compte YorkHost, dans les deux cas.

Connexion par votre compte (Claude.ai, ChatGPT…)

Aucune clé à copier : l'application vous envoie sur votre espace client YorkHost, vous choisissez ce qu'elle pourra faire, et c'est tout.

Claude (claude.ai et Claude Desktop) : Paramètres → Connecteurs → Ajouter un connecteur personnalisé, nommez-le « YorkHost » et collez l'URL https://api.yorkhost.fr/client/mcp. Laissez les champs OAuth avancés vides, puis cliquez sur Se connecter.

ChatGPT : dans les paramètres des connecteurs (mode développeur), créez un connecteur avec l'URL https://api.yorkhost.fr/client/mcp et l'authentification OAuth.

Claude Code :

claude mcp add --transport http yorkhost https://api.yorkhost.fr/client/mcp

puis tapez /mcp dans Claude Code et choisissez Authenticate.

Sur la page d'autorisation YorkHost :

1. Connectez-vous si besoin (mot de passe, Google, Discord, double authentification).
2. Vérifiez l'adresse de retour affichée (par exemple claude.ai) : c'est elle qui identifie l'application, pas son nom.
3. Cochez les permissions et, si vous voulez, limitez l'accès à certains services. Les permissions sensibles ne sont jamais cochées d'office.
4. Cliquez sur Autoriser. Vous recevez un e-mail de confirmation.

L'application apparaît ensuite dans Clés API → Applications connectées, où vous pouvez la déconnecter à tout moment. Son accès est aussi coupé si vous changez de mot de passe ou désactivez la double authentification. Les jetons d'accès durent une heure et sont renouvelés automatiquement par l'application.

Connexion par clé API

Pour les clients qui ne gèrent pas OAuth, ou pour un usage scripté, créez une clé dans Clés API et passez-la dans l'en-tête Authorization.

Claude Code

claude mcp add --transport http yorkhost https://api.yorkhost.fr/client/mcp \
  --header "Authorization: Bearer yhk_client_v1_..."

Cursor / VS Code / autre client MCP : ajoutez un serveur de type HTTP avec l'URL ci-dessus et l'en-tête Authorization.

astuce

Créez une clé dédiée à votre assistant, avec le modèle « Agent IA (sans action destructive) ». Vous pourrez la révoquer à tout moment sans toucher à vos autres intégrations. L'assistant ne voit que les outils autorisés par les permissions de la clé.

Page générée

Cette page est générée automatiquement depuis le catalogue d'outils du serveur MCP. Ne la modifiez pas à la main.

Outils

Outil	Description	Permission	Effet
get_account	Profile of the authenticated YorkHost account (name, email, credit balance).	account:read	lecture
list_services	List the account's services (VPS, game servers, domains…) with their IDs, type and status. Call this first to find a service ID.	services:read	lecture
get_service	Details of one service.	services:read	lecture
list_invoices	List invoices (status, amount, due date).	billing:read	lecture
get_invoice	One invoice with its line items.	billing:read	lecture
get_payment_link	Status of an invoice and, if unpaid, the secure YorkHost page where the user pays it (card with 3-D Secure, PayPal, account credit). Share the link with the user; never ask for card details in the chat.	billing:read	lecture
list_products	Products that can be ordered through the API, with prices per billing cycle (m, q, s, a), plus the agent sandbox offers.	services:read	lecture
create_order	Order a product (creates a real invoice). Two steps: call WITHOUT confirmation_token to get the price and a token (nothing is ordered), show the price to the user and get explicit approval, then call again WITH confirmation_token. Returns the invoice and its payment_url.	orders:write	action
list_tickets	List support tickets.	tickets:read	lecture
get_ticket	One support ticket with its messages.	tickets:read	lecture
create_ticket	Open a support ticket. Ask the user to confirm the content before calling.	tickets:write	action
reply_ticket	Reply to a support ticket.	tickets:write	action
get_vps	Status, resources and IPs of a VPS.	vps:read	lecture
get_vps_metrics	CPU, RAM and network usage of a VPS over the last hour.	vps:read	lecture
vps_power	Start, stop or restart a VPS. Stopping interrupts the customer's services: confirm with the user first.	vps:power	action
get_game_server	Status, address and live resources of a game server (FiveM, Minecraft, bots…).	game:read	lecture
get_game_server_metrics	CPU and RAM history of a game server.	game:read	lecture
game_server_power	Start, stop, restart or kill a game server. Stopping disconnects players: confirm with the user first.	game:power	action
get_ddos_attacks	DDoS attacks detected and mitigated on the account's IPs and game servers, with the protected targets. Optionally for one IP address only.	antiddos:read	lecture
list_ddos_rules	Anti-DDoS rules of the account and what can be created: account_level (standard or extended), policies the account may use (name, protocols, restricted = named sources and precise ports required, extended_only), limits, eligible_ips (IPv4 addresses a rule can protect) and rules (id, ip, policy, proto_list, dport_list, sport_list, sip_list, description, status, position). status: pending (requested, not yet applied by the YorkHost NOC), active, suspended, dormant or rejected. position: evaluation order among the rules of the same IP (1 = first). Optionally for one IP address only.	antiddos:read	lecture
create_ddos_rule	Request a new anti-DDoS rule on one of the account's eligible IPv4 addresses (from list_ddos_rules). Call list_ddos_rules first: the policy must be one of its policies, with protocols and ports that fit it. The rule is created with status pending and applied later by the YorkHost NOC. A wrong rule (e.g. Drop on the game port) can cut legitimate traffic: show the exact rule to the user and get explicit approval before calling. Validation errors carry a code and the field to fix.	antiddos:write	action
move_ddos_rule	Change the evaluation order of an anti-DDoS rule (id from list_ddos_rules): put it at position among the rules of the same IP (1 = evaluated first; a too large position puts it last). Confirm with the user first.	antiddos:write	action
delete_ddos_rule	Delete one anti-DDoS rule of the account (exact id from list_ddos_rules). The protection it gave stops once applied: confirm the rule (ip, policy, ports) with the user first.	antiddos:write	action
enable_authoritative_dns	Open inbound UDP port 53 on one of the account's eligible IPv4 addresses (from list_ddos_rules) for an AUTHORITATIVE DNS server the user runs there (e.g. ns1 of their domain). YorkHost first checks the server over TCP 53: it must answer authoritatively (AA bit) for zone, refuse recursion, refuse zone transfers (AXFR) from anyone but its secondaries, and give minimal ANY answers. If a check fails, nothing is changed and the error carries a code (dns_unreachable, dns_not_authoritative, dns_open_resolver, dns_axfr_open, dns_any_large, dns_zone_invalid, dns_preset_exists, too_soon) and a message: relay that message to the user as is and do not try to work around it. On success, a rule (policy General UDP Countermeasure, udp, port 53, kind dns_authoritative) is created: traffic stays mitigated by the anti-DDoS, but the default resolver whitelist no longer applies to this IP; the server is re-checked weekly and the rule is removed automatically if recursion or AXFR become open. Do not promise anything about the level of protection. This changes how traffic to the IP is filtered: call it only after the user has explicitly asked for it and approved the exact IP and zone. Undo with delete_ddos_rule.	antiddos:write	action
dns_list_domains	Domains and DNS zones of the account. For each one: domain name (use it in the other dns_* tools), kind (domain or dnszone), status, expiry, ns_state (managed = delegated to YorkHost nameservers, mixed, external, unknown), zone_exists, readonly and source. A readonly zone is hosted on a cPanel web hosting: it can be read here but must be edited in cPanel. Records only take effect publicly when ns_state is managed.	dns:read	lecture
dns_get_domain	DNS state of one domain: nameservers (state, live delegation, registrar, managed) and the YorkHost zone (exists, readonly, source, dnssec, serial, record count).	dns:read	lecture
dns_list_records	Records of a domain's DNS zone hosted at YorkHost: id (needed to update or delete), name (relative to the zone, @ = apex), fqdn, type, ttl, content, the type's fields (value; MX/SRV priority, weight, port, target; CAA flags, tag, value) and protected. Protected records (NS and SOA at the zone apex) are managed by YorkHost and cannot be changed or deleted.	dns:read	lecture
dns_add_record	Add a record to a domain's DNS zone at YorkHost (A, AAAA, CNAME, MX, TXT, SRV, CAA…). Only send the fields of the record type (MX: priority; SRV: priority, weight, port; CAA: flags, tag): other fields are refused. Changes are public and cached for the TTL: confirm with the user first. NS and SOA records at the zone apex are protected and cannot be changed; zones hosted on cPanel are read-only (edit them in cPanel). Validation errors (code rec_err_*) explain what to fix.	dns:write	action
dns_update_record	Replace a record of a domain's DNS zone (id from dns_list_records): send the complete record (name, type, value and, when relevant, ttl, priority, weight, port), not only the changed field. Only send the fields of the record type (MX: priority; SRV: priority, weight, port; CAA: flags, tag): other fields are refused. Changes are public and cached for the TTL: confirm with the user first. NS and SOA records at the zone apex are protected and cannot be changed; zones hosted on cPanel are read-only (edit them in cPanel). Validation errors (code rec_err_*) explain what to fix.	dns:write	action
dns_delete_record	Delete a record of a domain's DNS zone (id from dns_list_records). Deleting an A, MX or CNAME record can take a website or mailbox offline: confirm with the user first. NS and SOA at the zone apex are protected; zones hosted on cPanel are read-only.	dns:write	action
dns_export_zone	Export a domain's DNS zone hosted at YorkHost as a BIND zone file (field bind), e.g. as a backup before changes.	dns:read	lecture
rdns_list	Reverse DNS (PTR) of the IP addresses of the account's services (VPS, dedicated servers…): ip, service_id, service_name, current ptr, default hostname and state (ok, pending, nozone, error). Optionally for one service only.	rdns:read	lecture
rdns_set	Set the reverse DNS (PTR) of one of the account's IP addresses to a hostname. The hostname should resolve to the same IP (A or AAAA record), as mail servers check it: otherwise the PTR is still set and the result carries warning rdns_warn_forward — tell the user. Confirm the hostname with the user first.	rdns:write	action
rdns_reset	Restore the default YorkHost reverse DNS (PTR) of one of the account's IP addresses.	rdns:write	action
rdns_bulk	Set the reverse DNS of many IP addresses at once (up to 512 lines). An empty hostname restores the default PTR. Always call first with check_only=true: nothing is changed and the report (rows) gives, for each line, the result, error and warning; needed/remaining tell whether the batch fits the account's hourly change limit. Show it to the user, then call again with check_only=false to apply.	rdns:write	action
list_sandboxes	Agent sandboxes (free trial VMs for AI agents: Linux, Linux desktop, Windows desktop) of the account, with SSH command, preview URL, expiry and, when being turned into a VPS, the transfer progress.	sandbox:read	lecture
create_sandbox	Create a free trial VM for an AI agent. It runs for its run window (2 hours by default when created from an account; see free_minutes in list_products and run_until in the result), then is stopped, and deleted with its files unless turned into a VPS with keep_sandbox. No public IP: SSH through the YorkHost gateway, web apps on the HTTPS preview URL. kind: linux (SSH, coding agents preinstalled), desktop (Linux desktop in the browser via noVNC, for computer use) or windows (Windows desktop). Requires the SSH public key the agent will connect with; SSH keys registered with add_sandbox_key are authorized too. Account secrets (set_sandbox_secret) are exported as environment variables in Linux sandboxes unless inject_secrets is false.	sandbox:write	action
sandbox_links	New desktop link for a sandbox (the previous link stops working).	sandbox:write	action
keep_sandbox	Turn a trial sandbox into a regular YorkHost VPS (order + invoice; public IP; its /home/agent folder is copied into the new VPS once paid). Two steps like create_order: preflight without confirmation_token, user approval, then confirm.	orders:write	action
claim_sandbox	Attach an anonymous trial sandbox created with ssh yorkhost.sh to this account and turn it into a regular YorkHost VPS (order + invoice; its /home/agent folder is copied into the VPS once paid). Takes the claim link or token printed at creation. Only claim a sandbox the user created: its files come from its creator (SSH keys found in it are not copied; the account's registered SSH keys are installed for the agent user on the VPS). Two steps: preflight without confirmation_token, user approval, then confirm.	orders:write	action
delete_sandbox	Delete a trial sandbox and all its files. Irreversible: confirm with the user first.	sandbox:write	action
sandbox_exec	Run a shell command inside one of the account's running sandboxes (kinds linux and desktop, not windows), without SSH. The command runs as bash -lc <command> as the Linux user agent in the trial VM (home /home/agent, passwordless sudo for root tasks such as apt-get), in /home/agent or cwd. Returns exit_code, stdout and stderr (each truncated beyond 256 KiB, see stdout_truncated/stderr_truncated), timed_out and duration_ms. timeout_seconds defaults to 60 (max 300): the command and its children are killed at the timeout. For servers and long jobs, start them in the background with their output redirected (e.g. nohup npm run dev > /tmp/dev.log 2>&1 &), then poll the log. The sandbox has no public IP: to test a web app, listen on 0.0.0.0:8080 and open the sandbox's preview_url from list_sandboxes (https://<sandbox_id>-8080.yorkhost.sh; for another port, change 8080 in the hostname), or curl localhost:<port> here.Outbound traffic is limited to web, git, SSH and DNS. At most 4 commands run at once per sandbox.	sandbox:write	action
sandbox_list_files	List a directory inside a running sandbox (kinds linux and desktop), read as the Linux user agent: name (relative to path), type (file, dir, symlink, other), size, mode and mtime. path must be under /home/agent or /tmp (relative paths start from /home/agent; default /home/agent). depth 1 to 3 lists subdirectories recursively (default 1). At most 1000 entries (truncated flag); symlinks are not followed.	sandbox:read	lecture
sandbox_read_file	Read a file inside a running sandbox (kinds linux and desktop), as the Linux user agent (its permissions apply). path must be under /home/agent or /tmp (relative paths start from /home/agent). Returns the first 1 MiB: encoding utf-8 (content is the text) or base64 for binary files, plus size and truncated.	sandbox:read	lecture
sandbox_write_file	Create or overwrite a file inside a running sandbox (kinds linux and desktop), as the Linux user agent; missing parent directories are created and the file is replaced atomically. path must be under /home/agent or /tmp (relative paths start from /home/agent). content is text (encoding utf-8, default) or base64 (encoding base64) for binary data, at most 1 MiB. mode is an optional octal permission such as 755 (default: kept when overwriting an existing file).	sandbox:write	action
list_sandbox_keys	SSH public keys registered on the account for agent sandboxes (fingerprint, name). Each of them can connect to every sandbox of the account (ssh <sandbox id>@yorkhost.sh) and is added to sandboxes created later.	sandbox:read	lecture
add_sandbox_key	Register an SSH PUBLIC key on the account (max 10): it can then connect to all the account's sandboxes, current and future. Never send a private key.	sandbox:write	action
remove_sandbox_key	Remove an SSH key from the account: it can no longer connect to the account's sandboxes through the gateway.	sandbox:write	action
list_sandbox_secrets	Names of the account's sandbox secrets (environment variables such as ANTHROPIC_API_KEY, OPENAI_API_KEY, GITHUB_TOKEN exported in new Linux sandboxes). Values are never returned.	sandbox:read	lecture
set_sandbox_secret	Create or replace an account secret exported as an environment variable in the account's new Linux sandboxes (max 20, value up to 4 KiB). Stored encrypted and never shown again: only use a value the user explicitly gave for this purpose, and do not repeat it back.	sandbox:write	action
delete_sandbox_secret	Delete an account secret (sandboxes created later no longer get it; existing ones keep their environment until deleted).	sandbox:write	action

Détail des outils

get_account

Profile of the authenticated YorkHost account (name, email, credit balance).

• Permission : account:read
• Route équivalente : GET /client/v1/account
• Arguments : aucun

list_services

List the account's services (VPS, game servers, domains…) with their IDs, type and status. Call this first to find a service ID.

• Permission : services:read
• Route équivalente : GET /client/v1/services
• Arguments : aucun

get_service

Details of one service.

• Permission : services:read
• Route équivalente : GET /client/v1/services/:id

Arguments :

Argument	Type	Description
service_id (requis)	integer	YorkHost service ID (from list_services)

list_invoices

List invoices (status, amount, due date).

• Permission : billing:read
• Route équivalente : GET /client/v1/invoices
• Arguments : aucun

get_invoice

One invoice with its line items.

• Permission : billing:read
• Route équivalente : GET /client/v1/invoices/:id

Arguments :

Argument	Type	Description
invoice_id (requis)	integer

get_payment_link

Status of an invoice and, if unpaid, the secure YorkHost page where the user pays it (card with 3-D Secure, PayPal, account credit). Share the link with the user; never ask for card details in the chat.

• Permission : billing:read
• Route équivalente : GET /client/v1/invoices/:id/payment-link

Arguments :

Argument	Type	Description
invoice_id (requis)	integer

list_products

Products that can be ordered through the API, with prices per billing cycle (m, q, s, a), plus the agent sandbox offers.

• Permission : services:read
• Route équivalente : GET /client/v1/catalog
• Arguments : aucun

create_order

Order a product (creates a real invoice). Two steps: call WITHOUT confirmation_token to get the price and a token (nothing is ordered), show the price to the user and get explicit approval, then call again WITH confirmation_token. Returns the invoice and its payment_url.

• Permission : orders:write
• Route équivalente : POST /client/v1/orders

Arguments :

Argument	Type	Description
confirmation_token	string	From the preflight call, only after the user approved the price
cycle	string	Billing cycle (default m = monthly)
product_id (requis)	integer	From list_products

list_tickets

List support tickets.

• Permission : tickets:read
• Route équivalente : GET /client/v1/tickets
• Arguments : aucun

get_ticket

One support ticket with its messages.

• Permission : tickets:read
• Route équivalente : GET /client/v1/tickets/:id

Arguments :

Argument	Type	Description
ticket_id (requis)	string	Ticket number or ID

create_ticket

Open a support ticket. Ask the user to confirm the content before calling.

• Permission : tickets:write
• Route équivalente : POST /client/v1/tickets

Arguments :

Argument	Type	Description
body (requis)	string
request_type	string
service_id	integer	YorkHost service ID (from list_services)
subject (requis)	string

reply_ticket

Reply to a support ticket.

• Permission : tickets:write
• Route équivalente : POST /client/v1/tickets/:id/reply

Arguments :

Argument	Type	Description
body (requis)	string
ticket_id (requis)	string

get_vps

Status, resources and IPs of a VPS.

• Permission : vps:read
• Route équivalente : GET /client/v1/vps/:id

Arguments :

Argument	Type	Description
service_id (requis)	integer	YorkHost service ID (from list_services)

get_vps_metrics

CPU, RAM and network usage of a VPS over the last hour.

• Permission : vps:read
• Route équivalente : GET /client/v1/vps/:id/metrics

Arguments :

Argument	Type	Description
service_id (requis)	integer	YorkHost service ID (from list_services)

vps_power

Start, stop or restart a VPS. Stopping interrupts the customer's services: confirm with the user first.

• Permission : vps:power
• Route équivalente : POST /client/v1/vps/:id/power

Arguments :

Argument	Type	Description
action (requis)	string
service_id (requis)	integer	YorkHost service ID (from list_services)

get_game_server

Status, address and live resources of a game server (FiveM, Minecraft, bots…).

• Permission : game:read
• Route équivalente : GET /client/v1/game-servers/:id

Arguments :

Argument	Type	Description
service_id (requis)	integer	YorkHost service ID (from list_services)

get_game_server_metrics

CPU and RAM history of a game server.

• Permission : game:read
• Route équivalente : GET /client/v1/game-servers/:id/metrics

Arguments :

Argument	Type	Description
service_id (requis)	integer	YorkHost service ID (from list_services)

game_server_power

Start, stop, restart or kill a game server. Stopping disconnects players: confirm with the user first.

• Permission : game:power
• Route équivalente : POST /client/v1/game-servers/:id/power

Arguments :

Argument	Type	Description
action (requis)	string
service_id (requis)	integer	YorkHost service ID (from list_services)

get_ddos_attacks

DDoS attacks detected and mitigated on the account's IPs and game servers, with the protected targets. Optionally for one IP address only.

• Permission : antiddos:read
• Route équivalente : GET /client/v1/antiddos

Arguments :

Argument	Type	Description
days	integer	History depth in days (default 90)
ip	string	One IP address of the account (only this IP)

list_ddos_rules

Anti-DDoS rules of the account and what can be created: account_level (standard or extended), policies the account may use (name, protocols, restricted = named sources and precise ports required, extended_only), limits, eligible_ips (IPv4 addresses a rule can protect) and rules (id, ip, policy, proto_list, dport_list, sport_list, sip_list, description, status, position). status: pending (requested, not yet applied by the YorkHost NOC), active, suspended, dormant or rejected. position: evaluation order among the rules of the same IP (1 = first). Optionally for one IP address only.

• Permission : antiddos:read
• Route équivalente : GET /client/v1/antiddos/rules

Arguments :

Argument	Type	Description
ip	string	One IP address of the account (only this IP)

create_ddos_rule

Request a new anti-DDoS rule on one of the account's eligible IPv4 addresses (from list_ddos_rules). Call list_ddos_rules first: the policy must be one of its policies, with protocols and ports that fit it. The rule is created with status pending and applied later by the YorkHost NOC. A wrong rule (e.g. Drop on the game port) can cut legitimate traffic: show the exact rule to the user and get explicit approval before calling. Validation errors carry a code and the field to fix.

• Permission : antiddos:write
• Route équivalente : POST /client/v1/antiddos/rules

Arguments :

Argument	Type	Description
description	string	Short note shown in the client area
dport_list	array	Destination ports: 30120 or a range 27015-27030
ip (requis)	string	IPv4 address from eligible_ips (list_ddos_rules)
policy (requis)	string	Policy name from policies (list_ddos_rules), e.g. FiveM UDP, Minecraft Protection, Rate Limiter Low, Drop
position	integer	Position among the IP's rules (1 = evaluated first). Default: last
proto_list	array	Protocols (required by most policies)
sip_list	array	Source addresses or networks (required for Allow List)
sport_list	array	Source ports

move_ddos_rule

Change the evaluation order of an anti-DDoS rule (id from list_ddos_rules): put it at position among the rules of the same IP (1 = evaluated first; a too large position puts it last). Confirm with the user first.

• Permission : antiddos:write
• Route équivalente : POST /client/v1/antiddos/rules/:id/move

Arguments :

Argument	Type	Description
position (requis)	integer	New position (1 = first)
rule_id (requis)	string	Rule id from list_ddos_rules

delete_ddos_rule

Delete one anti-DDoS rule of the account (exact id from list_ddos_rules). The protection it gave stops once applied: confirm the rule (ip, policy, ports) with the user first.

• Permission : antiddos:write
• Route équivalente : DELETE /client/v1/antiddos/rules/:id

Arguments :

Argument	Type	Description
rule_id (requis)	string	Rule id from list_ddos_rules

enable_authoritative_dns

Open inbound UDP port 53 on one of the account's eligible IPv4 addresses (from list_ddos_rules) for an AUTHORITATIVE DNS server the user runs there (e.g. ns1 of their domain). YorkHost first checks the server over TCP 53: it must answer authoritatively (AA bit) for zone, refuse recursion, refuse zone transfers (AXFR) from anyone but its secondaries, and give minimal ANY answers. If a check fails, nothing is changed and the error carries a code (dns_unreachable, dns_not_authoritative, dns_open_resolver, dns_axfr_open, dns_any_large, dns_zone_invalid, dns_preset_exists, too_soon) and a message: relay that message to the user as is and do not try to work around it. On success, a rule (policy General UDP Countermeasure, udp, port 53, kind dns_authoritative) is created: traffic stays mitigated by the anti-DDoS, but the default resolver whitelist no longer applies to this IP; the server is re-checked weekly and the rule is removed automatically if recursion or AXFR become open. Do not promise anything about the level of protection. This changes how traffic to the IP is filtered: call it only after the user has explicitly asked for it and approved the exact IP and zone. Undo with delete_ddos_rule.

• Permission : antiddos:write
• Route équivalente : POST /client/v1/antiddos/rules/dns-authoritative

Arguments :

Argument	Type	Description
ip (requis)	string	IPv4 address of the DNS server, from eligible_ips (list_ddos_rules)
zone (requis)	string	Domain the server is authoritative for, e.g. example.com

dns_list_domains

Domains and DNS zones of the account. For each one: domain name (use it in the other dns_* tools), kind (domain or dnszone), status, expiry, ns_state (managed = delegated to YorkHost nameservers, mixed, external, unknown), zone_exists, readonly and source. A readonly zone is hosted on a cPanel web hosting: it can be read here but must be edited in cPanel. Records only take effect publicly when ns_state is managed.

• Permission : dns:read
• Route équivalente : GET /client/v1/dns/domains
• Arguments : aucun

dns_get_domain

DNS state of one domain: nameservers (state, live delegation, registrar, managed) and the YorkHost zone (exists, readonly, source, dnssec, serial, record count).

• Permission : dns:read
• Route équivalente : GET /client/v1/dns/domains/:domain

Arguments :

Argument	Type	Description
domain (requis)	string	Domain name, e.g. example.com (from dns_list_domains)

dns_list_records

Records of a domain's DNS zone hosted at YorkHost: id (needed to update or delete), name (relative to the zone, @ = apex), fqdn, type, ttl, content, the type's fields (value; MX/SRV priority, weight, port, target; CAA flags, tag, value) and protected. Protected records (NS and SOA at the zone apex) are managed by YorkHost and cannot be changed or deleted.

• Permission : dns:read
• Route équivalente : GET /client/v1/dns/domains/:domain/records

Arguments :

Argument	Type	Description
domain (requis)	string	Domain name, e.g. example.com (from dns_list_domains)

dns_add_record

Add a record to a domain's DNS zone at YorkHost (A, AAAA, CNAME, MX, TXT, SRV, CAA…). Only send the fields of the record type (MX: priority; SRV: priority, weight, port; CAA: flags, tag): other fields are refused. Changes are public and cached for the TTL: confirm with the user first. NS and SOA records at the zone apex are protected and cannot be changed; zones hosted on cPanel are read-only (edit them in cPanel). Validation errors (code rec_err_*) explain what to fix.

• Permission : dns:write
• Route équivalente : POST /client/v1/dns/domains/:domain/records

Arguments :

Argument	Type	Description
domain (requis)	string	Domain name, e.g. example.com (from dns_list_domains)
flags	integer	CAA flags (usually 0)
name (requis)	string	Record name relative to the zone: @ for the zone apex, www, mail, _dmarc…
port	integer	SRV port
priority	integer	MX and SRV priority
tag	string	CAA tag
ttl	integer	TTL in seconds (default chosen by YorkHost)
type (requis)	string	A, AAAA, CNAME, MX, TXT, SRV, CAA…
value (requis)	string	Record value: IP for A/AAAA, target hostname for CNAME/MX/SRV, text for TXT, CA domain for CAA
weight	integer	SRV weight

dns_update_record

Replace a record of a domain's DNS zone (id from dns_list_records): send the complete record (name, type, value and, when relevant, ttl, priority, weight, port), not only the changed field. Only send the fields of the record type (MX: priority; SRV: priority, weight, port; CAA: flags, tag): other fields are refused. Changes are public and cached for the TTL: confirm with the user first. NS and SOA records at the zone apex are protected and cannot be changed; zones hosted on cPanel are read-only (edit them in cPanel). Validation errors (code rec_err_*) explain what to fix.

• Permission : dns:write
• Route équivalente : PATCH /client/v1/dns/domains/:domain/records/:record_id

Arguments :

Argument	Type	Description
domain (requis)	string	Domain name, e.g. example.com (from dns_list_domains)
flags	integer	CAA flags (usually 0)
name (requis)	string	Record name relative to the zone: @ for the zone apex, www, mail, _dmarc…
port	integer	SRV port
priority	integer	MX and SRV priority
record_id (requis)	string	Record id from dns_list_records
tag	string	CAA tag
ttl	integer	TTL in seconds (default chosen by YorkHost)
type (requis)	string	A, AAAA, CNAME, MX, TXT, SRV, CAA…
value (requis)	string	Record value: IP for A/AAAA, target hostname for CNAME/MX/SRV, text for TXT, CA domain for CAA
weight	integer	SRV weight

dns_delete_record

Delete a record of a domain's DNS zone (id from dns_list_records). Deleting an A, MX or CNAME record can take a website or mailbox offline: confirm with the user first. NS and SOA at the zone apex are protected; zones hosted on cPanel are read-only.

• Permission : dns:write
• Route équivalente : DELETE /client/v1/dns/domains/:domain/records/:record_id

Arguments :

Argument	Type	Description
domain (requis)	string	Domain name, e.g. example.com (from dns_list_domains)
record_id (requis)	string	Record id from dns_list_records

dns_export_zone

Export a domain's DNS zone hosted at YorkHost as a BIND zone file (field bind), e.g. as a backup before changes.

• Permission : dns:read
• Route équivalente : GET /client/v1/dns/domains/:domain/export

Arguments :

Argument	Type	Description
domain (requis)	string	Domain name, e.g. example.com (from dns_list_domains)

rdns_list

Reverse DNS (PTR) of the IP addresses of the account's services (VPS, dedicated servers…): ip, service_id, service_name, current ptr, default hostname and state (ok, pending, nozone, error). Optionally for one service only.

• Permission : rdns:read
• Route équivalente : GET /client/v1/rdns

Arguments :

Argument	Type	Description
service_id	integer	YorkHost service ID (from list_services)

rdns_set

Set the reverse DNS (PTR) of one of the account's IP addresses to a hostname. The hostname should resolve to the same IP (A or AAAA record), as mail servers check it: otherwise the PTR is still set and the result carries warning rdns_warn_forward — tell the user. Confirm the hostname with the user first.

• Permission : rdns:write
• Route équivalente : PUT /client/v1/rdns/:ip

Arguments :

Argument	Type	Description
hostname (requis)	string	Fully qualified hostname, e.g. mail.example.com
ip (requis)	string	IPv4 or IPv6 address of one of the account's services (from rdns_list)

rdns_reset

Restore the default YorkHost reverse DNS (PTR) of one of the account's IP addresses.

• Permission : rdns:write
• Route équivalente : DELETE /client/v1/rdns/:ip

Arguments :

Argument	Type	Description
ip (requis)	string	IPv4 or IPv6 address of one of the account's services (from rdns_list)

rdns_bulk

Set the reverse DNS of many IP addresses at once (up to 512 lines). An empty hostname restores the default PTR. Always call first with check_only=true: nothing is changed and the report (rows) gives, for each line, the result, error and warning; needed/remaining tell whether the batch fits the account's hourly change limit. Show it to the user, then call again with check_only=false to apply.

• Permission : rdns:write
• Route équivalente : POST /client/v1/rdns/bulk

Arguments :

Argument	Type	Description
check_only (requis)	boolean	true = dry run (report only, nothing changed)
entries (requis)	array	Lines {ip, hostname}

list_sandboxes

Agent sandboxes (free trial VMs for AI agents: Linux, Linux desktop, Windows desktop) of the account, with SSH command, preview URL, expiry and, when being turned into a VPS, the transfer progress.

• Permission : sandbox:read
• Route équivalente : GET /client/v1/sandboxes
• Arguments : aucun

create_sandbox

Create a free trial VM for an AI agent. It runs for its run window (2 hours by default when created from an account; see free_minutes in list_products and run_until in the result), then is stopped, and deleted with its files unless turned into a VPS with keep_sandbox. No public IP: SSH through the YorkHost gateway, web apps on the HTTPS preview URL. kind: linux (SSH, coding agents preinstalled), desktop (Linux desktop in the browser via noVNC, for computer use) or windows (Windows desktop). Requires the SSH public key the agent will connect with; SSH keys registered with add_sandbox_key are authorized too. Account secrets (set_sandbox_secret) are exported as environment variables in Linux sandboxes unless inject_secrets is false.

• Permission : sandbox:write
• Route équivalente : POST /client/v1/sandboxes

Arguments :

Argument	Type	Description
inject_secrets	boolean	Export the account's sandbox secrets (API keys, tokens) in this sandbox. Default true; set false for untrusted code.
kind	string
ssh_public_key (requis)	string	One OpenSSH public key line (ssh-ed25519 …)

sandbox_links

New desktop link for a sandbox (the previous link stops working).

• Permission : sandbox:write
• Route équivalente : POST /client/v1/sandboxes/:id/links

Arguments :

Argument	Type	Description
sandbox_id (requis)	string	Sandbox ID (sbx…, from list_sandboxes)

keep_sandbox

Turn a trial sandbox into a regular YorkHost VPS (order + invoice; public IP; its /home/agent folder is copied into the new VPS once paid). Two steps like create_order: preflight without confirmation_token, user approval, then confirm.

• Permission : orders:write
• Route équivalente : POST /client/v1/sandboxes/:id/keep

Arguments :

Argument	Type	Description
confirmation_token	string
sandbox_id (requis)	string	Sandbox ID (sbx…, from list_sandboxes)

claim_sandbox

Attach an anonymous trial sandbox created with ssh yorkhost.sh to this account and turn it into a regular YorkHost VPS (order + invoice; its /home/agent folder is copied into the VPS once paid). Takes the claim link or token printed at creation. Only claim a sandbox the user created: its files come from its creator (SSH keys found in it are not copied; the account's registered SSH keys are installed for the agent user on the VPS). Two steps: preflight without confirmation_token, user approval, then confirm.

• Permission : orders:write
• Route équivalente : POST /client/v1/sandboxes/claim

Arguments :

Argument	Type	Description
claim_token (requis)	string	yhsc_… token or the full claim link
confirmation_token	string

delete_sandbox

Delete a trial sandbox and all its files. Irreversible: confirm with the user first.

• Permission : sandbox:write
• Route équivalente : DELETE /client/v1/sandboxes/:id

Arguments :

Argument	Type	Description
sandbox_id (requis)	string	Sandbox ID (sbx…, from list_sandboxes)

sandbox_exec

Run a shell command inside one of the account's running sandboxes (kinds linux and desktop, not windows), without SSH. The command runs as bash -lc <command> as the Linux user agent in the trial VM (home /home/agent, passwordless sudo for root tasks such as apt-get), in /home/agent or cwd. Returns exit_code, stdout and stderr (each truncated beyond 256 KiB, see stdout_truncated/stderr_truncated), timed_out and duration_ms. timeout_seconds defaults to 60 (max 300): the command and its children are killed at the timeout. For servers and long jobs, start them in the background with their output redirected (e.g. nohup npm run dev > /tmp/dev.log 2>&1 &), then poll the log. The sandbox has no public IP: to test a web app, listen on 0.0.0.0:8080 and open the sandbox's preview_url from list_sandboxes (https://<sandbox_id>-8080.yorkhost.sh; for another port, change 8080 in the hostname), or curl localhost:<port> here.Outbound traffic is limited to web, git, SSH and DNS. At most 4 commands run at once per sandbox.

• Permission : sandbox:write
• Route équivalente : POST /client/v1/sandboxes/:id/exec

Arguments :

Argument	Type	Description
command (requis)	string	Shell command (bash syntax, pipes and && allowed), at most 32 KiB
cwd	string	Working directory under /home/agent (default /home/agent)
sandbox_id (requis)	string	Sandbox ID (sbx…, from list_sandboxes)
stdin	string	Optional text sent to the command's standard input (at most 32 KiB)
timeout_seconds	integer	Default 60

sandbox_list_files

List a directory inside a running sandbox (kinds linux and desktop), read as the Linux user agent: name (relative to path), type (file, dir, symlink, other), size, mode and mtime. path must be under /home/agent or /tmp (relative paths start from /home/agent; default /home/agent). depth 1 to 3 lists subdirectories recursively (default 1). At most 1000 entries (truncated flag); symlinks are not followed.

• Permission : sandbox:read
• Route équivalente : GET /client/v1/sandboxes/:id/files

Arguments :

Argument	Type	Description
depth	integer	Recursion depth (default 1)
path	string	Directory under /home/agent or /tmp (default /home/agent)
sandbox_id (requis)	string	Sandbox ID (sbx…, from list_sandboxes)

sandbox_read_file

Read a file inside a running sandbox (kinds linux and desktop), as the Linux user agent (its permissions apply). path must be under /home/agent or /tmp (relative paths start from /home/agent). Returns the first 1 MiB: encoding utf-8 (content is the text) or base64 for binary files, plus size and truncated.

• Permission : sandbox:read
• Route équivalente : GET /client/v1/sandboxes/:id/files/content

Arguments :

Argument	Type	Description
path (requis)	string	File under /home/agent or /tmp
sandbox_id (requis)	string	Sandbox ID (sbx…, from list_sandboxes)

sandbox_write_file

Create or overwrite a file inside a running sandbox (kinds linux and desktop), as the Linux user agent; missing parent directories are created and the file is replaced atomically. path must be under /home/agent or /tmp (relative paths start from /home/agent). content is text (encoding utf-8, default) or base64 (encoding base64) for binary data, at most 1 MiB. mode is an optional octal permission such as 755 (default: kept when overwriting an existing file).

• Permission : sandbox:write
• Route équivalente : PUT /client/v1/sandboxes/:id/files/content

Arguments :

Argument	Type	Description
content (requis)	string	File content (text, or base64 with encoding=base64)
encoding	string	Default utf-8
mode	string	Octal permission, e.g. 644 or 755
path (requis)	string	File under /home/agent or /tmp
sandbox_id (requis)	string	Sandbox ID (sbx…, from list_sandboxes)

list_sandbox_keys

SSH public keys registered on the account for agent sandboxes (fingerprint, name). Each of them can connect to every sandbox of the account (ssh <sandbox id>@yorkhost.sh) and is added to sandboxes created later.

• Permission : sandbox:read
• Route équivalente : GET /client/v1/sandbox-keys
• Arguments : aucun

add_sandbox_key

Register an SSH PUBLIC key on the account (max 10): it can then connect to all the account's sandboxes, current and future. Never send a private key.

• Permission : sandbox:write
• Route équivalente : POST /client/v1/sandbox-keys

Arguments :

Argument	Type	Description
name	string	Label (default: the key comment)
public_key (requis)	string	One OpenSSH public key line (ssh-ed25519 …, ecdsa-sha2-… or ssh-rsa ≥ 2048 bits)

remove_sandbox_key

Remove an SSH key from the account: it can no longer connect to the account's sandboxes through the gateway.

• Permission : sandbox:write
• Route équivalente : DELETE /client/v1/sandbox-keys

Arguments :

Argument	Type	Description
fingerprint (requis)	string	SHA256:… fingerprint from list_sandbox_keys

list_sandbox_secrets

Names of the account's sandbox secrets (environment variables such as ANTHROPIC_API_KEY, OPENAI_API_KEY, GITHUB_TOKEN exported in new Linux sandboxes). Values are never returned.

• Permission : sandbox:read
• Route équivalente : GET /client/v1/sandbox-secrets
• Arguments : aucun

set_sandbox_secret

Create or replace an account secret exported as an environment variable in the account's new Linux sandboxes (max 20, value up to 4 KiB). Stored encrypted and never shown again: only use a value the user explicitly gave for this purpose, and do not repeat it back.

• Permission : sandbox:write
• Route équivalente : PUT /client/v1/sandbox-secrets/:name

Arguments :

Argument	Type	Description
name (requis)	string	Variable name, e.g. ANTHROPIC_API_KEY
value (requis)	string	Secret value (up to 4096 bytes)

delete_sandbox_secret

Delete an account secret (sandboxes created later no longer get it; existing ones keep their environment until deleted).

• Permission : sandbox:write
• Route équivalente : DELETE /client/v1/sandbox-secrets/:name

Arguments :

Argument	Type	Description
name (requis)	string	Variable name from list_sandbox_secrets