---
title: "Connect Censys to ChatGPT: Search and aggregate global asset data"
slug: connect-censys-to-chatgpt-search-and-aggregate-global-asset-data
date: 2026-08-10
author: Sidharth Verma
categories: ["AI & Agents"]
excerpt: "Learn how to connect Censys to ChatGPT using Truto's managed MCP server. Search global assets, automate threat intelligence, and aggregate host data with AI."
tldr: "Connect Censys to ChatGPT by generating a secure, managed MCP server URL with Truto. Give your AI agents direct access to search global assets, extract raw certificates, and automate threat intelligence workflows."
canonical: https://truto.one/blog/connect-censys-to-chatgpt-search-and-aggregate-global-asset-data/
---

# Connect Censys to ChatGPT: Search and aggregate global asset data


If you need to connect Censys to ChatGPT to automate attack surface management, execute global asset searches, or orchestrate threat intelligence gathering, you need a [Model Context Protocol (MCP) server](https://truto.one/what-is-mcp-and-mcp-servers-and-how-do-they-work/). This server acts as the translation layer between ChatGPT's JSON-RPC tool calls and the Censys REST API.

If your team uses Claude, check out our guide on [connecting Censys to Claude](https://truto.one/connect-censys-to-claude-track-host-history-and-certificate-records/) or explore our broader architectural overview on [connecting Censys to AI Agents](https://truto.one/connect-censys-to-ai-agents-automate-discovery-and-asset-management/).

[Giving a Large Language Model (LLM) read and write access](https://truto.one/what-is-mcp-model-context-protocol-the-2026-guide-for-saas-pms/) to a vast, complex intelligence platform like Censys is an engineering hurdle. You have to handle deeply nested payload structures, translate raw PEM certificates, and manage strict query syntax (CenQL). Every time a developer adds a new use case or the Censys API updates, your custom server code must be updated, redeployed, and tested.

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

::cta{buttonText="Talk to us" buttonUrl="https://cal.com/truto/partner-with-truto"}
Stop writing boilerplate API integration code. Let Truto generate secure, managed MCP servers for your AI agents in seconds.
:::

## The Engineering Reality of the Censys API

A custom MCP server is a self-hosted integration layer that translates an LLM's tool calls into REST API requests. While the open MCP standard provides a predictable way for models to discover tools, implementing it against the actual Censys API is uniquely painful.

If you decide to [build a custom MCP server](https://truto.one/the-hands-on-guide-to-building-mcp-servers-for-ai-agents-2026/) for Censys, you own the entire integration lifecycle. Here are the specific challenges that break standard CRUD assumptions when working with this provider:

### CenQL Syntax and Query Translation
Censys relies heavily on its proprietary query language (CenQL) for global asset discovery. When an LLM wants to find all hosts running a specific vulnerable service, it must format the query string perfectly. If your MCP server does not expose the proper schemas and descriptions, the LLM will hallucinate invalid syntax. Furthermore, Censys has legacy systems (CSL) that require explicit conversion endpoints to format queries correctly for the modern platform.

### Deeply Nested Host and Certificate Objects
Censys payloads are massive. A single host response includes autonomous system data, WHOIS records, software versions, and an array of potentially hundreds of services with individual banner hashes. Certificates often require handling raw PEM-encoded strings. Passing this unstructured, massive data directly to an LLM blows up context windows. Your MCP server must present strictly typed JSON schemas derived from Censys documentation to ensure the LLM maps arguments correctly.

### Deprecated GET Endpoints and Bulk Operations
Censys is actively deprecating standard `GET` requests for list operations (like fetching multiple hosts or certificates by ID) in favor of POST-based `bulk_get` endpoints. A naive custom MCP server that maps standard REST operations will quickly find its endpoints returning deprecation warnings or failing entirely. Your tool generation logic must intelligently route the LLM toward the modern bulk operations.

### Strict Rate Limits and Error Transparency
Censys enforces rate limits strictly based on your organization's plan. A critical architectural detail: **Truto does not retry, throttle, or apply backoff on rate limit errors.** When the Censys API returns an HTTP 429, Truto passes that error directly to the caller. Truto normalizes the upstream rate limit info into standardized headers (`ratelimit-limit`, `ratelimit-remaining`, `ratelimit-reset`) per the IETF spec. 

This is a feature, not a bug. In an agentic architecture, the caller (ChatGPT) must be aware of the exact reset window so it can pause execution or pivot to a different task, rather than having a middleware layer silently hang the connection.

## The Managed MCP Approach

Instead of forcing your engineering team to build, host, and maintain a custom MCP server, you can use Truto to dynamically generate one. Truto derives tool definitions directly from the Censys integration's resource configurations and documentation records. 

A tool only appears in the MCP server if it has a corresponding documentation entry - acting as a quality gate that ensures only well-documented, AI-ready endpoints are exposed to ChatGPT.

### Step 1: Creating the Censys MCP Server

Each MCP server is scoped to a single connected Censys account and backed by a cryptographic token. You can generate this server via the Truto UI or programmatically via the API.

**Method A: Via the Truto UI**
1. Navigate to the integrated account page for your Censys connection.
2. Click the **MCP Servers** tab.
3. Click **Create MCP Server**.
4. Select your desired configuration (name, method filters like "read-only", and tag filters).
5. Copy the generated MCP server URL (e.g., `https://api.truto.one/mcp/a1b2c3d4...`).

**Method B: Via the API**
You can dynamically provision an MCP server for an automated workflow by making an authenticated request to the Truto API.

```typescript
// POST /integrated-account/:id/mcp
{
  "name": "Censys Threat Intel MCP",
  "config": {
    "methods": ["read", "list", "custom"],
    "tags": ["hosts", "certificates", "search"]
  },
  "expires_at": "2026-12-31T23:59:59Z"
}
```

The API returns a fully provisioned endpoint. The random hex token in the URL is hashed via HMAC before being stored in distributed edge storage, ensuring rapid authentication with high security.

### Step 2: Connecting the MCP Server to ChatGPT

Once you have your Truto MCP URL, connecting it to ChatGPT takes seconds.

**Method A: Via the ChatGPT UI**
1. In ChatGPT, navigate to **Settings** -> **Apps** -> **Advanced settings**.
2. Enable **Developer mode**.
3. Under MCP servers / Custom connectors, click to add a new server.
4. Enter a name (e.g., "Censys Intel").
5. Paste the Truto MCP URL and click **Add**.

ChatGPT will immediately perform the JSON-RPC initialization handshake and load the Censys tools.

**Method B: Via Manual Config File**
If you are running a local client, headless agent framework, or testing via the official MCP SSE transport, you can define the server in your standard MCP configuration file.

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

## Hero Tools for Censys

When ChatGPT connects to the server, it calls the `tools/list` protocol method. Truto dynamically builds the tool definitions by combining the available Censys resources with their exact query and body schemas. 

Here are the highest-leverage tools available for Censys:

### list_all_censys_search
Search Censys global assets using a CenQL query string. This is the primary entry point for broad asset discovery and attack surface mapping.

**Contextual usage notes:** This method automatically injects `limit` and `next_cursor` properties into the query schema. The LLM is explicitly instructed by the generated description to pass the cursor value back unchanged if it needs to paginate through more than 100 results.

> "Search Censys for all global assets running an outdated version of NGINX on port 443. Limit the results to 50 records and provide a summary of their autonomous systems."

### censys_hosts_enrichment
Get massive enrichment data for a single Censys host by IP address, including location, autonomous system, reputation, and third-party labels.

**Contextual usage notes:** This tool is crucial for deep dives on suspicious IPs discovered in previous broad searches. It returns a heavy, deeply nested object. The LLM leverages the `host_ip` required parameter to fetch the targeted data.

> "Take the suspicious IP address we found in the previous search and run a full host enrichment. Tell me if it has any negative reputation flags or known malicious labels."

### censys_search_aggregate
Aggregate Censys search results by a specified field, splitting values into term buckets with counts. This is the API equivalent of the Censys Report Builder.

**Contextual usage notes:** The LLM must supply a valid `field`, the `number_of_buckets` (up to 2000), and a `query`. This tool allows the agent to perform data science and statistical analysis without downloading millions of individual records.

> "Run an aggregate search on the CenQL query for exposed RDP ports. Break down the results by the 'location.country' field and return the top 20 buckets."

### censys_certificates_bulk_get_raw
Retrieve up to 1,000 Censys certificates in raw PEM-encoded format by their SHA-256 fingerprints.

**Contextual usage notes:** This tool uses the modern POST-based bulk approach. It requires an array of `certificate_ids`. It bypasses parsed metadata and returns the raw PEM content directly, which is useful when the agent needs to pass certificates to other validation tools or scripts.

> "Fetch the raw PEM certificates for these five SHA-256 fingerprints we just identified, and format them into a single code block for me to review."

### censys_hosts_event_history
Get the event history timeline for a specific Censys host to see when services were added, removed, or changed.

**Contextual usage notes:** Requires `host_id`, `start_time`, and `end_time`. The timestamps must be valid RFC3339 strings. The tool definition ensures the LLM knows to format the time bounds correctly before executing the request.

> "Pull the event history for IP 192.0.2.1 between January 1st and January 31st of this year. Tell me if any new ports were opened during that window."

### create_a_censys_censeye_job
Create an asynchronous CensEye pivot analysis job for a host, web property, or certificate.

**Contextual usage notes:** This triggers a heavy background job. The tool returns a `job_id`. The LLM must be instructed (via your prompt or agent loop) to subsequently poll the `get_single_censys_censeye_job_by_id` tool until completion before attempting to fetch the results.

> "Initialize a CensEye pivot analysis job for this certificate fingerprint. Once you get the job ID, check its status, and notify me when the results are ready to be read."

For the complete inventory of available tools and exact schema definitions, visit the [Censys integration page](https://truto.one/integrations/detail/censys).

## Workflows in Action

When you connect Truto's MCP server to ChatGPT, the LLM stops being a simple chat interface and becomes a capable threat intelligence analyst. Here is how real-world workflows execute autonomously.

### Workflow 1: Attack Surface Reconnaissance
An IT admin needs to investigate the footprint of exposed development servers across the internet and analyze where they are hosted.

> "Search Censys for hosts running 'Jenkins' on port 8080 that do not have authentication enabled. Once you have the first page of results, run an aggregate report to show me which autonomous systems (ASNs) are hosting the highest number of these exposed servers."

1. ChatGPT calls `list_all_censys_search` with the CenQL query `services.service_name: "jenkins" and services.port: 8080`. 
2. The proxy API layer parses the flat JSON-RPC arguments, routes the request to Censys, and returns the paginated host data.
3. ChatGPT analyzes the hosts, then autonomously calls `censys_search_aggregate` with the same query, setting `field` to `autonomous_system.name` and `number_of_buckets` to 10.
4. ChatGPT formats the resulting buckets into a clean markdown table for the admin.

```mermaid
sequenceDiagram
    participant ChatGPT as ChatGPT Agent
    participant MCP as MCP Server
    participant Truto as Proxy API Layer
    participant Censys as Censys Platform
    ChatGPT->>MCP: Call list_all_censys_search
    MCP->>Truto: Validate token & parse flat arguments
    Truto->>Censys: Execute CenQL query
    Censys-->>Truto: Return paginated hosts
    Truto-->>MCP: Format JSON-RPC response
    MCP-->>ChatGPT: Provide context with next_cursor
```

### Workflow 2: Certificate Expiry and PEM Extraction
A DevOps engineer needs to identify expiring certificates tied to a specific domain and extract them for local analysis.

> "Find all certificates matching the domain 'corp.example.com' that expire in the next 30 days. Extract their SHA-256 fingerprints, and then retrieve the raw PEM formats for all of them at once."

1. ChatGPT calls `list_all_censys_search` (or a specific certificate search tool if configured) using a CenQL query filtering by the domain and expiration date range.
2. The model extracts the `fingerprint_sha256` values from the returned array.
3. ChatGPT calls `censys_certificates_bulk_get_raw`, passing the array of extracted fingerprints into the `certificate_ids` body parameter.
4. Truto routes the POST request to the Censys bulk endpoint and returns the raw string content.
5. ChatGPT presents the raw PEM blocks to the engineer.

## Security and Access Control

Giving an AI agent access to global threat intelligence tools requires strict governance. Truto provides [granular controls at the MCP server level](https://truto.one/handling-auth-tool-sharing-in-multi-agent-frameworks-via-mcp/) to ensure secure execution:

*   **Method filtering:** You can restrict a server to specific operations. By passing `methods: ["read"]` during creation, the server will only generate tools for `get` and `list` operations, ensuring the LLM cannot accidentally create collections or trigger intensive jobs.
*   **Tag filtering:** Truto tags integration resources logically. You can scope an MCP server by passing `tags: ["certificates"]`, which forces the server to drop all host, search, and admin tools, limiting the LLM to certificate workflows only.
*   **require_api_token_auth:** For high-security environments, enabling this flag adds a second authentication layer. Possession of the MCP URL is no longer enough; the client must also pass a valid Truto API token in the `Authorization` header, leveraging standard session middleware.
*   **expires_at:** MCP servers can be granted a time-to-live. By setting an ISO datetime, a cleanup alarm is scheduled via distributed edge storage. Once the timestamp hits, the token is automatically purged from KV storage, immediately revoking access.
*   **Flat Input Namespace Resolution:** When ChatGPT sends a tool call, arguments arrive as a flat JSON object. Truto's proxy layer uses the integration schemas to dynamically split these arguments into query parameters and complex nested body payloads before routing to Censys, preventing injection bleed.

## Strategic Wrap-up

Connecting ChatGPT to Censys transforms static threat intelligence into an interactive, agent-driven workflow. However, building the translation layer to handle CenQL syntax, raw PEM extraction, and strict rate limits is an engineering sinkhole.

By leveraging Truto to generate a managed MCP server, you offload the boilerplate of JSON schemas, token hashing, and JSON-RPC protocol handling. Your engineering team stops maintaining fragile API wrapper code and starts orchestrating intelligent, secure workflows.