urlDNA

Servidor MCP urlDNA

Blog

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

El repositorio expone el mismo conjunto de herramientas a través de dos transportes:

• stdio para integraciones locales de escritorio como Claude Desktop.
• streamable-http para implementaciones alojadas como Cloud Run.

---

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 has hecho:

# 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 HTTP transmisible:

uv run python urldna_mcp/server.py

El servidor alojado lee estas variables de entorno:

• PORT: Puerto HTTP al que vincularse. El valor predeterminado es 8080.
• MCP_PATH: Ruta pública del endpoint MCP. El valor predeterminado es /.

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/

Este servidor es accesible a través de HTTP transmisible, lo que lo hace adecuado para Cloud Run y otras plataformas basadas en solicitudes.

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

---

Herramientas Compatibles

Escaneo

Herramienta	Descripción
fast_check	Verifica al instante si una URL ha sido escaneada. Devuelve SEGURO / MALICIOSO / SIN CLASIFICAR.
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) en dominio, IP, tecnología, indicador malicioso y más. Admite expresiones AND y OR además de paginación (la 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 (TODAS / GRATIS / PREMIUM / MARCAS_DE_USUARIO).
get_brand	Recupera los detalles completos de una marca específica por ID.
brand_scans	Obtiene todos los escaneos asociados con una marca. Admite filtrado CQL adicional.

Referencia de API

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

---

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",
        "urldna_mcp\\run.py"
      ],
      "env": {
        "x-api-key": "<urlDNA_API_KEY>"
      }
    }
  }
}

Reemplaza <YOUR_PATH> con el directorio principal que contiene este repositorio y <urlDNA_API_KEY> con tu clave API de https://urldna.io.

Para clientes MCP alojados, apúntalos a https://mcp.urldna.io/ o a tu propio MCP_PATH implementado.

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

"Busca en urlDNA escaneos maliciosos con título similar a 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á resultados de la plataforma urlDNA.

---

Uso del Servidor MCP con OpenAI GPT

from openai import OpenAI

# Initialize OpenAI client (assumes OPENAI_API_KEY is set via environment variable)
client = OpenAI()

response = client.responses.create(
    model="gpt-3.5-turbo",  # Note: MCP tool use requires a Responses API-compatible model
    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 or login"}]
        }
    ],
    text={"format": {"type": "text"}},
    reasoning={},
    tools=[
        {
            "type": "mcp",
            "server_label": "urlDNA",
            "server_url": "https://mcp.urldna.io/",
            "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, AND/OR supported)

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

---

Uso del Servidor MCP con Google Gemini

Gemini se conecta al servidor urlDNA MCP a través de fastmcp, y las herramientas se descubren automáticamente en lugar de pasarse como una lista de allowed_tools.

import os
import asyncio
from fastmcp import Client
from fastmcp.client.transports import StreamableHttpTransport
from google import genai

async def main():
    # 1. Connect FastMCP client directly to streamable-http
    transport = StreamableHttpTransport(
        "https://mcp.urldna.io/",
        headers={"x-api-key": os.getenv("URLDNA_API_KEY", "YOUR_KEY")},
    )
    client_mcp = Client(transport)

    async with client_mcp:
        ai = genai.Client(vertexai=True, project=os.getenv("GOOGLE_CLOUD_PROJECT", "YOUR_PROJECT_ID"))
        response = await ai.aio.models.generate_content(
            model="gemini-2.5-flash",
            contents="Search in urlDNA for malicious scans with title like paypal",
            # Pass the live MCP session (not just tool declarations) so Gemini
            # can automatically call tools and receive their results.
            config=genai.types.GenerateContentConfig(tools=[client_mcp.session]),
        )

        print(response.text)


if __name__ == "__main__":
    asyncio.run(main())

---

Implementación con Contenedores

Compila 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

# Optional: override the public MCP path if you do not want /
docker run -p 8080:8080 -e MCP_PATH=/custom-path -e x-api-key=<URLDNA_API_KEY> urldna-mcp-server

# Cloud Run example
gcloud run deploy urldna-mcp-server \
  --source . \
  --allow-unauthenticated \
  --set-env-vars MCP_PATH=/

Sintaxis de Búsqueda

Las herramientas search y brand_scans reenvían el CQL proporcionado directamente a la API de urlDNA. Puedes combinar condiciones con AND o OR.

Ejemplos:

malicious = true AND technology LIKE wordpress
domain = google.com OR domain = youtube.com
(domain = paypal.com OR title LIKE paypal) AND country_code = IT

---

Contribuciones

1. Haz un fork del repositorio
2. Crea una rama de características: 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 solicitud de extracción

---

Contacto y Soporte

Para soporte o acceso a la API, visita https://urldna.io o envía un correo a urldna@urldna.io.