Building AI Applications

This section covers patterns and architecture for building AI-powered security applications that use the Polarity MCP as a data enrichment layer.

The Core Architecture Pattern

The Polarity MCP acts as a structured bridge between an AI agent and Polarity's integration ecosystem.  Instead of writing custom API connectors for each security tool, your AI application connects to Polarity once and gains uniform access to all integrations the server has configured.

The typical architecture looks like this:

1. User input or trigger (a question, an alert, a SIEM event) arrives at your AI agent.

2. The agent calls list\_available\_integrations to discover what data sources are available (or uses a cached list).

3. The agent determines which integrations are relevant to the entities in the input.

4. The agent calls do\_integration\_lookup for each relevant integration to obtain enrichment data.

5. The agent synthesizes the results and generates a response, triage decision, or automated action.

Use Case:  Automated IOC Enrichment

An analyst pastes a list of suspicious IPs and domains from a SIEM alert into your AI agent.

The agent:

1. Calls parse\_entities to extract and classify each indicator from the pasted text.

2. Calls list\_available\_integrations to find integrations that support IPv4 and domain entity types.

3. Calls do\_integration\_lookup for each relevant integration, passing each indicator.

4. Aggregates the results:  reputation scores, geolocation, ASN data, historical malware associations, passive DNS records.

5. Generates a triage report with a confidence-scored verdict for each indicator.

Because reducers strip raw integration responses to the most relevant fields before they reach the LLM, the agent can process many indicators within a single context window.

Use Case:  Natural-Language Threat Queries

A user asks your agent: "Is 198.51.100.42 malicious, and what do we know about it?"

The agent:

1. Calls do\_integration\_lookup against the most relevant threat intelligence integrations (such as AbuseIPDB, VirusTotal, and/or Shodan) with the IP as the query.

2. Receives reduced, structured enrichment data from each integration.

3. The LLM synthesizes the data into a coherent, natural-language answer, citing specific findings from each source.

Integration Scoping and Permissions

Every MCP session is fully user-scoped.  

The tools available to your AI agent are bounded by:

• Subscriptions:  

  • The authenticated user must be subscribed to an integration for it to appear in list\_available\_integrations and be callable via do\_integration\_lookup.

• Running status:

  • Only integrations in the running state are available.

  • Stopped integrations are excluded.

• Notification context (when provided):  

  • If a notification context is passed along with a request, the allowed integration list is further narrowed to integrations present in that context.

  • Without a context, the fallback is the full list of the user's subscribed running integrations.

This scoping ensures that your AI agent cannot access integrations the user is not authorized to view, and that the tool list it receives is always up to date and reflects what is actually operational on the server.

Designing Prompts for Polarity MCP Tools

When building an agent that uses the Polarity MCP, consider the following prompt design guidelines:

• Discover before calling:

  • If the integration to query is not known in advance, always call list\_available\_integrations first.

  • Integration IDs are runtime-generated and include version numbers and node identifiers (e.g., virustotal\_3\_1\_2\_node\_18\_abc123). Do not hardcode them.

• Use the query field naturally:

  • do\_integration\_lookup parses entities automatically from the query parameter.

  • You do not need to pre-parse or clean entity strings before calling the tool.

• Batch by integration, not by entity:

  • Each call to do\_integration\_lookup can include multiple entities in the query string.

  • It is more efficient to pass all relevant entities in a single call per integration than to make a separate call for each entity.

• Handle empty results gracefully:

  • An integration may return no results for a given entity.

  • Design your agent to handle this case without treating it as an error.

Token Budget Considerations

MCP reducers significantly reduce the token cost of integration data.  Even with reducers, a lookup against a rich integration like VirusTotal may return several hundred tokens of structured data per entity.

For high-volume workflows:

• Use list\_available\_integrations to pre-select only the integrations most relevant to the entity types you are investigating, rather than querying all integrations.

• If a specific integration returns overly verbose data for your use case, consider requesting a custom reducer for that integration from your Polarity Administrator.

• For large-scale batch workflows, consider processing entities in parallel calls to multiple integrations and aggregating results at the application layer rather than within a single LLM context.