urlDNA MCP Server

Claude Prompt

The urlDNA MCP Server enables native tool use for security-focused LLM agents like OpenAI GPT, Google Gemini and Claude Desktop, providing a direct interface to interact with the urlDNA threat intelligence platform via API.

The repository exposes the same toolset over two transports:

stdio for local desktop integrations such as Claude Desktop.
streamable-http for hosted deployments such as Cloud Run.

Installation & Setup

This project uses uv for fast Python package management.

Prerequisites

Install uv if you haven't already:

bash

# 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

Quick Start

Clone and setup the project:

bash

git clone <repository-url>

cd urlDNA-mcp-server

uv sync

Run the MCP server locally (stdio mode):

bash

uv run python urldna_mcp/run.py

Run the MCP server in streamable HTTP mode:

bash

uv run python urldna_mcp/server.py

The hosted server reads these environment variables:

PORT: HTTP port to bind to. Defaults to 8080.
MCP_PATH: Public MCP endpoint path. Defaults to /.

Development

bash

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

Hosted MCP Server

The urlDNA MCP server is already hosted and available at:

Code

https://mcp.urldna.io/

This server is accessible over streamable HTTP, which makes it suitable for Cloud Run and other request-driven platforms.

You can use it directly with any platform or LLM that supports the MCP specification (e.g., Claude Desktop, OpenAI GPT, Google Gemini).

Supported Tools

Scanning

Tool	Description
`fast_check`	Instantly check if a URL has been scanned. Returns SAFE / MALICIOUS / UNRATED.
`new_scan`	Submit a URL for a full scan and wait for the result (~30–60s).
`get_scan`	Retrieve a complete scan result by ID.

Search

Tool	Description
`search`	Search scans using CQL (Custom Query Language) across domain, IP, technology, malicious flag, and more. Supports `AND` and `OR` expressions plus pagination (page 2+ requires PREMIUM).

Saved Queries

Tool	Description
`list_queries`	List all saved queries for the authenticated user.
`get_query`	Retrieve a specific saved query and its filters by ID.
`create_query`	Create a new saved query with one or more CQL filter conditions.
`update_query`	Update an existing query's name and filters (full replacement).
`delete_query`	Permanently delete a saved query by ID.
`query_scans`	Retrieve all matching scans for a saved query.

Brand Monitoring

Tool	Description
`list_brands`	List available brands with optional name search and visibility filter (ALL / FREE / PREMIUM / USER_BRANDS).
`get_brand`	Retrieve full details of a specific brand by ID.
`brand_scans`	Get all scans associated with a brand. Supports additional CQL filtering.

API Reference

Tool	Description
`search_docs`	Fetch the full urlDNA OpenAPI and documentations.

Integration with Claude Desktop

To integrate the urlDNA MCP server in Claude Desktop, update your claude_desktop_config.json:

config.json

{

  "mcpServers": {

    "urlDNA": {

      "command": "uv",

      "args": [

        "--directory",

        "<YOUR_PATH>\\urldna_mcp",

        "run",

        "urldna_mcp\\run.py"

      ],

      "env": {

        "x-api-key": "<urlDNA_API_KEY>"

      }

    }

  }

}

Replace <YOUR_PATH> with the parent directory that contains this repository and <urlDNA_API_KEY> with your API key from https://urldna.io.

For hosted MCP clients, point them at https://mcp.urldna.io/ or your own deployed MCP_PATH.

Once configured, you can prompt Claude with natural language, for example:

"Search in urlDNA for malicious scans with title like paypal"

"Create a saved query for mobile scans from Italy that are flagged as malicious"

"Show me all scans associated with the Google brand"

Claude will automatically call the correct tool and return results from the urlDNA platform.

Using the MCP Server with OpenAI GPT

server.ts

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)

Using the MCP Server with Google Gemini

Gemini connects to the urlDNA MCP server via fastmcp, and tools are auto-discovered rather than passed as an allowed_tools list.

server.ts

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

Container Deployment

Build and run with Docker:

bash

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

The search and brand_scans tools forward the provided CQL directly to the urlDNA API. You can combine conditions with either AND or OR.

Examples:

text

malicious = true AND technology LIKE wordpress

domain = google.com OR domain = youtube.com

(domain = paypal.com OR title LIKE paypal) AND country_code = IT

Contributing

Fork the repository
Create a feature branch: git checkout -b feature-name
Install development dependencies: uv sync --dev
Make your changes and ensure tests pass
Format code: uv run black .
Submit a pull request

Contact & Support

For support or API access, visit https://urldna.io or email urldna@urldna.io.