urlDNA

Servidor MCP urlDNA

Blog

El urlDNA MCP Server permite el uso nativo de herramientas para agentes LLM enfocados en seguridad como OpenAI GPT-4.1 y Claude Desktop, proporcionando una interfaz directa para interactuar con la plataforma de inteligencia de amenazas urlDNA a través de API.

---

Instalación y configuración

Este proyecto utiliza uv para una gestión rápida de paquetes Python.

Requisitos previos

Instala uv si aún no lo tienes:

# 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 uv

Inicio rápido

1. Clona y configura el proyecto:

git clone <repository-url>
cd urlDNA-mcp-server
uv sync

2. Ejecuta el servidor MCP localmente (modo stdio):

uv run python urldna_mcp/run.py

3. Ejecuta el servidor MCP en modo SSE:

uv run python urldna_mcp/server.py

Desarrollo

# 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 .

---

Servidor MCP alojado

El servidor urlDNA MCP ya está alojado y disponible en:

https://mcp.urldna.io/sse

Se puede acceder a este servidor a través del protocolo Server-Sent Events (SSE), que admite interacciones de transmisión entre los LLM y las herramientas del backend.

Puedes usarlo directamente con cualquier plataforma o LLM que admita la especificación MCP (por ejemplo, Claude Desktop, OpenAI GPT-4.1).

---

Herramientas compatibles

Escaneo

Herramienta	Descripción
fast_check	Verifica al instante si una URL ha sido escaneada. Devuelve SAFE / MALICIOUS / UNRATED.
new_scan	Envía una URL para un escaneo completo y espera el resultado (~30–60s).
get_scan	Recupera un resultado de escaneo completo por ID.

Búsqueda

Herramienta	Descripción
search	Busca escaneos usando CQL (Lenguaje de Consulta Personalizado) a través de dominio, IP, tecnología, indicador de malicioso y más. Soporta paginación (página 2+ requiere PREMIUM).

Consultas guardadas

Herramienta	Descripción
list_queries	Lista todas las consultas guardadas para el usuario autenticado.
get_query	Recupera una consulta guardada específica y sus filtros por ID.
create_query	Crea una nueva consulta guardada con una o más condiciones de filtro CQL.
update_query	Actualiza el nombre y los filtros de una consulta existente (reemplazo completo).
delete_query	Elimina permanentemente una consulta guardada por ID.
query_scans	Recupera todos los escaneos coincidentes para una consulta guardada.

Monitoreo de marca

Herramienta	Descripción
list_brands	Lista las marcas disponibles con búsqueda opcional por nombre y filtro de visibilidad (ALL / FREE / PREMIUM / USER_BRANDS).
get_brand	Recupera los detalles completos de una marca específica por ID.
brand_scans	Obtiene todos los escaneos asociados con una marca. Soporta filtrado CQL adicional.

Referencia de API

Herramienta	Descripción
search_docs	Obtiene la OpenAPI completa de urlDNA y documentaciones.

---

Integración con Claude Desktop

Para integrar el urlDNA MCP server en Claude Desktop, actualiza tu claude_desktop_config.json:

{
  "mcpServers": {
    "urlDNA": {
      "command": "uv",
      "args": [
        "--directory",
        "<YOUR_PATH>\\urldna_mcp",
        "run",
        "run.py"
      ],
      "env": {
        "x-api-key": "<urlDNA_API_KEY>"
      }
    }
  }
}

Reemplaza <YOUR_PATH> con la ruta real al directorio del proyecto y <urlDNA_API_KEY> con tu clave API de https://urldna.io.

Una vez configurado, puedes pedirle a Claude con lenguaje natural, por ejemplo:

"Busca en urlDNA escaneos maliciosos con título como paypal"

"Crea una consulta guardada para escaneos móviles de Italia que estén marcados como maliciosos"

"Muéstrame todos los escaneos asociados con la marca Google"

Claude llamará automáticamente a la herramienta correcta y devolverá los resultados de la plataforma urlDNA.

---

Uso del servidor MCP con 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)

---

Despliegue en contenedor

Construye y ejecuta con 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-server

---

Contribuciones

1. Haz un fork del repositorio
2. Crea una rama de funcionalidad: git checkout -b feature-name
3. Instala las dependencias de desarrollo: uv sync --dev
4. Realiza tus cambios y asegúrate de que las pruebas pasen
5. Formatea el código: uv run black .
6. Envía una pull request

---

Contacto y soporte

Para soporte o acceso a la API, visita https://urldna.io o envía un correo a [email protected].