Urldna MCP

What urldna/mcp MCP server does

The urldna/mcp MCP server exposes urlDNA threat intelligence capabilities through the Model Context Protocol. Agents can check whether a URL has already been scanned, submit a URL for a full scan, and retrieve scan results by ID. Full scan investigations can include DOM snapshots, network requests, and visual screenshots for examining redirects and suspicious infrastructure.

The server also supports historical searches across recorded scans with urlDNA’s Custom Query Language (CQL). Search conditions can cover domains, IP addresses, technologies, malicious status, and other scan attributes. CQL expressions support AND and OR operators, with pagination available for search results; pages after the first require PREMIUM access.

How it works

The urldna/mcp MCP server offers the same toolset through two transports. Local desktop clients can launch it over stdio. Hosted deployments can expose it through streamable HTTP, including the published endpoint at https://mcp.urldna.io/.

The server passes requests to the urlDNA platform API and requires a urlDNA API key for authenticated access. Compatible MCP clients can discover or call tools for scanning, search, saved queries, brand monitoring, and API documentation. Claude Desktop can use the local transport or connect to the hosted endpoint.

Setup and configuration

For a local deployment, clone the repository, install its Python dependencies with uv sync, and start stdio mode with:

uv run python urldna_mcp/run.py

Streamable HTTP mode starts with:

uv run python urldna_mcp/server.py

The HTTP process reads PORT, defaulting to 8080, and MCP_PATH, defaulting to /. These settings control the listening port and public MCP endpoint path. Client configuration supplies the urlDNA credential as the x-api-key header. Claude Desktop configuration uses the uv command with the repository directory and urldna_mcp/run.py as arguments.

For a hosted connection, configure the client with https://mcp.urldna.io/ and provide the API key in the request headers. The repository’s examples show this pattern for OpenAI and Gemini clients.

Tools and capabilities

Available tool groups include:

• fast_check for an immediate SAFE, MALICIOUS, or UNRATED result when a URL has been scanned.
• new_scan for submitting a URL and waiting approximately 30–60 seconds for a full result.
• get_scan for retrieving a complete scan by ID.
• search for CQL searches over recorded scans.
• list_queries, get_query, create_query, update_query, delete_query, and query_scans for saved-query management.
• list_brands, get_brand, and brand_scans for brand data and associated scans.
• search_docs for retrieving the urlDNA OpenAPI specification and documentation.

Limitations and notes

Some capabilities are access-controlled. Search pagination beyond the first page requires PREMIUM access, and the README labels saved-query and brand-monitoring tools as PREMIUM. Running the local server also requires the repository, uv, and a urlDNA API key. The hosted endpoint avoids local process management but still requires the urlDNA credential.

The server returns urlDNA platform data; it does not replace analyst review of suspicious pages or infrastructure. Scan completion for new_scan is asynchronous from the user’s perspective and may take approximately 30–60 seconds.