Skip to content
aivikings.ai
Dashboard

AiVikings MCP tools reference

AiVikings exposes 31 MCP tools for domain registration, domain management, pricing, transfers, managed DNS, contacts, account identity, and prepaid balance checks. These tools let an AI agent work with domains as callable actions instead of asking a human to click through a registrar dashboard.

This reference is the detailed companion to the compact tools list in the AiVikings docs. Use it when you want to understand what each tool does, what parameters it accepts, what it returns, and when an agent should call it.

The AiVikings MCP endpoint is:

https://mcp.aivikings.ai/mcp

MCP-compatible clients can discover the tools with tools/list. Calling protected tools requires OAuth authorization for the connected AiVikings account.

Read Reads data without changing it.

Write Changes account, contact, domain, DNS, or configuration data.

Spend or destructive Can spend account credit, start a paid lifecycle action, or delete a DNS record.

For production agents, a practical permission model is to allow low-risk read tools and require confirmation for registration, renewal, transfer, DNS deletion, and other write actions.

Who you are, your balance, and account plumbing.

Read Return the account tied to the current token.

When to use Confirm the connection is authenticated and see which customer the agent is acting as.

Parameters

No input parameters.

Returns The authenticated flag plus the customer id, name, and email. api_key_id is null on an OAuth/bearer session.

Example

You ask: Which AiVikings account am I connected as? The agent: The agent calls get_current_user and replies with the name and email on the account, confirming the connection is live.

Behind the scenes

{
"tool": "get_current_user",
"arguments": {}
}

Read Fetch the customer record for the current token.

When to use Read the stored profile for the account the token belongs to. A supplied customer id must match the token.

Parameters

Parameter Required Type Notes
customer_id Optional string or integer Optional. Must match the token’s own customer if provided.

Returns The customer record linked to the bearer token.

Example

You ask: Show me my AiVikings account details. The agent: The agent reads the customer record and summarises your profile, such as your email and preferred currency.

Behind the scenes

{
"tool": "get_customer",
"arguments": {
"customer_id": "cus_XXXXXXXXXXXX"
}
}

Write Create a new customer, without issuing an API key.

When to use Provision a downstream customer record. Does not return credentials.

Parameters

Parameter Required Type Notes
email Required string Customer email.
company_name Optional string Optional company name.
display_name Optional string Optional display name.
preferred_currency Optional string Defaults to USD.
referral_code Optional string Optional referral code.
referred_by Optional string Optional referrer.

Returns The created customer record.

Example

You ask: Set up a new AiVikings customer for hello@customer.icu. The agent: The agent creates the customer and confirms the new account, noting that no login credentials are issued by this step.

Behind the scenes

{
"tool": "create_customer",
"arguments": {
"email": "hello@customer.icu",
"preferred_currency": "USD"
}
}

Read Return prepaid wallet balances for domain purchases.

When to use Check funds before registering or renewing. Shows USD and EUR wallets.

Parameters

Parameter Required Type Notes
currency Optional string Requested currency. Defaults to USD.

Returns Balance in the requested currency plus a per-wallet breakdown. When automatic conversion is on, a zero balance in one currency does not block a purchase if the other wallet has enough credit.

Example

You ask: How much credit do I have left for registering domains? The agent: The agent checks your balance and tells you the available amount on the account.

Behind the scenes

{
"tool": "get_prepaid_balance",
"arguments": {
"currency": "USD"
}
}

Write Link or create the registrar client account for this customer.

When to use One-time plumbing to prevent duplicate registrar client records. Rarely needed by hand.

Parameters

Parameter Required Type Notes
customer_id Optional string or integer Optional. Must match the token if provided.

Returns The linked or newly created provider client reference.

Example

You ask: My account seems out of sync with the registrar, can you fix the link? The agent: The agent links or recreates your registrar client record and confirms the account is connected, avoiding duplicates.

Behind the scenes

{
"tool": "reconcile_provider_client",
"arguments": {}
}

Check names and see prices before you buy.

Read Check availability and price for one domain.

When to use Look up a single exact name and get its price in one call.

Parameters

Parameter Required Type Notes
domain Required string The domain to check, e.g. exampledomain.icu.
currency Optional string Defaults to USD.

Returns A one-item domains array with availability, long_domain flag, domain_type, prices, premium flag, environment, and the provider code and description.

Example

You ask: Is myproject.icu available? The agent: The agent checks the one name and tells you whether it is free and what it would cost to register, renew, and transfer.

Behind the scenes

{
"tool": "check_single_domain_availability",
"arguments": {
"domain": "exampledomain.icu",
"currency": "USD"
}
}

Read Check availability for up to 200 domains at once.

When to use Batch-check a list of candidate names. is_premium flags premium pricing; domain_type only reflects name length.

Parameters

Parameter Required Type Notes
domains Required string[] Up to 200 domains to check.
currency Optional string Defaults to USD.

Returns A domains array, one entry per input name, in the same shape as the single check.

Example

You ask: Check whether myproject.icu, myproject.sbs, and myproject.cfd are free. The agent: The agent batch-checks all three and lists which are available with their prices, and which are taken.

Behind the scenes

{
"tool": "check_domain_availability",
"arguments": {
"domains": [
"myproject.icu",
"myproject.sbs",
"myproject.cfd"
],
"currency": "USD"
}
}

Read Get a full price schedule for one domain.

When to use Show registration, renewal, and transfer prices, and the per-year registration schedule, before committing.

Parameters

Parameter Required Type Notes
domain Required string The domain to price.
currency Optional string Omit to use the returned currency. USD and EUR can be requested.

Returns Customer-facing registration, renewal, and transfer prices, a registration_prices array by year, min and max registration years, and is_premium. Never exposes upstream cost prices.

Example

You ask: How much would it cost to register exampledomain.icu for three years? The agent: The agent pulls the price schedule and gives you the one, two, and three year registration prices plus renewal and transfer costs.

Behind the scenes

{
"tool": "get_domain_pricing",
"arguments": {
"domain": "exampledomain.icu"
}
}

Register, renew, inspect, and list domains.

Spend or destructive Register a domain for a number of years. Spends credit.

When to use Buy a name once you have confirmed availability and a registration-ready contact. Uses account default nameservers when none are given.

Parameters

Parameter Required Type Notes
domain Required string The domain to register.
period_years Required integer Registration length in years.
contact_handle Optional string A complete reusable contact for all roles. Call list_domain_registration_contacts first.
nameservers Optional string[] Optional. Defaults to the account’s configured nameservers.
currency Optional string USD or EUR. Match the currency used for the price quote.
allow_premium Optional boolean Set true only after the user accepts a premium price shown via get_domain_pricing.

Returns The created domain record, including status and expiry once provisioned.

Example

You ask: Register myproject.icu for one year for me. The agent: The agent confirms availability and your default contact, then registers the domain and reports it as registered with an expiry date. Because this spends credit, a well-configured agent will confirm before buying.

Behind the scenes

{
"tool": "register_domain",
"arguments": {
"domain": "myproject.icu",
"period_years": 1,
"contact_handle": "contact-2"
}
}

Spend or destructive Renew a domain for a number of years. Spends credit.

When to use Extend a domain you already own before it expires.

Parameters

Parameter Required Type Notes
domain Required string The domain to renew.
period_years Required integer Additional years.

Returns The updated domain record with the new expiry.

Example

You ask: Renew kaffe.icu for another year. The agent: The agent renews the domain and confirms the new expiry date. This spends credit, so the agent typically confirms first.

Behind the scenes

{
"tool": "renew_domain",
"arguments": {
"domain": "myproject.icu",
"period_years": 1
}
}

Read Get registration status and nameservers for one domain.

When to use Inspect a single domain: status, expiry, nameservers, registrant verification, and lock state.

Parameters

Parameter Required Type Notes
domain Required string The domain to inspect.

Returns Status, expiry, nameservers, long_domain, period, contact handle, registrant verification status and date, provider lock flag, and provider code and description.

Example

You ask: What’s the status of kaffe.icu and when does it expire? The agent: The agent reports the domain’s status, expiry, nameservers, and whether the registrant is verified and the domain is locked.

Behind the scenes

{
"tool": "get_domain_status",
"arguments": {
"domain": "kaffe.icu"
}
}

Read List domains in the local registrar datastore.

When to use Enumerate everything on the account with status, nameservers, contact handle, and dates.

Parameters

No input parameters.

Returns A domains array. Each entry has id, domain, status, long_domain, period_years, nameservers, contact_handle, customer_id, expires_at, created_at, and updated_at.

Example

You ask: List all the domains on my account. The agent: The agent returns your domains with their status and expiry dates, so you can see everything you own at a glance.

Behind the scenes

{
"tool": "list_domains",
"arguments": {}
}

Read Compare local domain records with the configured registrar provider records.

When to use Audit for drift between the local datastore and the configured registrar provider.

Parameters

No input parameters.

Returns A reconciliation summary of matches and differences.

Example

You ask: Do my domain records match what the registrar has? The agent: The agent compares local records with configured registrar provider records and tells you whether everything is in sync or flags any differences.

Behind the scenes

{
"tool": "reconcile_domains",
"arguments": {}
}

Move domains in, and control transfer locks.

Spend or destructive Transfer a domain in to AiVikings. Spends credit.

When to use Bring an existing domain from another registrar, using its auth code.

Parameters

Parameter Required Type Notes
domain Required string The domain to transfer in.
auth_code Required string The EPP/auth code from the losing registrar.
period_years Optional integer Defaults to 1.

Returns The transfer request record and its status.

Example

You ask: Transfer example.icu to AiVikings, the auth code is ABC-123. The agent: The agent starts the inbound transfer using your auth code and reports that the transfer is pending. This spends credit.

Behind the scenes

{
"tool": "domain_transfer",
"arguments": {
"domain": "example.icu",
"auth_code": "AUTH-CODE-HERE",
"period_years": 1
}
}

Read Return the EPP transfer auth code for a domain you own.

When to use Retrieve the code needed to transfer a domain out to another registrar. Fetched on demand.

Parameters

Parameter Required Type Notes
domain Required string A domain owned by the authenticated customer.

Returns The current EPP auth code for the domain.

Example

You ask: I want to move kaffe.icu to another registrar, what’s the auth code? The agent: The agent retrieves and gives you the domain’s EPP auth code to hand to the gaining registrar.

Behind the scenes

{
"tool": "get_transfer_auth_code",
"arguments": {
"domain": "kaffe.icu"
}
}

Write Generate a new auth code, invalidating the old one.

When to use Rotate the transfer code, for example if the previous one may be compromised.

Parameters

Parameter Required Type Notes
domain Required string A domain owned by the authenticated customer.

Returns The new EPP auth code. The previous code stops working.

Example

You ask: Reset the transfer code for kaffe.icu, I think the old one leaked. The agent: The agent generates a fresh auth code and gives it to you, and the previous code stops working.

Behind the scenes

{
"tool": "regenerate_transfer_auth_code",
"arguments": {
"domain": "kaffe.icu"
}
}

Write Enable the registrar transfer lock.

When to use Protect a domain from being transferred away.

Parameters

Parameter Required Type Notes
domain Required string A domain owned by the authenticated customer.

Returns Confirmation that the transfer lock is on.

Example

You ask: Lock kaffe.icu so it can’t be transferred away. The agent: The agent enables the transfer lock and confirms the domain is protected.

Behind the scenes

{
"tool": "lock_domain",
"arguments": {
"domain": "kaffe.icu"
}
}

Write Disable the registrar transfer lock.

When to use Prepare a domain for transfer out by removing its lock.

Parameters

Parameter Required Type Notes
domain Required string A domain owned by the authenticated customer.

Returns Confirmation that the transfer lock is off.

Example

You ask: Unlock kaffe.icu, I’m about to transfer it out. The agent: The agent removes the transfer lock and confirms the domain is ready to transfer.

Behind the scenes

{
"tool": "unlock_domain",
"arguments": {
"domain": "kaffe.icu"
}
}

Point the domain and manage its zone records.

Write Replace a domain’s nameservers.

When to use Delegate a domain to a different DNS provider or back to AiVikings.

Parameters

Parameter Required Type Notes
domain Required string The domain to update.
nameservers Required string[] The full replacement nameserver set.

Returns The updated nameserver set for the domain.

Example

You ask: Point kaffe.icu at AiVikings nameservers. The agent: The agent replaces the domain’s nameservers with the ones you name and confirms the new delegation.

Behind the scenes

{
"tool": "update_nameservers",
"arguments": {
"domain": "kaffe.icu",
"nameservers": [
"ns1.aivikings.net",
"ns2.aivikings.net"
]
}
}

Read List the managed DNS records for a domain.

When to use Read the current zone before editing. Use the returned id to update or delete a record.

Parameters

Parameter Required Type Notes
domain Required string A domain owned by the authenticated customer.

Returns A records array. Each record has recordName, recordType, recordContent, recordTTL, recordPriority, and dnszoneRecordID (the id to pass to update or delete). Note the provider spells one field recordWeieght.

Example

You ask: Show me the DNS records for kaffe.icu. The agent: The agent lists the current zone, including record types, values, and TTLs, so you can see what is set before changing anything.

Behind the scenes

{
"tool": "list_dns_records",
"arguments": {
"domain": "kaffe.icu"
}
}

Write Set the A record for a domain or subdomain.

When to use Quick path to point a name at an IP. Use @ or omit record_name for the root; pass a relative name like www or staging.api for a subdomain.

Parameters

Parameter Required Type Notes
domain Required string The domain, or a full hostname the server resolves to its parent.
record_value Required string The IPv4 address for the A record.
record_name Optional string Relative name, or @ for the apex. Defaults to @.

Returns The A record that was set.

Example

You ask: Point kaffe.icu at 87.62.127.19. The agent: The agent sets the root A record to that IP address and confirms the domain now points there.

Behind the scenes

{
"tool": "configure_dns_record",
"arguments": {
"domain": "kaffe.icu",
"record_name": "@",
"record_value": "87.62.127.19"
}
}

Write Add a managed DNS record (A, AAAA, CNAME, MX, TXT, NS, SRV).

When to use Create a new record. Relative names expand under the domain, including nested names; use @ for the apex. SRV needs port and weight.

Parameters

Parameter Required Type Notes
domain Required string The domain to add the record to.
record_name Required string Relative name or @ for the apex.
record_type Required string A, AAAA, CNAME, MX, TXT, NS, or SRV.
record_value Required string The record content.
record_ttl Optional integer Time to live in seconds. Defaults to 43200.
record_priority Optional integer For MX and SRV. Defaults to 0.
record_port Optional integer Required for SRV.
record_weight Optional integer Required for SRV.

Returns The created record, including its dnszoneRecordID.

Example

You ask: Add a mail record for kaffe.icu pointing to mail.kaffe.icu. The agent: The agent adds the MX record with the right priority and confirms it was created.

Behind the scenes

{
"tool": "add_dns_record",
"arguments": {
"domain": "kaffe.icu",
"record_name": "@",
"record_type": "MX",
"record_value": "mail.kaffe.icu",
"record_priority": 10
}
}

Write Replace an existing managed DNS record.

When to use Change a record in place. Call list_dns_records first to get its dnszoneRecordID. All fields describe the desired replacement.

Parameters

Parameter Required Type Notes
dns_zone_record_id Required string The dnszoneRecordID from list_dns_records.
domain Required string The domain the record belongs to.
record_name Required string Relative name or @.
record_type Required string The record type.
record_value Required string The new content.
record_ttl Optional integer Defaults to 43200.
record_priority Optional integer For MX and SRV. Defaults to 0.
record_port Optional integer For SRV.
record_weight Optional integer For SRV.

Returns The updated record.

Example

You ask: Change the A record on kaffe.icu to 203.0.113.10. The agent: The agent looks up the existing record, replaces it with the new IP, and confirms the change.

Behind the scenes

{
"tool": "update_dns_record",
"arguments": {
"dns_zone_record_id": "1113100947",
"domain": "kaffe.icu",
"record_name": "@",
"record_type": "A",
"record_value": "203.0.113.10"
}
}

Spend or destructive Permanently delete a managed DNS record.

When to use Remove a record. Call list_dns_records first and pass the exact dnszoneRecordID. This cannot be undone.

Parameters

Parameter Required Type Notes
dns_zone_record_id Required string The dnszoneRecordID from list_dns_records.
domain Required string The domain the record belongs to.

Returns Confirmation of deletion.

Example

You ask: Remove the MX record from kaffe.icu. The agent: The agent finds the record and deletes it. Because deletion is permanent, a careful agent confirms which record before removing it.

Behind the scenes

{
"tool": "delete_dns_record",
"arguments": {
"dns_zone_record_id": "1113104636",
"domain": "kaffe.icu"
}
}

Manage reusable contacts and registrant roles.

Write Create a reusable contact for registrations.

When to use Make a contact once and reuse its handle across many domains. Handle is generated if omitted.

Parameters

Parameter Required Type Notes
name Required string Contact full name.
email Required string Contact email.
address Required string Street address.
city Required string City.
state Required string State or region.
postal_code Required string Postal code.
country Required string Country.
phone_country_code Required string Phone country code, e.g. 45.
phone_number Required string Phone number.
organization Optional string Optional organization.
address_line_2 Optional string Optional second address line.
handle Optional string Optional. Generated from initials, digits, and country if omitted.
default_registrant Optional boolean Set as default registrant.
default_admin Optional boolean Set as default admin.
default_technical Optional boolean Set as default technical.
default_billing Optional boolean Set as default billing.

Returns The created contact, including its handle for use in register_domain.

Example

You ask: Save my details as a reusable contact for future registrations. The agent: The agent creates a contact from your details and confirms its handle, which can then be reused across domains.

Behind the scenes

{
"tool": "create_contact",
"arguments": {
"name": "Alex Customer",
"email": "hello@customer.icu",
"address": "Agent Street 1",
"city": "Copenhagen",
"state": "Copenhagen",
"postal_code": "1000",
"country": "Denmark",
"phone_country_code": "45",
"phone_number": "12345678"
}
}

Read List reusable contacts for the account.

When to use See existing contacts, their handles, default roles, and how many domains use each.

Parameters

No input parameters.

Returns Contact records with handle, name, email, address fields, the default_* role flags, used_by_domain_count, and timestamps.

Example

You ask: What contacts do I have saved? The agent: The agent lists your reusable contacts, their handles, default roles, and how many domains use each.

Behind the scenes

{
"tool": "list_contacts",
"arguments": {}
}

Read Get one reusable contact by its handle.

When to use Read a single contact’s full details.

Parameters

Parameter Required Type Notes
contact_handle Required string The contact handle.

Returns The full contact record.

Example

You ask: Show me the details for my main contact. The agent: The agent reads that contact by its handle and shows the full record.

Behind the scenes

{
"tool": "get_contact",
"arguments": {
"contact_handle": "contact-2"
}
}

Read List contacts usable for registration, with readiness.

When to use Always call before register_domain. Shows which contacts are complete, what fields are missing, and their default roles.

Parameters

No input parameters.

Returns Registration contact handles, each with a registration-ready flag, any missing required fields, and default role assignments.

Example

You ask: Am I ready to register a domain, contact-wise? The agent: The agent checks your registration contacts and tells you which are complete and ready, or what fields are still missing.

Behind the scenes

{
"tool": "list_domain_registration_contacts",
"arguments": {}
}

Write Assign default registration roles to one contact.

When to use Make a contact the default for registrant, admin, technical, and/or billing. Replaces the prior default for each role set.

Parameters

Parameter Required Type Notes
contact_handle Required string The contact to assign roles to.
assign_registrant Optional boolean Set as default registrant.
assign_admin Optional boolean Set as default admin.
assign_technical Optional boolean Set as default technical.
assign_billing Optional boolean Set as default billing.

Returns The updated default-role assignments.

Example

You ask: Make my main contact the default for all registration roles. The agent: The agent assigns that contact as the default registrant, admin, technical, and billing contact and confirms.

Behind the scenes

{
"tool": "assign_domain_registration_contact_roles",
"arguments": {
"contact_handle": "contact-2",
"assign_registrant": true,
"assign_admin": true
}
}

Write Remove default registration roles from one contact.

When to use Clear a contact’s default roles. Does not delete the contact. Removing a role without assigning it elsewhere can make registration validation fail unless register_domain is given an explicit contact.

Parameters

Parameter Required Type Notes
contact_handle Required string The contact to remove roles from.
remove_registrant Optional boolean Remove default registrant.
remove_admin Optional boolean Remove default admin.
remove_technical Optional boolean Remove default technical.
remove_billing Optional boolean Remove default billing.

Returns The updated default-role assignments.

Example

You ask: Stop using that contact as my default billing contact. The agent: The agent removes the billing role from that contact and confirms, leaving the contact itself intact.

Behind the scenes

{
"tool": "remove_domain_registration_contact_roles",
"arguments": {
"contact_handle": "contact-2",
"remove_billing": true
}
}

Write Update the registrant contact for a domain.

When to use Change a domain’s registrant. Name, organization, or email changes require acknowledge_transfer_lock=true and can impose a 60-day transfer lock while verification completes.

Parameters

Parameter Required Type Notes
domain Required string The domain to update.
contact_handle Optional string Apply an existing reusable contact by handle.
name Optional string New name. Triggers verification.
organization Optional string New organization. Triggers verification.
email Optional string New email. Triggers verification.
address Optional string New street address.
city Optional string New city.
state Optional string New state or region.
postal_code Optional string New postal code.
country Optional string New country.
phone_country_code Optional string New phone country code.
phone_number Optional string New phone number.
acknowledge_transfer_lock Optional boolean Required for name, org, or email changes. Acknowledges the possible 60-day lock.

Returns The updated registrant details. A provider-accepted change is reported as verification pending until the registrant completes verification.

Example

You ask: Change the registrant on kaffe.icu to my saved business contact. The agent: The agent applies the contact to the domain. If the name, organisation, or email changes, it warns that verification is required and a 60-day transfer lock may apply.

Behind the scenes

{
"tool": "update_registrant_contact",
"arguments": {
"domain": "kaffe.icu",
"contact_handle": "contact-2"
}
}
  1. Call get_current_user to confirm the connected account.
  2. Call get_prepaid_balance before any action that spends credit.
  3. Call check_single_domain_availability or check_domain_availability to find available names.
  4. Call get_domain_pricing before asking the user to approve a registration, renewal, or transfer.
  5. Call list_domain_registration_contacts before register_domain.
  6. Call register_domain, renew_domain, or domain_transfer only after the user has approved the spend.
  7. Call get_domain_status, update_nameservers, or DNS record tools to complete routing and verification.