Connect Censys to Claude: Track host history and certificate records

If you need to connect Censys to Claude to investigate suspicious infrastructure, analyze global attack surfaces, or audit certificate chains, you need a Model Context Protocol (MCP) server. This server acts as the critical translation layer between Claude's LLM tool calls and the highly structured Censys REST API. You can either build, host, and maintain this infrastructure yourself, or use a managed integration platform like Truto to dynamically generate a secure, authenticated MCP server URL. If your security operations team uses ChatGPT, check out our guide on connecting Censys to ChatGPT or explore our broader architectural overview on connecting Censys to AI Agents.

Giving a Large Language Model (LLM) access to a massive security dataset like Censys introduces significant engineering friction. You have to map deeply nested JSON host objects, handle complex CenQL search syntax, and aggressively manage context windows when retrieving thousands of historical events. Every time Censys updates a search endpoint or deprecates a bulk retrieval method, you have to update your server code, test it, and redeploy.

This guide breaks down exactly how to use Truto to generate a secure, managed MCP server for Censys, connect it natively to Claude Desktop, and execute complex threat hunting workflows using natural language.

The Engineering Reality of the Censys API

A custom MCP server is a self-hosted integration layer. While the open MCP standard provides a predictable way for models like Claude to discover tools, the reality of implementing it against the Censys API requires dealing with domain-specific security data complexities. You are not just building standard CRUD endpoints - you are exposing a global Internet intelligence database to an AI agent.

If you decide to build a custom MCP server for Censys, you own the entire API lifecycle and its quirks. Here are the specific challenges you will face:

Massive Nested Payloads and Context Limits Censys host records are exceptionally verbose. A single GET request for an IP address returns autonomous system data, location, WHOIS records, and a deeply nested array of every service, port, and protocol running on that host, along with specific banner hashes. If an LLM attempts to ingest 50 of these records at once via a raw API call, it will instantly blow out its context window or hallucinate details from adjacent objects. A managed MCP server helps control this by providing specialized tools (like bulk GETs with filtered extensions) and explicitly instructing the model on how to handle pagination.

CenQL Translation and Deprecated Endpoints Censys relies on its proprietary Censys Search Language (CenQL) for querying global assets. Security analysts often have older queries written in the legacy CSL (Censys Search Language) format. Furthermore, Censys has deprecated older GET endpoints for bulk retrieval (like list_all_censys_hosts) in favor of POST endpoints (censys_hosts_bulk_get) to handle massive identifier lists safely. Your MCP server must accurately expose the correct endpoints and handle the translation of older syntax to CenQL, otherwise Claude will fail to return actionable search results.

Strict Time Bounds and Rate Limiting Historical data retrieval in Censys, such as host event history or DNS resolution tracking, requires highly specific RFC3339 timestamps for start and end bounds. LLMs are notoriously bad at formatting these unprompted. Additionally, Censys enforces strict API quotas. Truto handles this reality transparently: we do not retry, throttle, or apply backoff on rate limit errors. When Censys returns an HTTP 429, Truto passes that error directly to the caller, normalizing the upstream rate limit information into standard ratelimit-limit, ratelimit-remaining, and ratelimit-reset headers per the IETF spec. The LLM or the calling framework is entirely responsible for evaluating the reset header and applying the correct backoff strategy.

Step 1: Creating the Managed MCP Server for Censys

Instead of building a local Node.js or Python server to parse CenQL and handle HTTP 429s, you can use Truto to generate a hosted MCP server URL. This URL is cryptographically tied to a specific authenticated Censys account.

Truto dynamically derives the tool definitions directly from the integration's schema documentation. Tools are not hard-coded; they are generated on the fly when Claude connects, ensuring they always match the current state of the Censys API.

You can create this server in two ways.

Method A: Via the Truto UI

If you prefer a visual interface, you can generate the MCP URL directly from your dashboard:

1. Log into your Truto account and navigate to the integrated account page for your connected Censys instance.
2. Click the MCP Servers tab.
3. Click Create MCP Server.
4. Configure your server settings. You can name it (e.g., "Censys Threat Intel"), filter the allowed methods (e.g., "read" only), or set an expiration date if this is for a temporary audit.
5. Click Create and copy the generated MCP server URL (it will look like https://api.truto.one/mcp/a1b2c3d4...).

Method B: Via the API

For platform engineers looking to programmatically provision AI access to Censys, you can create the MCP server via a REST call to the Truto API. This validates that the integration has tools available, generates a secure token, and returns a ready-to-use URL.

curl -X POST https://api.truto.one/integrated-account/{integrated_account_id}/mcp \
  -H "Authorization: Bearer YOUR_TRUTO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Censys Threat Hunting Tools",
    "config": {
      "methods": ["read", "custom"],
      "tags": ["hosts", "certificates", "search"]
    }
  }'

The API returns a JSON payload containing the url.

{
  "id": "mcp_srv_9x8y7z",
  "name": "Censys Threat Hunting Tools",
  "config": { "methods": ["read", "custom"] },
  "expires_at": null,
  "url": "https://api.truto.one/mcp/a1b2c3d4e5f67890"
}

This URL is completely self-contained. It encodes the tenant routing and authentication logic required to communicate with Censys.

Step 2: Connecting the MCP Server to Claude

Once you have the Truto MCP URL, you need to expose it to Claude. You can do this through the Claude user interface or by modifying the desktop configuration file.

Method A: Via the Claude UI

If you are using the Claude desktop app or web interface on an Enterprise or Team plan with custom connector support:

1. Open Claude and navigate to Settings.
2. Select Integrations or Connectors.
3. Click Add MCP Server (or Add custom connector).
4. Name the connector (e.g., "Censys Intel").
5. Paste the Truto MCP URL into the Server URL field.
6. Click Add.

Claude will immediately ping the server via the JSON-RPC 2.0 initialize protocol, fetch the Censys capabilities, and populate its context window with the available tools.

Method B: Via Manual Configuration File

For developers running Claude Desktop locally or managing headless agents, you can configure the MCP server by editing the claude_desktop_config.json file. Because Truto provides a remote SSE (Server-Sent Events) endpoint, you use the @modelcontextprotocol/server-sse npx package to proxy the connection locally.

Open your configuration file (located at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows) and add the following:

{
  "mcpServers": {
    "censys-intel": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sse",
        "https://api.truto.one/mcp/a1b2c3d4e5f67890"
      ]
    }
  }
}

Restart Claude Desktop. The application will execute the proxy command, connect to the Truto edge router, and dynamically load the Censys tools.

Hero Tools for Censys Operations

Truto automatically generates a comprehensive set of tools from the Censys API documentation. To keep Claude focused and highly effective, we recommend restricting your MCP server to these specific, high-leverage "hero" tools for threat hunting and infrastructure analysis.

Get Single Host by IP

get_single_censys_host_by_id

This is the foundational tool for infrastructure investigation. It retrieves a comprehensive breakdown of an IP address, including its physical location, autonomous system, WHOIS data, and an array of all detected services, open ports, and DNS records.

Contextual note: The response from this tool can be massive for hosts with dozens of open ports. Ask the LLM to summarize specific protocols or look for specific banner hashes rather than dumping the raw JSON to the chat.

"Use the Censys tools to look up the host at 8.8.8.8. Tell me what autonomous system it belongs to and list all the unique transport protocols currently exposed on its open ports."

Analyze Host Event History

censys_hosts_event_history

Understanding what a host was doing yesterday is often more important than what it is doing today. This tool retrieves the event history timeline for a specific host ID, allowing you to track when services were exposed or taken offline.

Contextual note: The start_time and end_time parameters must be valid RFC3339 strings. The LLM must be explicitly told to format timestamps correctly (e.g., 2023-10-01T00:00:00Z).

"Fetch the event history for the IP 192.0.2.1 between September 1st, 2023 and September 30th, 2023. Format the timestamps as RFC3339. I am looking for any new services that were brought online during that window."

Aggregate Global Search Data

censys_search_aggregate

This tool is the API equivalent of the Censys Report Builder. It takes a CenQL query and splits the resulting values into term buckets with counts, allowing you to quickly analyze the distribution of technologies or vulnerabilities across the internet.

Contextual note: The number_of_buckets parameter is required and must be between 1 and 2000.

"Run an aggregate search on Censys for hosts running 'services.software.product: nginx'. Group the results by the 'location.country' field and return the top 10 buckets so I can see where this software is most heavily deployed."

Retrieve Raw PEM Certificates

censys_certificates_bulk_get_raw

Security audits often require inspecting the raw certificate chain. This tool accepts an array of SHA-256 fingerprints and returns the raw PEM-encoded certificate strings, up to 1,000 at a time.

Contextual note: This is the preferred POST endpoint over the deprecated GET version. LLMs are highly capable of parsing PEM strings to extract issuer strings, expiration dates, and SANs (Subject Alternative Names) once retrieved.

"I have a list of three suspicious SHA-256 certificate fingerprints: [hash1, hash2, hash3]. Use the bulk get raw tool to retrieve their PEM strings, then parse the PEMs and tell me if any of them share the same issuer."

Track DNS IP Resolution

censys_dns_ip_resolution_ranges

When investigating command and control (C2) infrastructure, you need to know what domain names previously resolved to a malicious IP. This tool returns DNS names that resolved to a specific IP, broken down by time range.

Contextual note: This tool requires your Censys organization_id.

"Look up the DNS resolution ranges for the IP 203.0.113.50 using my organization ID. List every domain name that has historically resolved to this IP, and note the time frames they were active."

Initiate Live Discovery Scans

create_a_censys_discovery_scan

If you need immediate intel on a new asset that isn't fully indexed yet, this tool triggers a new Live Discovery scan against a specific target.

Contextual note: This is an asynchronous operation. The tool returns a scan ID, which you must poll (using the get_single_censys_scan_by_id tool) to get the final result.

"Initiate a Live Discovery scan on the hostname 'staging-api.example.com'. Once you get the scan ID, wait 30 seconds and then check the scan status to see if it has completed."

For the complete inventory of available tools, required parameters, and JSON schemas, visit the Censys integration page.

Workflows in Action

Connecting Claude to Censys unlocks automated, multi-step threat intelligence workflows that normally require a security analyst to juggle multiple dashboard tabs and Python scripts.

Workflow 1: Investigating Suspicious Infrastructure

A security operations center (SOC) analyst receives an alert about an unknown IP address communicating with an internal database. They ask Claude to build a profile of the external host.

"Investigate the IP 198.51.100.14. Look up its current host profile, then check its DNS resolution history to see what domains point to it. Finally, retrieve its event history for the last 7 days to see if any new ports were recently opened."

Step-by-step execution:

1. Claude calls get_single_censys_host_by_id to get the current state of 198.51.100.14, discovering it is hosted on a known bulletproof hosting ASN.
2. Claude calls censys_dns_ip_resolution_ranges and finds that a suspicious domain (update-service-api.net) resolved to this IP two weeks ago.
3. Claude formulates RFC3339 timestamps for the past 7 days and calls censys_hosts_event_history.
4. Claude synthesizes the output, telling the analyst that port 22 and port 3389 were suddenly exposed three days ago, matching the timeline of the internal alert.

sequenceDiagram
    participant Analyst as Analyst
    participant Claude as Claude Desktop
    participant MCPServer as Truto MCP Server
    participant CensysAPI as Censys API
    
    Analyst->>Claude: "Investigate IP 198.51.100.14..."
    Claude->>MCPServer: call get_single_censys_host_by_id
    MCPServer->>CensysAPI: GET /api/v2/hosts/198.51.100.14
    CensysAPI-->>MCPServer: return host data
    MCPServer-->>Claude: JSON response
    Claude->>MCPServer: call censys_dns_ip_resolution_ranges
    MCPServer->>CensysAPI: GET /api/v1/dns/198.51.100.14
    CensysAPI-->>MCPServer: return domain history
    MCPServer-->>Claude: JSON response
    Claude->>Analyst: Summarized Threat Profile

Workflow 2: Auditing Corporate Certificate Sprawl

An IT administrator wants to find any certificates across the internet that are using their corporate domain name but were not issued by their approved internal Certificate Authority.

"Run an aggregate search to find all certificates where the parsed names match 'internal.mycompany.com'. Group the results by the issuer name so I can see who is signing these certificates. If you find any non-standard issuers, pull the raw PEM for one of those certificates so I can inspect it."

Step-by-step execution:

1. Claude translates the request into a CenQL query (parsed.names: internal.mycompany.com) and calls censys_search_aggregate, asking for 10 buckets grouped by parsed.issuer.organization.
2. Claude analyzes the returned buckets and notices that while 900 certificates are signed by the corporate CA, 3 are signed by "Let's Encrypt".
3. Claude extracts the SHA-256 fingerprint for one of the anomalous certificates and calls censys_certificates_bulk_get_raw.
4. Claude presents the parsed PEM string to the IT admin, highlighting the rogue certificate for revocation.

Security and Access Control

When connecting an LLM to a sensitive enterprise tool like Censys, zero-trust security is paramount. The Truto MCP architecture provides multiple layers of control at the server creation phase to ensure your AI agents only have the access they strictly need.

• Method Filtering: You can strictly limit the MCP server to read-only operations by passing config.methods: ["read"]. This allows Claude to query host data and certificates but strictly prevents it from initiating live discovery scans or modifying collections.
• Tag Filtering: Truto allows you to restrict tool generation to specific tags. Passing config.tags: ["search", "certificates"] ensures the server will only generate tools related to those endpoints, completely hiding organization or billing endpoints from the model.
• Require API Token Auth: By default, possessing the MCP URL grants access to the tools. For higher security deployments, setting require_api_token_auth: true forces the client to also pass a valid Truto API token in the Authorization header, preventing unauthorized execution if the URL leaks into log files.
• Time-to-Live (TTL): If you are generating an MCP server for a temporary audit or a specific contractor, you can set an expires_at ISO datetime. Once that time passes, Truto automatically triggers a Durable Object alarm to purge the server token and KV entries, securely invalidating the access.

Rethinking Threat Hunting with AI

Connecting Censys to Claude via a managed MCP server fundamentally changes how security teams interact with global internet data. Instead of manually writing CenQL syntax, parsing nested JSON arrays, and writing Python scripts to stitch together DNS histories, analysts can investigate infrastructure using natural language.

By offloading the complexities of endpoint versioning, rate limit header propagation, and schema mapping to Truto, your engineering team can focus on writing better agent logic instead of maintaining brittle integration code. Whether you are hunting for rogue certificates or tracking the movement of a threat actor across hosting providers, Truto ensures your AI agents have reliable, authenticated access to the ground truth of the internet.