# NS1 (IBM NS1 Premium DNS API) MCP

> NS1 (IBM NS1 Premium DNS API) MCP Server connects your AI agent directly to global DNS infrastructure. You use this server to list, create, update, and delete entire DNS zones and individual records across multiple domains. It lets you configure advanced traffic steering rules and set up monitoring jobs—all through natural conversation. Stop logging into web dashboards; manage all your network routing from your IDE.

## Overview
- **Category:** developer-tools
- **Price:** Free
- **Tags:** dns-management, traffic-steering, managed-dns, network-automation, ibm-ns1

## Description

Hey, listen up. The NS1 DNS API MCP Server plugs your AI agent straight into global DNS infrastructure. You use this server to manage everything—from setting up a brand-new domain zone right down to changing a single record's TTL. Forget logging into web dashboards; you handle all that complex network routing and configuration straight from your IDE.

**Zone Lifecycle Management**
You can list every DNS zone (domain) you manage in NS1 using `list_zones`. You’ll get the full setup details for any specific domain with `get_zone`, or you can modify general settings, like nameservers or policies, by running `update_zone`. If you need to provision an entirely new domain space, use `create_zone` to set it up. When you're done with a zone, you decommission and delete the whole thing using `delete_zone`.

**DNS Record CRUD Operations**
You control every single record type—A, CNAME, TXT, whatever. To add a brand-new DNS record to an existing zone, just call `create_record`. If you need to modify an existing record's value or tweak its parameters without deleting it first, use `update_record`. You can pull up all the specific details for any targeted record type by running `get_record`, and if a record is trash, you wipe it out permanently with `delete_record`.

**Network Health Monitoring**
It's crucial to know if your endpoints are actually alive. You set up monitoring jobs using `create_monitoring_job` to track endpoint health across global regions. To see what job statuses you've got running or finished, check the list with `list_monitoring_jobs`. If you need to scope out where these checks can run, grab a list of available geographical regions by calling `list_monitoring_regions`.

**Data Source Orchestration and Dynamic DNS**
If your records depend on real-time data, this is how you handle it. You first check what external feeds are connected using `list_data_sources`. To bring a new data source online for dynamic responses, run `create_data_source`. Once that's set up, you push actual information to the feed via `push_data_feed` so your DNS responds with current data. This keeps everything fresh and accurate.

Basically, this server gives you total control over setting up zones, managing records, checking endpoint health across multiple regions, and feeding dynamic responses from external sources—all without touching a web console.

## Tools

### create_data_source
Sets up a new external data feed source for NS1 to use in dynamic DNS responses.

### create_monitoring_job
Schedules a new job that tracks the health of specified endpoints across global regions.

### create_record
Adds a brand-new DNS record (like A, CNAME, or TXT) to an existing zone.

### create_zone
Provisions and sets up an entirely new domain zone within your NS1 account.

### delete_record
Permanently removes a specific DNS record from its respective zone.

### delete_zone
Decommissions and deletes an entire domain zone managed by NS1.

### get_record
Retrieves all specific details for a single, targeted DNS record type.

### get_zone
Fetches the current configuration and settings for an entire zone.

### list_data_sources
Lists all data sources currently connected or defined in your NS1 account.

### list_monitoring_jobs
Retrieves a list of all active and past monitoring jobs you've configured.

### list_monitoring_regions
Lists the geographical regions available for setting up new health checks.

### list_zones
Returns a list of every DNS zone (domain) you currently manage in NS1.

### push_data_feed
Sends a payload of data to an existing, defined data feed source for dynamic responses.

### update_record
Modifies the value or parameters (like TTL) of an existing DNS record without deleting it first.

### update_zone
Changes the general settings, such as nameservers or policies, for a defined zone.

## Prompt Examples

**Prompt:** 
```
List all my DNS zones in NS1.
```

**Response:** 
```
I've retrieved your zones. You currently manage 3 zones: 'production.com', 'staging.net', and 'api-gateway.io'. Which one would you like to manage?
```

**Prompt:** 
```
Create an A record for 'www.production.com' pointing to '1.2.3.4' with a TTL of 3600.
```

**Response:** 
```
I've successfully created the A record for 'www.production.com' in the 'production.com' zone. It is now pointing to 1.2.3.4 with a TTL of 3600 seconds.
```

**Prompt:** 
```
Show me all active monitoring jobs and their regions.
```

**Response:** 
```
Fetching monitoring data... I found 2 active jobs: 'Global-Web-Check' (monitoring from US-East, EU-West, and Asia-Pacific) and 'API-Health' (monitoring from US-West).
```

## Capabilities

### Zone Lifecycle Management
Create, list, get details for, update, or delete entire domains (zones) within your NS1 account.

### DNS Record CRUD
Add new records (`create_record`), retrieve specifics (`get_record`), modify existing records (`update_record`), and delete any DNS record type.

### Network Health Monitoring
Set up monitoring jobs to check endpoint health, list available regions using `list_monitoring_regions`, or retrieve status reports using `list_monitoring_jobs`.

### Data Source Orchestration
Manage external data feeds by listing sources (`list_data_sources`), creating new ones (`create_data_source`), and pushing real-time payloads via `push_data_feed`.

### Zone Configuration Updates
Modify the overall settings of a zone using `update_zone`, or read current configuration details with `get_zone`.

## Use Cases

### Emergency Service Failover
The primary web service went down in the EU region. The SRE doesn't have time to log into the dashboard. They prompt their agent: 'Set all traffic for my-app.com to point to the backup IP address 203.0.113.5 and set a low TTL.' The agent runs `update_record` instantly, redirecting global traffic while the team investigates the root cause.

### New Feature Rollout
A developer needs to test a new API endpoint in staging. Instead of manually creating the record, they ask their agent: 'Create an A record for api-staging.internal pointing to 10.0.0.5.' The agent runs `create_record` and confirms it's ready for testing.

### Audit/Cleanup
A Cloud Architect suspects a zone is abandoned. They use `list_zones`, identify the old domain, run `get_zone` to review settings, and then call `delete_zone`. This ensures proper cleanup without manual dashboard interaction.

### Dependency Tracking
The team needs to build a dynamic DNS response based on inventory data. They first use `list_data_sources` to check what's available, then call `create_data_source`, and finally push the initial records using `push_data_feed`.

## Benefits

- Global Visibility: Instantly check the health of endpoints anywhere in the world. Use `list_monitoring_jobs` to see what's running, then use `create_monitoring_job` to add coverage for a new service endpoint.
- Atomic Updates: You don't need multi-step scripts just to change one IP address. The `update_record` tool lets you modify an existing A or CNAME record directly via prompt, saving five minutes of SSH work every time.
- Dynamic Routing Control: Don't rely on static IPs. By using tools like `create_data_source` and `push_data_feed`, your DNS responses can change based on real-time input (e.g., failover data).
- Full Zone Lifecycle Management: Need to decommission an old service? You can run the full cleanup cycle—from `list_zones` to `delete_record` and finally `delete_zone`—all in conversation, ensuring nothing is left dangling.
- Structured Deployment: Use `create_zone` first. Then, define records using `create_record`. This conversational process enforces a structured way of building out new domains without leaving your IDE.

## How It Works

The bottom line is you talk to your AI client, and it speaks directly to IBM NS1 to make infrastructure changes.

1. Subscribe to this server and provide your NS1 API Key.
2. Your AI client uses the key to authenticate against the NS1 APIs.
3. You prompt your agent with a natural language request (e.g., 'Update the CNAME record for staging.com'). The agent then runs the specific tool call (`update_record`) and returns confirmation of the change.

## Frequently Asked Questions

**How do I list all my domains in NS1 using the MCP Server?**
Run the `list_zones` tool. It immediately returns a comprehensive list of every DNS zone you manage within your account, so you know exactly what you're working with before making any changes.

**What is the difference between `create_record` and `update_record`?**
`create_record` builds a record that doesn't exist yet. Use it when you are launching something new. If the record already exists, use `update_record` to modify its value or parameters (like TTL) without deleting it.

**Can I automate DNS changes as part of my workflow?**
Yes. The server supports this by allowing your AI agent to execute tools like `create_zone` and `create_record` based on a sequence of prompts, which is ideal for CI/CD integration.

**How do I check the health status before making changes?**
You first call `list_monitoring_jobs` to see what's running. If you need new checks, use `create_monitoring_job`, specifying regions via `list_monitoring_regions`.

**What do I need to check if my attempts to run `get_zone` return an access denied error?**
You must verify your NS1 API key. The server requires valid credentials linked to an active account to read zone data. Check the documentation for key generation and scope permissions.

**How does the `push_data_feed` tool handle real-time, dynamic DNS updates?**
The tool accepts external data sources that drive immediate DNS responses. It pushes structured data directly to a specified feed endpoint, bypassing manual record creation for rapid changes.

**Are there specific requirements I need to know before running `create_zone`?**
The API enforces standard domain naming conventions and checks for regional availability. We recommend listing existing zones first using `list_zones` to confirm uniqueness.

**Before executing a potentially destructive command like `delete_record`, how can I verify its current settings?**
Always run `get_record` first. This confirms the exact details—including TTL, record type (A, CNAME), and associated zone—before you issue the delete command.

**Can I create a new DNS zone using this server?**
Yes! Use the `create_zone` tool with the zone name (e.g., 'example.com'). You can also optionally set TTL, refresh, and expiry values during creation.

**How do I add a record with specific answers for traffic steering?**
Use the `create_record` tool. You can provide a JSON array of `answers` (e.g., IP addresses) and a JSON array of `filters` to define how NS1 should steer traffic between those answers.

**Can I see my active monitoring jobs and their status?**
Yes, the `list_monitoring_jobs` tool retrieves all configured monitoring jobs, allowing your AI agent to report on the health and status of your monitored endpoints.