urldna/mcp

Blog
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:
Quick Start
1. **Clone and setup the project:**
2. **Run the MCP server locally (stdio mode):**
3. **Run the MCP server in streamable HTTP mode:**
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
---
Hosted MCP Server
The urlDNA MCP server is already **hosted and available** at:
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 |
|----------------|--------------------------------------------------------------------------|