mcp

The urlDNA MCP Server exposes a suite of native tools that integrate with large language model agents via the MCP protocol. It provides server-side capabilities for URL threat intelligence, including quick safety checks, full scans, saved queries, brand monitoring, and API reference access. The server is accessed over Server-Sent Events (SSE) and is designed to be consumed by LLM platforms (e.g., Claude Desktop, GPT-4.1) that support MCP tool orchestration. To start using it, run the server locally or connect to the hosted SSE endpoint at mcp.urldna.io/sse and authenticate with your urlDNA API key when required.

Tools available fall into several categories:

• Scanning: fast_check, new_scan, get_scan for quick safety checks and full scans with results over time.
• Search: search to query scans using a Custom Query Language (CQL) with pagination support on premium tiers.
• Saved Queries: list_queries, get_query, create_query, update_query, delete_query, query_scans to manage and reuse saved scans.
• Brand Monitoring: list_brands, get_brand, brand_scans for brand-related insights (premium).
• API Reference: search_docs to fetch the OpenAPI documentation for urlDNA.

When used via Claude Desktop or GPT-4.1, you configure the MCP server by providing the server URL, the appropriate tool set, and your API key. Claude can then route natural-language requests such as searching for scans, creating a saved query, or retrieving brand scans directly to the urlDNA MCP server and return structured results to the user.

Prerequisites:\n- Python installed (3.8+).\n- uv (astral uv) installed.\n\nInstall uv (one of the following methods):\nbash\n# On macOS and Linux (recommended)\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# Or install via pip (if you prefer)\npip install uv\n\n\nSteps to install and run:\n1) Clone the repository (or obtain the project files).\nbash\ngit clone <repository-url>\ncd urldna-mcp-server\n\n2) Install development dependencies (optional):\nbash\nuv sync --dev\n\n3) Start the MCP server using uv (stdio/SSE) as described in the README. For local development in SSE mode, you can run:\nbash\nuv run python urldna_mcp/server.py\n\n4) If you prefer the run via the run entry point used in Claude integration, start with:\nbash\nuv run python urldna_mcp/run.py\n\n5) Ensure you have configured your API key in the environment or in the MCP config (see mcp_config). Then connect your MCP-enabled client (Claude Desktop, GPT-4.1) to the provided SSE endpoint.\n```

Tips and common considerations:\n- The hosted URL for the MCP server is https://mcp.urldna.io/sse; use this endpoint in clients that support SSE-based MCP interactions.\n- You will typically need an API key from urlDNA; pass it as x-api-key in the MCP tool configuration or as an environment variable.\n- The server supports multiple tools and categories (Scanning, Search, Saved Queries, Brand Monitoring, API Reference). Some features (e.g., premium tools like list_queries, brand_scans) may require a premium account.\n- If you encounter authentication or endpoint errors, verify that the API key is correctly provided to the MCP client and that the server is reachable.\n- For Claude Desktop integration, you can specify the uv-based command and the working directory to point to your local urldna_mcp directory; ensure the path matches your environment.\n- When running locally, you can switch between stdio mode (run.py) and SSE mode (server.py) depending on the intended integration mode.