urlDNA

urlDNA MCP 서버

블로그

urlDNA MCP Server은(는) OpenAI GPT, Google Gemini, Claude Desktop과 같은 보안 중심 LLM 에이전트를 위한 네이티브 도구 사용을 가능하게 하며, API를 통해 urlDNA 위협 인텔리전스 플랫폼과 직접 상호작용할 수 있는 인터페이스를 제공합니다.

이 저장소는 두 가지 전송 방식으로 동일한 도구 세트를 제공합니다:

• stdio: Claude Desktop과 같은 로컬 데스크톱 통합용.
• streamable-http: Cloud Run과 같은 호스팅 배포용.

---

설치 및 설정

이 프로젝트는 빠른 Python 패키지 관리를 위해 uv를 사용합니다.

사전 요구 사항

아직 설치하지 않았다면 uv를 설치하세요:

# 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

빠른 시작

1. 저장소를 클론하고 프로젝트를 설정합니다:

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

2. MCP 서버를 로컬에서 실행합니다 (stdio 모드):

uv run python urldna_mcp/run.py

3. MCP 서버를 스트리밍 가능한 HTTP 모드로 실행합니다:

uv run python urldna_mcp/server.py

호스팅 서버는 다음 환경 변수를 읽습니다:

• PORT: 바인딩할 HTTP 포트. 기본값은 8080입니다.
• MCP_PATH: 공개 MCP 엔드포인트 경로. 기본값은 /입니다.

개발

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

---

호스팅 MCP 서버

urlDNA MCP 서버는 이미 호스팅되어 사용 가능합니다:

https://mcp.urldna.io/

이 서버는 스트리밍 가능한 HTTP를 통해 접근할 수 있으며, Cloud Run 및 기타 요청 기반 플랫폼에 적합합니다.

MCP 사양을 지원하는 모든 플랫폼이나 LLM(예: Claude Desktop, OpenAI GPT, Google Gemini)에서 직접 사용할 수 있습니다.

---

지원 도구

스캔

도구	설명
fast_check	URL이 스캔되었는지 즉시 확인합니다. SAFE / MALICIOUS / UNRATED를 반환합니다.
new_scan	전체 스캔을 위해 URL을 제출하고 결과를 기다립니다 (~30–60초).
get_scan	ID로 전체 스캔 결과를 검색합니다.

검색

도구	설명
search	도메인, IP, 기술, 악성 플래그 등에 대해 CQL(사용자 정의 쿼리 언어)로 스캔을 검색합니다. AND 및 OR 표현식과 페이지네이션을 지원합니다 (2페이지 이상은 PREMIUM 필요).

저장된 쿼리

도구	설명
list_queries	인증된 사용자의 모든 저장된 쿼리를 나열합니다.
get_query	ID로 특정 저장된 쿼리와 해당 필터를 검색합니다.
create_query	하나 이상의 CQL 필터 조건으로 새 저장된 쿼리를 생성합니다.
update_query	기존 쿼리의 이름과 필터를 업데이트합니다 (전체 교체).
delete_query	ID로 저장된 쿼리를 영구적으로 삭제합니다.
query_scans	저장된 쿼리에 대한 모든 일치 스캔을 검색합니다.

브랜드 모니터링

도구	설명
list_brands	선택적 이름 검색 및 가시성 필터(ALL / FREE / PREMIUM / USER_BRANDS)로 사용 가능한 브랜드를 나열합니다.
get_brand	ID로 특정 브랜드의 전체 세부 정보를 검색합니다.
brand_scans	브랜드와 관련된 모든 스캔을 가져옵니다. 추가 CQL 필터링을 지원합니다.

API 참조

도구	설명
search_docs	전체 urlDNA OpenAPI 및 문서를 가져옵니다.

---

Claude Desktop과의 통합

Claude Desktop에서 urlDNA MCP server을(를) 통합하려면 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>"
      }
    }
  }
}

<YOUR_PATH>을(를) 이 저장소가 포함된 상위 디렉토리로 바꾸고, <urlDNA_API_KEY>을(를) https://urldna.io에서 얻은 API 키로 바꾸세요.

호스팅 MCP 클라이언트의 경우 https://mcp.urldna.io/ 또는 직접 배포한 MCP_PATH을(를) 가리키세요.

구성 후 자연어로 Claude에게 프롬프트할 수 있습니다. 예:

"paypal과 같은 제목의 악성 스캔을 urlDNA에서 검색해줘"

"이탈리아에서 악성으로 플래그된 모바일 스캔에 대한 저장된 쿼리를 생성해줘"

"Google 브랜드와 관련된 모든 스캔을 보여줘"

Claude는 자동으로 올바른 도구를 호출하고 urlDNA 플랫폼에서 결과를 반환합니다.

---

OpenAI GPT와 함께 MCP 서버 사용하기

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)

---

Google Gemini와 함께 MCP 서버 사용하기

Gemini는 fastmcp을(를) 통해 urlDNA MCP 서버에 연결하며, 도구는 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())

---

컨테이너 배포

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=/

검색 구문

search 및 brand_scans 도구는 제공된 CQL을 urlDNA API로 직접 전달합니다. AND 또는 OR으로 조건을 결합할 수 있습니다.

예:

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

---

기여

1. 저장소를 포크합니다
2. 기능 브랜치를 생성합니다: git checkout -b feature-name
3. 개발 종속성을 설치합니다: uv sync --dev
4. 변경 사항을 적용하고 테스트가 통과하는지 확인합니다
5. 코드 형식을 지정합니다: uv run black .
6. 풀 리퀘스트를 제출합니다

---

연락처 및 지원

지원 또는 API 액세스가 필요하면 https://urldna.io을(를) 방문하거나 urldna@urldna.io로 이메일을 보내세요.