> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encrata.com/llms.txt
> Use this file to discover all available pages before exploring further.
# MCP Server
> Connect Encrata to any AI agent using the Model Context Protocol.
## Overview
Encrata provides an [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server that lets any compatible AI agent Claude, ChatGPT, Cursor, Windsurf, VS Code Copilot use Encrata as a tool natively. Ask your AI assistant to look up a person by email, and it calls Encrata directly.
There are **two ways** to connect:
| Method | Transport | Best for |
| ----------------------------- | --------------- | -------------------------------------------------- |
| **npm package** (recommended) | stdio | Claude Desktop, ChatGPT, Cursor, VS Code, Windsurf |
| **Remote endpoint** | Streamable HTTP | Custom integrations, any MCP client |
## Quick start
### 1. Get an API key
Sign up at [encrata.com](https://encrata.com) and create an API key in [Settings → API Keys](https://encrata.com/settings/api-keys).
### 2. Install
```bash theme={"dark"}
npm install -g encrata-mcp
```
Or use `npx` no install needed (shown in configs below).
## Authentication
Pass your Encrata API key as an environment variable (npm package) or Bearer token (remote endpoint):
```
# npm package
ENCRATA_API_KEY=your-api-key
# Remote endpoint
Authorization: Bearer YOUR_API_KEY
```
## Available tools
| Tool | Description | Credits |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ |
| `lookup_email` | Full person intelligence from an email name, company, role, socials, breaches, validity | 1 per fresh lookup |
| `validate_email` | Deliverability check status (valid/invalid/catch-all/risky) plus reason, confidence, domain trust & person signal | Free |
| `check_breaches` | Data breach exposure affected services and exposed data types | Free |
| `ip_lookup` | IP intelligence geolocation, VPN/proxy/Tor detection, ASN, company | Free |
| `company_search` | Company intelligence profile data, knowledge graph, organic search results | 1 |
| `lookup_domain` | Comprehensive 16-section OSINT report WHOIS, DNS, SSL, subdomains, tech stack, passive security, company, email auth (SPF/DMARC/DKIM/CAA/BIMI/TLS-RPT), historical (Wayback/CT), risk, and recommended next steps | 1 |
| `darkweb_search` | Dark web intelligence search by email, domain, IP, or free text | 1 |
| `onion_search` | Find hidden-service (.onion) sites that mention a keyword, brand, domain, or email | 1 |
| `onion_render` | Fetch a single .onion page over Tor extracted text, emails, linked onions, outbound links | 1 |
| `google_search` | Google search web, news, images with country/language filters | 1 |
| `google_dork` | OSINT dork pack + free enrichment for a person/email/username/domain categorized Google dork links, Wikipedia & Wikidata, DuckDuckGo, Wayback, Reddit/HN/GitHub mentions, username presence | Free |
| `list_monitors` | List all email monitors | Free |
| `create_monitor` | Create a new monitor to track email changes over time | Free |
| `get_monitor` | Get details of a specific monitor | Free |
| `trigger_monitor_run` | Trigger an immediate enrichment run | 1 per email |
| `list_runs` | List monitoring runs for a monitor or all monitors | Free |
| `get_run_results` | Get enrichment results and detected changes for a run | Free |
| `list_contact_lists` | List all contact lists | Free |
| `create_contact_list` | Create a reusable email list | Free |
| `get_contact_list` | Get details of a specific contact list | Free |
| `delete_contact_list` | Delete a contact list permanently | Free |
| `list_contact_list_emails` | List all emails in a contact list | Free |
| `add_emails_to_list` | Add emails to a contact list | Free |
| `remove_emails_from_list` | Remove emails from a contact list | Free |
| `list_bulk_jobs` | List async bulk enrichment jobs | Free |
| `get_bulk_job` | Get status and download URL of a bulk job | Free |
| `cancel_bulk_job` | Cancel a pending/in-progress bulk job | Free |
### lookup\_email
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------- |
| `email` | string | Yes | Email address to look up |
| `fields` | string | No | Comma-separated fields to return (see [field reference](/api-reference/endpoint/agent-lookup#field-reference)) |
### validate\_email
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ------------------------- |
| `email` | string | Yes | Email address to validate |
### check\_breaches
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ---------------------- |
| `email` | string | Yes | Email address to check |
### ip\_lookup
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ------------------------------------ |
| `ip` | string | Yes | IP address to look up (IPv4 or IPv6) |
### company\_search
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ---------------------------- |
| `query` | string | Yes | Company name or search query |
### lookup\_domain
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ----------------------------------------------- |
| `domain` | string | Yes | Domain name to investigate (e.g. `example.com`) |
Returns a structured, 16-section OSINT report (executive summary plus DNS, infrastructure,
subdomains, website, tech stack, security, company, marketing, documents, email
infrastructure, risk, historical, gaps, next steps, and sources).
### darkweb\_search
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | -------------------------------------------------------------- |
| `query` | string | Yes | Search query (email, domain, IP, or text) |
| `type` | string | No | Type of search: `email` (default), `domain`, `ip`, or `search` |
| `offset` | number | No | Pagination offset for results |
### onion\_search
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ---------------------------------------------------------------- |
| `query` | string | Yes | Keyword, brand, domain, or email to search across onion services |
| `limit` | number | No | Maximum onion services to return (1–50, default 20) |
### onion\_render
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ------------------------------------------------------- |
| `url` | string | Yes | The `.onion` URL to fetch (from `onion_search` results) |
### google\_search
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ---------------------------------------------------------- |
| `query` | string | Yes | Search query |
| `type` | string | No | Type of search: `search` (default), `news`, or `images` |
| `country` | string | No | Country code for localized results (e.g. `us`, `uk`, `in`) |
| `lang` | string | No | Language code (e.g. `en`, `fr`) |
| `num` | number | No | Number of results to return |
### google\_dork
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ----------------------------------------------------------------- |
| `query` | string | Yes | Subject to investigate: a person name, email, username, or domain |
Returns a categorized Google dork pack plus keyless OSINT enrichment (Wikipedia, Wikidata, DuckDuckGo, Wayback Machine, Reddit/Hacker News/GitHub mentions, and social username presence). Free costs no credits.
## Connect to your AI tool
Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
```json npm package (recommended) theme={"dark"}
{
"mcpServers": {
"encrata": {
"command": "npx",
"args": ["-y", "encrata-mcp"],
"env": {
"ENCRATA_API_KEY": "your-api-key"
}
}
}
}
```
```json Remote endpoint theme={"dark"}
{
"mcpServers": {
"encrata": {
"type": "streamable-http",
"url": "https://encrata.com/mcp",
"headers": {
"Authorization": "Bearer YOUR_API_KEY"
}
}
}
}
```
Then ask Claude: *"Look up [satya@microsoft.com](mailto:satya@microsoft.com) on Encrata"*
```bash theme={"dark"}
claude mcp add encrata -- npx -y encrata-mcp
# Set your API key
export ENCRATA_API_KEY="your-api-key"
```
ChatGPT supports MCP servers via the [desktop app](https://openai.com/chatgpt/desktop/). Go to **Settings → MCP Servers → Add**:
* **Name**: Encrata
* **Command**: `npx -y encrata-mcp`
* **Environment**: `ENCRATA_API_KEY=your-api-key`
Add to `.cursor/mcp.json` in your project root:
```json npm package (recommended) theme={"dark"}
{
"mcpServers": {
"encrata": {
"command": "npx",
"args": ["-y", "encrata-mcp"],
"env": {
"ENCRATA_API_KEY": "your-api-key"
}
}
}
}
```
```json Remote endpoint theme={"dark"}
{
"mcpServers": {
"encrata": {
"type": "streamable-http",
"url": "https://encrata.com/mcp",
"headers": {
"Authorization": "Bearer YOUR_API_KEY"
}
}
}
}
```
Add to `.vscode/mcp.json` in your project root:
```json npm package (recommended) theme={"dark"}
{
"servers": {
"encrata": {
"command": "npx",
"args": ["-y", "encrata-mcp"],
"env": {
"ENCRATA_API_KEY": "your-api-key"
}
}
}
}
```
```json Remote endpoint theme={"dark"}
{
"servers": {
"encrata": {
"type": "http",
"url": "https://encrata.com/mcp",
"headers": {
"Authorization": "Bearer YOUR_API_KEY"
}
}
}
}
```
Add to `~/.codeium/windsurf/mcp_config.json`:
```json npm package (recommended) theme={"dark"}
{
"mcpServers": {
"encrata": {
"command": "npx",
"args": ["-y", "encrata-mcp"],
"env": {
"ENCRATA_API_KEY": "your-api-key"
}
}
}
}
```
```json Remote endpoint theme={"dark"}
{
"mcpServers": {
"encrata": {
"type": "streamable-http",
"url": "https://encrata.com/mcp",
"headers": {
"Authorization": "Bearer YOUR_API_KEY"
}
}
}
}
```
**npm package (stdio):**
```
Command: npx -y encrata-mcp
Transport: stdio
Env: ENCRATA_API_KEY=your-api-key
```
**Remote endpoint (HTTP):**
```
URL: https://encrata.com/mcp
Transport: Streamable HTTP
Auth: Bearer token (your API key)
```
## Example prompts
Once connected, try asking your AI:
* *"Look up [john@example.com](mailto:john@example.com)"*
* *"Is [sarah@company.io](mailto:sarah@company.io) a valid email?"*
* *"Check if [mike@gmail.com](mailto:mike@gmail.com) has been in any data breaches"*
* *"Find me everything about the person behind [hello@startup.com](mailto:hello@startup.com)"*
* *"Validate these emails and tell me which are deliverable: [a@x.com](mailto:a@x.com), [b@y.com](mailto:b@y.com)"*
* *"Search for information about OpenAI as a company"*
* *"Look up the domain tesla.com who owns it and when does it expire?"*
* *"Search the dark web for any mentions of [leaked@company.com](mailto:leaked@company.com)"*
* *"Google search for 'AI agent frameworks 2025' and summarize the top results"*
* *"Find dark web mentions of the domain example.com"*
* *"Search Google News for 'Series A funding' in the US"*
## How it works
```
┌─────────────────────────────────────────────┐
│ AI Agent (Claude, ChatGPT, etc.) │
└─────────────┬───────────────────────────────┘
│ MCP protocol
▼
┌─────────────────────────────────────────────┐
│ npm package (stdio) or Remote HTTP │
│ encrata-mcp /mcp │
└─────────────┬───────────────────────────────┘
│ REST API / JSON-RPC
▼
┌─────────────────────────────────────────────┐
│ Encrata API │
│ 10+ data sources in parallel │
└─────────────────────────────────────────────┘
```
**npm package**: Runs locally as a stdio process. Calls Encrata's REST API directly. No sessions, no state each tool call is a simple HTTP request.
**Remote endpoint**: Streamable HTTP transport (JSON-RPC 2.0 over POST) at `https://encrata.com/mcp`. Useful for custom integrations or clients that only support HTTP transport.
## Source code
The MCP server is open source:
```
https://github.com/Encratahq/encrata-mcp
```
## Advanced: raw JSON-RPC
If you're building a custom integration against the remote endpoint:
```bash Initialize theme={"dark"}
curl -X POST https://encrata.com/mcp \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "initialize",
"params": {
"protocolVersion": "2025-03-26",
"capabilities": {},
"clientInfo": { "name": "my-app", "version": "1.0" }
}
}'
```
```bash List Tools theme={"dark"}
curl -X POST https://encrata.com/mcp \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Mcp-Session-Id: SESSION_ID" \
-d '{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/list"
}'
```
```bash Call Tool theme={"dark"}
curl -X POST https://encrata.com/mcp \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Mcp-Session-Id: SESSION_ID" \
-d '{
"jsonrpc": "2.0",
"id": 3,
"method": "tools/call",
"params": {
"name": "lookup_email",
"arguments": {
"email": "satya@microsoft.com",
"fields": "n,co,role,s"
}
}
}'
```