urlDNA

Máy chủ MCP urlDNA

Blog

urlDNA MCP Server cho phép sử dụng công cụ gốc cho các tác nhân LLM tập trung vào bảo mật như OpenAI GPT, Google Gemini và Claude Desktop, cung cấp giao diện trực tiếp để tương tác với nền tảng thông tin tình báo mối đe dọa urlDNA thông qua API.

Kho lưu trữ này cung cấp cùng một bộ công cụ qua hai phương thức truyền tải:

• stdio cho các tích hợp máy tính để bàn cục bộ như Claude Desktop.
• streamable-http cho các triển khai lưu trữ như Cloud Run.

---

Cài đặt & Thiết lập

Dự án này sử dụng uv để quản lý gói Python nhanh chóng.

Điều kiện tiên quyết

Cài đặt uv nếu bạn chưa cài đặt:

# 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

Bắt đầu nhanh

1. Nhân bản và thiết lập dự án:

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

2. Chạy máy chủ MCP cục bộ (chế độ stdio):

uv run python urldna_mcp/run.py

3. Chạy máy chủ MCP ở chế độ HTTP có thể truyền phát:

uv run python urldna_mcp/server.py

Máy chủ lưu trữ đọc các biến môi trường sau:

• PORT: Cổng HTTP để liên kết. Mặc định là 8080.
• MCP_PATH: Đường dẫn điểm cuối MCP công khai. Mặc định là /.

Phát triển

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

---

Máy chủ MCP lưu trữ

Máy chủ urlDNA MCP đã được lưu trữ và sẵn sàng tại:

https://mcp.urldna.io/

Máy chủ này có thể truy cập qua HTTP có thể truyền phát, phù hợp cho Cloud Run và các nền tảng hướng yêu cầu khác.

Bạn có thể sử dụng trực tiếp với bất kỳ nền tảng hoặc LLM nào hỗ trợ đặc tả MCP (ví dụ: Claude Desktop, OpenAI GPT, Google Gemini).

---

Công cụ được hỗ trợ

Quét

Công cụ	Mô tả
fast_check	Kiểm tra ngay lập tức xem một URL đã được quét chưa. Trả về SAFE / MALICIOUS / UNRATED.
new_scan	Gửi một URL để quét đầy đủ và chờ kết quả (~30–60 giây).
get_scan	Truy xuất kết quả quét đầy đủ theo ID.

Tìm kiếm

Công cụ	Mô tả
search	Tìm kiếm các lần quét bằng CQL (Ngôn ngữ truy vấn tùy chỉnh) trên tên miền, IP, công nghệ, cờ độc hại, v.v. Hỗ trợ biểu thức AND và OR cùng phân trang (trang 2+ yêu cầu PREMIUM).

Truy vấn đã lưu

Công cụ	Mô tả
list_queries	Liệt kê tất cả các truy vấn đã lưu cho người dùng đã xác thực.
get_query	Truy xuất một truy vấn đã lưu cụ thể và các bộ lọc của nó theo ID.
create_query	Tạo một truy vấn đã lưu mới với một hoặc nhiều điều kiện bộ lọc CQL.
update_query	Cập nhật tên và bộ lọc của một truy vấn hiện có (thay thế toàn bộ).
delete_query	Xóa vĩnh viễn một truy vấn đã lưu theo ID.
query_scans	Truy xuất tất cả các lần quét khớp cho một truy vấn đã lưu.

Giám sát thương hiệu

Công cụ	Mô tả
list_brands	Liệt kê các thương hiệu có sẵn với tìm kiếm tên tùy chọn và bộ lọc hiển thị (ALL / FREE / PREMIUM / USER_BRANDS).
get_brand	Truy xuất chi tiết đầy đủ của một thương hiệu cụ thể theo ID.
brand_scans	Lấy tất cả các lần quét liên quan đến một thương hiệu. Hỗ trợ lọc CQL bổ sung.

Tài liệu tham khảo API

Công cụ	Mô tả
search_docs	Tải xuống OpenAPI đầy đủ của urlDNA và tài liệu.

---

Tích hợp với Claude Desktop

Để tích hợp urlDNA MCP server trong Claude Desktop, cập nhật claude_desktop_config.json của bạn:

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

Thay thế <YOUR_PATH> bằng thư mục cha chứa kho lưu trữ này và <urlDNA_API_KEY> bằng khóa API của bạn từ https://urldna.io.

Đối với các máy khách MCP lưu trữ, hãy trỏ chúng đến https://mcp.urldna.io/ hoặc MCP_PATH đã triển khai của riêng bạn.

Sau khi cấu hình, bạn có thể nhắc Claude bằng ngôn ngữ tự nhiên, ví dụ:

"Tìm kiếm trong urlDNA các lần quét độc hại có tiêu đề chứa paypal"

"Tạo một truy vấn đã lưu cho các lần quét di động từ Ý được gắn cờ là độc hại"

"Hiển thị cho tôi tất cả các lần quét liên quan đến thương hiệu Google"

Claude sẽ tự động gọi công cụ chính xác và trả về kết quả từ nền tảng urlDNA.

---

Sử dụng Máy chủ MCP với 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)

---

Sử dụng Máy chủ MCP với Google Gemini

Gemini kết nối với máy chủ urlDNA MCP qua fastmcp, và các công cụ được tự động phát hiện thay vì được truyền dưới dạng danh sách 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())

---

Triển khai Container

Xây dựng và chạy với 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=/

Cú pháp tìm kiếm

Các công cụ search và brand_scans chuyển tiếp CQL được cung cấp trực tiếp đến API urlDNA. Bạn có thể kết hợp các điều kiện với AND hoặc OR.

Ví dụ:

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

---

Đóng góp

1. Fork kho lưu trữ
2. Tạo nhánh tính năng: git checkout -b feature-name
3. Cài đặt các phụ thuộc phát triển: uv sync --dev
4. Thực hiện các thay đổi của bạn và đảm bảo các bài kiểm tra vượt qua
5. Định dạng mã: uv run black .
6. Gửi yêu cầu kéo

---

Liên hệ & Hỗ trợ

Để được hỗ trợ hoặc truy cập API, hãy truy cập https://urldna.io hoặc gửi email đến urldna@urldna.io.