urlDNA

Server MCP urlDNA

Blog

urlDNA MCP Server memungkinkan penggunaan alat secara native untuk agen LLM yang berfokus pada keamanan seperti OpenAI GPT, Google Gemini, dan Claude Desktop, menyediakan antarmuka langsung untuk berinteraksi dengan platform intelijen ancaman urlDNA melalui API.

Repositori ini mengekspos rangkaian alat yang sama melalui dua transport:

• stdio untuk integrasi desktop lokal seperti Claude Desktop.
• streamable-http untuk deployment terhosting seperti Cloud Run.

---

Instalasi & Pengaturan

Proyek ini menggunakan uv untuk manajemen paket Python yang cepat.

Prasyarat

Instal uv jika Anda belum melakukannya:

# 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

Memulai dengan Cepat

1. Kloning dan siapkan proyek:

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

2. Jalankan server MCP secara lokal (mode stdio):

uv run python urldna_mcp/run.py

3. Jalankan server MCP dalam mode HTTP streamable:

uv run python urldna_mcp/server.py

Server terhosting membaca variabel lingkungan berikut:

• PORT: Port HTTP yang akan diikat. Defaultnya adalah 8080.
• MCP_PATH: Jalur endpoint MCP publik. Defaultnya adalah /.

Pengembangan

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

---

Server MCP Terhosting

Server urlDNA MCP sudah terhosting dan tersedia di:

https://mcp.urldna.io/

Server ini dapat diakses melalui HTTP streamable, sehingga cocok untuk Cloud Run dan platform berbasis permintaan lainnya.

Anda dapat menggunakannya secara langsung dengan platform atau LLM apa pun yang mendukung spesifikasi MCP (misalnya, Claude Desktop, OpenAI GPT, Google Gemini).

---

Alat yang Didukung

Pemindaian

Alat	Deskripsi
fast_check	Periksa secara instan apakah URL telah dipindai. Mengembalikan SAFE / MALICIOUS / UNRATED.
new_scan	Kirim URL untuk pemindaian penuh dan tunggu hasilnya (~30–60 detik).
get_scan	Ambil hasil pemindaian lengkap berdasarkan ID.

Pencarian

Alat	Deskripsi
search	Cari pemindaian menggunakan CQL (Custom Query Language) di seluruh domain, IP, teknologi, flag berbahaya, dan lainnya. Mendukung ekspresi AND dan OR serta paginasi (halaman 2+ memerlukan PREMIUM).

Kueri Tersimpan

Alat	Deskripsi
list_queries	Daftar semua kueri tersimpan untuk pengguna yang terautentikasi.
get_query	Ambil kueri tersimpan tertentu dan filternya berdasarkan ID.
create_query	Buat kueri tersimpan baru dengan satu atau lebih kondisi filter CQL.
update_query	Perbarui nama dan filter kueri yang ada (penggantian penuh).
delete_query	Hapus permanen kueri tersimpan berdasarkan ID.
query_scans	Ambil semua pemindaian yang cocok untuk kueri tersimpan.

Pemantauan Merek

Alat	Deskripsi
list_brands	Daftar merek yang tersedia dengan pencarian nama opsional dan filter visibilitas (ALL / FREE / PREMIUM / USER_BRANDS).
get_brand	Ambil detail lengkap merek tertentu berdasarkan ID.
brand_scans	Dapatkan semua pemindaian yang terkait dengan merek. Mendukung filter CQL tambahan.

Referensi API

Alat	Deskripsi
search_docs	Ambil OpenAPI urlDNA lengkap dan dokumentasinya.

---

Integrasi dengan Claude Desktop

Untuk mengintegrasikan urlDNA MCP server di Claude Desktop, perbarui claude_desktop_config.json Anda:

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

Ganti <YOUR_PATH> dengan direktori induk yang berisi repositori ini dan <urlDNA_API_KEY> dengan kunci API Anda dari https://urldna.io.

Untuk klien MCP terhosting, arahkan mereka ke https://mcp.urldna.io/ atau MCP_PATH yang Anda deploy sendiri.

Setelah dikonfigurasi, Anda dapat meminta Claude dengan bahasa alami, misalnya:

"Cari di urlDNA untuk pemindaian berbahaya dengan judul seperti paypal"

"Buat kueri tersimpan untuk pemindaian seluler dari Italia yang ditandai sebagai berbahaya"

"Tampilkan semua pemindaian yang terkait dengan merek Google"

Claude akan secara otomatis memanggil alat yang benar dan mengembalikan hasil dari platform urlDNA.

---

Menggunakan Server MCP dengan 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)

---

Menggunakan Server MCP dengan Google Gemini

Gemini terhubung ke server urlDNA MCP melalui fastmcp, dan alat ditemukan secara otomatis daripada diteruskan sebagai daftar 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())

---

Deployment Kontainer

Bangun dan jalankan dengan 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=/

Sintaks Pencarian

Alat search dan brand_scans meneruskan CQL yang diberikan langsung ke API urlDNA. Anda dapat menggabungkan kondisi dengan AND atau OR.

Contoh:

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

---

Kontribusi

1. Fork repositori
2. Buat cabang fitur: git checkout -b feature-name
3. Instal dependensi pengembangan: uv sync --dev
4. Lakukan perubahan Anda dan pastikan tes lulus
5. Format kode: uv run black .
6. Kirim pull request

---

Kontak & Dukungan

Untuk dukungan atau akses API, kunjungi https://urldna.io atau email urldna@urldna.io.