The urlDNA MCP Server enables LLM agents (e.g., Claude Desktop, OpenAI GPT-4.1) to interact with the urlDNA threat intelligence platform for cybersecurity analysis.
URL Scanning
fast_check— Instantly check if a URL has been scanned, returning a verdict: SAFE, MALICIOUS, or UNRATEDnew_scan— Submit a URL for a full security scan (~30–60s) and retrieve detailed resultsget_scan— Fetch a previously completed scan by its unique scan ID
Threat Intelligence Search
search— Query scans using a Custom Query Language (CQL) across fields like domain, IP, title, technology, malicious flag, country, device type, and more (supports=,!=,LIKE,>,<, etc.)
Saved Queries Management (Premium)
list_queries,get_query,create_query,update_query,delete_query— Full CRUD management of saved CQL queriesquery_scans— Retrieve scans matching a saved query
Brand Monitoring (Premium)
list_brands— List available brands with filtering optionsget_brand— Get detailed info on a specific brandbrand_scans— Retrieve all scans associated with a brand, with optional CQL filtering
API Documentation
get_api_docs— Fetch the full urlDNA OpenAPI specification for integration guidance
Allows GPT-4.1 to interact with the urlDNA threat intelligence platform, providing tools for URL scanning, retrieving scan results, searching for malicious content, and performing fast phishing checks
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@urlDNA MCP Serverfast check this suspicious link: http://fake-paypal-login.com"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
urlDNA MCP Server
The urlDNA MCP Server enables native tool use for security-focused LLM agents like OpenAI GPT-4.1 and Claude Desktop, providing a direct interface to interact with the urlDNA threat intelligence platform via API.
Installation & Setup
This project uses uv for fast Python package management.
Prerequisites
Install uv if you haven't already:
# On macOS and Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# On Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
# Or with pip
pip install uvQuick Start
Clone and setup the project:
git clone <repository-url>
cd urlDNA-mcp-server
uv syncRun the MCP server locally (stdio mode):
uv run python urldna_mcp/run.pyRun the MCP server in SSE mode:
uv run python urldna_mcp/server.pyDevelopment
# Install development dependencies
uv sync --dev
# Run tests (when available)
uv run pytest
# Format code
uv run black .
# Type checking
uv run mypy .
# Lint code
uv run flake8 .Related MCP server: GPT Researcher MCP Server
Hosted MCP Server
The urlDNA MCP server is already hosted and available at:
https://mcp.urldna.io/sseThis server is accessible over Server-Sent Events (SSE) protocol, which supports streaming interactions between LLMs and the backend tools.
You can use it directly with any platform or LLM that supports the MCP specification (e.g., Claude Desktop, OpenAI GPT-4.1).
Supported Tools
Scanning
Tool | Description |
| Instantly check if a URL has been scanned. Returns SAFE / MALICIOUS / UNRATED. |
| Submit a URL for a full scan and wait for the result (~30–60s). |
| Retrieve a complete scan result by ID. |
Search
Tool | Description |
| Search scans using CQL (Custom Query Language) across domain, IP, technology, malicious flag, and more. Supports pagination (page 2+ requires PREMIUM). |
Saved Queries
Tool | Description |
| List all saved queries for the authenticated user. |
| Retrieve a specific saved query and its filters by ID. |
| Create a new saved query with one or more CQL filter conditions. |
| Update an existing query's name and filters (full replacement). |
| Permanently delete a saved query by ID. |
| Retrieve all matching scans for a saved query. |
Brand Monitoring
Tool | Description |
| List available brands with optional name search and visibility filter (ALL / FREE / PREMIUM / USER_BRANDS). |
| Retrieve full details of a specific brand by ID. |
| Get all scans associated with a brand. Supports additional CQL filtering. |
API Reference
Tool | Description |
| Fetch the full urlDNA OpenAPI and documentations. |
Integration with Claude Desktop
To integrate the urlDNA MCP server in Claude Desktop, update your claude_desktop_config.json:
{
"mcpServers": {
"urlDNA": {
"command": "uv",
"args": [
"--directory",
"C:\\Users\\pripamonti\\urlDNA\\mcp\\urldna_mcp",
"run",
"run.py"
],
"env": {
"x-api-key": "<urlDNA_API_KEY>"
}
}
}
}Replace
<YOUR_PATH>with the actual path to the project directory and<urlDNA_API_KEY>with your API key from https://urldna.io.
Once configured, you can prompt Claude with natural language, for example:
"Search in urlDNA for malicious scans with title like paypal"
"Create a saved query for mobile scans from Italy that are flagged as malicious"
"Show me all scans associated with the Google brand"
Claude will automatically call the correct tool and return results from the urlDNA platform.
Using the MCP Server with OpenAI GPT-4.1
from openai import OpenAI
# Initialize OpenAI client (assumes OPENAI_API_KEY is set via environment variable)
client = OpenAI()
response = client.responses.create(
model="gpt-4.1", # GPT-4.1 supports native MCP tool use
input=[
{
"role": "system",
"content": [{"type": "input_text", "text": "You are a cybersecurity analyst using urlDNA."}]
},
{
"role": "user",
"content": [{"type": "input_text", "text": "Search in urlDNA for malicious scans with title like paypal"}]
}
],
text={"format": {"type": "text"}},
reasoning={},
tools=[
{
"type": "mcp",
"server_label": "urlDNA",
"server_url": "https://mcp.urldna.io/sse",
"headers": {
"x-api-key": "<URLDNA_API_KEY>" # Replace with your urlDNA API key
},
"allowed_tools": [
# --- Scanning ---
"new_scan", # Submit a URL for a full scan and wait for the result
"get_scan", # Retrieve a scan result by ID
"fast_check", # Lightweight instant safety check (SAFE / MALICIOUS / UNRATED)
# --- Search ---
"search", # Search scans using CQL (Custom Query Language)
# --- Saved Queries (PREMIUM) ---
"list_queries",
"get_query",
"create_query",
"update_query",
"delete_query",
"query_scans",
# --- Brand Monitoring (PREMIUM) ---
"list_brands",
"get_brand",
"brand_scans",
# --- API Reference ---
"search_docs",
],
"require_approval": "never"
}
],
temperature=0.7,
top_p=1,
max_output_tokens=2048,
store=True
)
print(response.output)Container Deployment
Build and run with Docker:
# Build the container
docker build -t urldna-mcp-server .
# Run the server
docker run -p 8080:8080 -e x-api-key=<URLDNA_API_KEY> urldna-mcp-serverContributing
Fork the repository
Create a feature branch:
git checkout -b feature-nameInstall development dependencies:
uv sync --devMake your changes and ensure tests pass
Format code:
uv run black .Submit a pull request
Contact & Support
For support or API access, visit https://urldna.io or email urldna@urldna.io.
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.