urlDNA

urlDNA MCP 서버

블로그

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

---

설치 및 설정

이 프로젝트는 빠른 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 서버를 SSE 모드로 실행:

uv run python urldna_mcp/server.py

개발

# 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/sse

이 서버는 Server-Sent Events (SSE) 프로토콜을 통해 접근할 수 있으며, LLM과 백엔드 도구 간의 스트리밍 상호 작용을 지원합니다.

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

---

지원 도구

스캔

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

검색

도구	설명
search	도메인, IP, 기술, 악성 플래그 등에서 CQL(사용자 정의 쿼리 언어)을 사용하여 스캔을 검색합니다. 페이지네이션을 지원합니다 (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",
        "run.py"
      ],
      "env": {
        "x-api-key": "<urlDNA_API_KEY>"
      }
    }
  }
}

<YOUR_PATH>을(를) 프로젝트 디렉터리의 실제 경로로, <urlDNA_API_KEY>을(를) https://urldna.io에서 발급받은 API 키로 교체하세요.

구성이 완료되면 자연어로 Claude에 프롬프트를 보낼 수 있습니다. 예를 들면:

"urlDNA에서 제목에 paypal이 포함된 악성 스캔을 검색해 줘"

"이탈리아에서 발생한 악성으로 표시된 모바일 스캔에 대한 저장된 쿼리를 만들어 줘"

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

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

---

OpenAI GPT-4.1과 함께 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-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)

---

컨테이너 배포

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

---

기여하기

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

---

연락처 및 지원

지원 또는 API 액세스에 관해서는 https://urldna.io를 방문하거나 urldna@urldna.io로 이메일을 보내주세요.