# Encrata MCP Server

Production-ready MCP server for email intelligence workflows.

Use Encrata MCP to let AI agents run:
- Email lookup and enrichment
- Email validity checks
- Breach checks
- Monitor lifecycle and run management
- Contact list management
- Bulk async jobs (validity, identity, password breach)

Links: [Website](https://encrata.com) | [Docs](https://docs.encrata.com/mcp-server) | [API Keys](https://encrata.com/settings/api-keys)

## 1) Overview

### What this MCP server does

Encrata MCP exposes domain tools over the Model Context Protocol so AI clients can call Encrata APIs without writing glue code. The server runs locally and forwards tool calls to Encrata REST endpoints using your API key.

It covers the full workflow — **email intelligence** (lookup, validate, breaches), **monitoring**, **contact lists**, **bulk/async jobs**, plus **account management**: `whoami`/credits, **API keys**, **webhooks**, and **workspaces & members**.

### Supported transports

| Transport | Status | Notes |
| --- | --- | --- |
| MCP stdio | Supported | Primary transport used by this package (`npx -y encrata-mcp`) |
| MCP Streamable HTTP / SSE | Not exposed by this package | You can still call Encrata REST HTTP endpoints directly from your own backend |
| Encrata REST HTTP | Supported (upstream API) | Used internally by this MCP server |

### Supported AI clients

- Claude Desktop
- Claude Code
- Cursor
- VS Code / GitHub Copilot (MCP-compatible mode)
- ChatGPT Desktop (MCP server integration where available)
- Windsurf
- Other MCP-compatible clients that support stdio servers

## 2) Prerequisites

### API key requirements

- You need an active Encrata API key.
- Minimum required scope: access to the endpoints used by tools in this README.
- Create keys at: https://encrata.com/settings/api-keys

### Authentication methods

- Supported: Bearer token API key (`Authorization: Bearer <key>`)
- Not supported in this MCP package: OAuth client flow

### Required software

- Node.js 18+
- npm (or npx)
- An MCP-compatible AI client

## 3) Quick Start

### Install and run

```bash
ENCRATA_API_KEY=your-api-key npx -y encrata-mcp
```

Windows PowerShell:

```powershell
$env:ENCRATA_API_KEY="your-api-key"
npx -y encrata-mcp
```

### Connect to Claude Desktop

Config file:
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "encrata": {
      "command": "npx",
      "args": ["-y", "encrata-mcp"],
      "env": {
        "ENCRATA_API_KEY": "your-api-key"
      }
    }
  }
}
```

### Connect to Claude Code

```bash
claude mcp add encrata -- npx -y encrata-mcp
export ENCRATA_API_KEY="your-api-key"
```

### Connect to Cursor

Create `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "encrata": {
      "command": "npx",
      "args": ["-y", "encrata-mcp"],
      "env": {
        "ENCRATA_API_KEY": "your-api-key"
      }
    }
  }
}
```

### Connect to ChatGPT / OpenAI

In ChatGPT Desktop:
1. Open Settings
2. Open MCP Servers
3. Add server with:
- Name: `Encrata`
- Command: `npx -y encrata-mcp`
- Environment: `ENCRATA_API_KEY=your-api-key`

Note: Availability can vary by ChatGPT app version and account rollout.

### Connect to VS Code or other MCP clients

Create `.vscode/mcp.json`:

```json
{
  "servers": {
    "encrata": {
      "command": "npx",
      "args": ["-y", "encrata-mcp"],
      "env": {
        "ENCRATA_API_KEY": "your-api-key"
      }
    }
  }
}
```

## 4) Configuration

### Environment variables

| Variable | Required | Default | Why it exists |
| --- | --- | --- | --- |
| `ENCRATA_API_KEY` | Yes | None | Authenticates every tool call to Encrata APIs |
| `ENCRATA_BASE_URL` | No | `https://encrata.com` | Points traffic to a custom/self-hosted API base |

### JSON configuration examples

Minimal server block (works for most clients):

```json
{
  "command": "npx",
  "args": ["-y", "encrata-mcp"],
  "env": {
    "ENCRATA_API_KEY": "your-api-key",
    "ENCRATA_BASE_URL": "https://encrata.com"
  }
}
```

### CLI examples

Check version:

```bash
npx -y encrata-mcp --version
```

Show help:

```bash
npx -y encrata-mcp --help
```

Run with custom base URL:

```bash
ENCRATA_API_KEY=your-api-key ENCRATA_BASE_URL=https://api.example.com npx -y encrata-mcp
```

### HTTP endpoint examples (upstream Encrata API)

Even though this package runs MCP over stdio, it calls REST endpoints like:

```http
POST /api/agent/lookup
POST /api/agent/validate
POST /api/agent/breaches
GET  /api/agent/monitors
POST /api/validity-jobs
GET  /api/validity-jobs/results?id=job_123&page=1&page_size=50
```

### Authentication headers

```http
Authorization: Bearer YOUR_ENCRATA_API_KEY
Content-Type: application/json
```

Why this matters:
- `Authorization` is required for every protected endpoint.
- `Content-Type` ensures JSON bodies parse correctly.

## 5) Available Tools

Tool responses in MCP are returned in the `content` array, usually as human-readable text plus optional JSON blocks.

Output conventions used below:
- `text`: summary line(s)
- `json`: structured payload (embedded as fenced JSON text in content)

### Email Intelligence Tools

#### lookup_email
- Description: Full person intelligence by email.
- Input schema:
```json
{
  "type": "object",
  "required": ["email"],
  "properties": {
    "email": { "type": "string", "format": "email" },
    "fields": { "type": "string", "description": "Comma-separated field list" }
  }
}
```
- Output schema:
```json
{
  "text": "Formatted profile summary",
  "json": {
    "name": "string",
    "email": "string",
    "company": "string",
    "role": "string",
    "industry": "string",
    "socials": { "linkedin": "string" },
    "breaches": { "count": 0, "services": ["string"] }
  }
}
```
- Example request:
```json
{ "email": "john@example.com", "fields": "name,email,company,role,socials,breaches" }
```
- Example response:
```json
{
  "name": "John Doe",
  "email": "john@example.com",
  "company": "Acme Inc",
  "role": "Engineering Manager",
  "socials": { "linkedin": "https://linkedin.com/in/johndoe" },
  "breaches": { "count": 1, "services": ["example-service"] }
}
```
- Common use cases:
- Sales lead research
- User risk screening
- Account intelligence enrichment

#### validate_email
- Description: Full dashboard-grade validity report with billing parity (1 credit on fresh lookup, free repeat within charge window).
- Input schema:
```json
{ "type": "object", "required": ["email"], "properties": { "email": { "type": "string", "format": "email" } } }
```
- Output schema:
```json
{
  "email": "string",
  "status": "valid|invalid|catch_all|risky",
  "reason": "string",
  "confidence": 0.99,
  "role": false,
  "disposable": false,
  "provider": "string",
  "mx": ["string"],
  "domain_trust": { "grade": "A", "dkim": true, "bimi": false, "dnssec": true },
  "person_signal": { "count": 0, "sources": ["string"] },
  "smtp": { "mx_host": "string", "catch_all": false, "greylisted": false },
  "canonical": "string",
  "free_provider": false,
  "domain_info": { "registrar": "string", "created_at": "string", "age_days": 0 },
  "mail_servers": ["string"],
  "footprint": { "breaches": { "count": 0 }, "registered_services": ["string"] },
  "credits": 1
}
```
- Example request:
```json
{ "email": "ops@company.com" }
```
- Example response:
```json
{
  "email": "ops@company.com",
  "status": "valid",
  "reason": "deliverable",
  "confidence": 0.98,
  "provider": "google",
  "canonical": "ops@company.com",
  "free_provider": true,
  "mx": ["aspmx.l.google.com"],
  "domain_trust": { "grade": "A", "dkim": true, "bimi": false, "dnssec": true },
  "domain_info": { "registrar": "MarkMonitor", "created_at": "2000-01-01", "age_days": 9000 },
  "mail_servers": ["aspmx.l.google.com"],
  "footprint": { "breaches": { "count": 0 }, "registered_services": ["workspace"] },
  "credits": 1
}
```
- Common use cases:
- Signup checks with trust scoring
- Deliverability + domain posture review
- Billed validation workflows with repeat-window caching

#### check_breaches
- Description: Breach exposure check for an email.
- Input schema:
```json
{ "type": "object", "required": ["email"], "properties": { "email": { "type": "string", "format": "email" } } }
```
- Output schema:
```json
{
  "email": "string",
  "count": 0,
  "services": ["string"],
  "exposed_data": ["string"],
  "message": "string"
}
```
- Example request:
```json
{ "email": "alice@example.com" }
```
- Example response:
```json
{
  "email": "alice@example.com",
  "count": 2,
  "services": ["ServiceA", "ServiceB"],
  "exposed_data": ["email", "password_hash"],
  "message": "found in known breaches"
}
```
- Common use cases:
- Security review
- Incident response support
- Priority scoring for remediation

### Monitoring Tools

#### list_monitors
- Description: List monitor resources and run cadence.
- Input schema:
```json
{ "type": "object", "properties": {} }
```
- Output schema:
```json
{ "monitors": [{ "id": "string", "name": "string", "status": "string", "frequency": "string", "email_count": 0 }] }
```
- Example request:
```json
{}
```
- Example response:
```json
{ "monitors": [{ "id": "mon_123", "name": "Sales Leads", "status": "active", "frequency": "monthly", "email_count": 240 }] }
```
- Common use cases:
- Operations overview
- Job scheduling audits

#### create_monitor
- Description: Create an email monitor.
- Input schema:
```json
{
  "type": "object",
  "required": ["name"],
  "properties": {
    "name": { "type": "string" },
    "emails": { "type": "array", "items": { "type": "string", "format": "email" } },
    "frequency": { "type": "string", "enum": ["weekly", "biweekly", "monthly", "quarterly"] },
    "change_detection": { "type": "string", "enum": ["diff_only", "full_refresh"] },
    "list_id": { "type": "string" }
  }
}
```
- Output schema:
```json
{ "id": "string", "name": "string", "frequency": "string", "email_count": 0 }
```
- Example request:
```json
{ "name": "VIP Accounts", "list_id": "list_123", "frequency": "weekly", "change_detection": "diff_only" }
```
- Example response:
```json
{ "id": "mon_123", "name": "VIP Accounts", "frequency": "weekly", "email_count": 120 }
```
- Common use cases:
- Executive contact watchlists
- Compliance monitoring

#### get_monitor
- Description: Retrieve one monitor by ID.
- Input schema:
```json
{ "type": "object", "required": ["monitor_id"], "properties": { "monitor_id": { "type": "string" } } }
```
- Output schema:
```json
{ "id": "string", "name": "string", "status": "string", "frequency": "string", "change_detection": "string" }
```
- Example request:
```json
{ "monitor_id": "mon_123" }
```
- Example response:
```json
{ "id": "mon_123", "name": "VIP Accounts", "status": "active", "frequency": "weekly", "change_detection": "diff_only" }
```
- Common use cases:
- Debugging config drift
- Dashboard details view

#### trigger_monitor_run
- Description: Start a run now.
- Input schema:
```json
{ "type": "object", "required": ["monitor_id"], "properties": { "monitor_id": { "type": "string" } } }
```
- Output schema:
```json
{ "run_id": "string", "status": "string", "message": "string" }
```
- Example request:
```json
{ "monitor_id": "mon_123" }
```
- Example response:
```json
{ "run_id": "run_456", "status": "queued", "message": "run started" }
```
- Common use cases:
- Manual refresh before reporting
- Urgent recon checks

#### list_runs
- Description: List runs for a monitor or globally.
- Input schema:
```json
{
  "type": "object",
  "properties": {
    "monitor_id": { "type": "string" },
    "limit": { "type": "number" },
    "offset": { "type": "number" }
  }
}
```
- Output schema:
```json
{ "runs": [{ "id": "string", "status": "string", "total_records": 0, "changes_detected": 0, "credits_used": 0 }], "total": 0 }
```
- Example request:
```json
{ "monitor_id": "mon_123", "limit": 20, "offset": 0 }
```
- Example response:
```json
{ "runs": [{ "id": "run_456", "status": "completed", "total_records": 120, "changes_detected": 7, "credits_used": 120 }], "total": 42 }
```
- Common use cases:
- Throughput tracking
- Credit consumption analysis

#### get_run_results
- Description: Retrieve snapshots and change details for one run.
- Input schema:
```json
{
  "type": "object",
  "required": ["monitor_id", "run_id"],
  "properties": {
    "monitor_id": { "type": "string" },
    "run_id": { "type": "string" },
    "changes_only": { "type": "boolean" }
  }
}
```
- Output schema:
```json
{ "run": { "id": "string" }, "results": [{ "email": "string", "has_changes": true, "changes": {} }], "total": 0 }
```
- Example request:
```json
{ "monitor_id": "mon_123", "run_id": "run_456", "changes_only": true }
```
- Example response:
```json
{ "results": [{ "email": "ceo@example.com", "has_changes": true, "changes": { "role": ["CTO", "CEO"] } }], "total": 1 }
```
- Common use cases:
- Alert payload generation
- Post-run triage

### Contact List Tools

#### list_contact_lists
- Description: List all reusable email lists.
- Input schema:
```json
{ "type": "object", "properties": {} }
```
- Output schema:
```json
[{ "id": "string", "name": "string", "email_count": 0, "created_at": "string" }]
```
- Example request:
```json
{}
```
- Example response:
```json
[{ "id": "list_123", "name": "Engineering", "email_count": 84, "created_at": "2026-07-01T10:00:00Z" }]
```
- Common use cases:
- Inventory and governance
- Input source selection for monitors

#### create_contact_list
- Description: Create list with optional initial emails.
- Input schema:
```json
{
  "type": "object",
  "required": ["name"],
  "properties": {
    "name": { "type": "string" },
    "emails": { "type": "array", "items": { "type": "string", "format": "email" } }
  }
}
```
- Output schema:
```json
{ "id": "string", "name": "string", "email_count": 0, "created_at": "string" }
```
- Example request:
```json
{ "name": "Engineering", "emails": ["alice@company.com", "bob@company.com"] }
```
- Example response:
```json
{ "id": "list_123", "name": "Engineering", "email_count": 2, "created_at": "2026-07-28T10:00:00Z" }
```
- Common use cases:
- Team-based watchlists
- Sales segment setup

#### get_contact_list
- Description: Get one list by ID.
- Input schema:
```json
{ "type": "object", "required": ["list_id"], "properties": { "list_id": { "type": "string" } } }
```
- Output schema:
```json
{ "id": "string", "name": "string", "email_count": 0, "created_at": "string" }
```
- Example request:
```json
{ "list_id": "list_123" }
```
- Example response:
```json
{ "id": "list_123", "name": "Engineering", "email_count": 84, "created_at": "2026-07-01T10:00:00Z" }
```
- Common use cases:
- Metadata fetch before bulk updates

#### delete_contact_list
- Description: Permanently delete a list.
- Input schema:
```json
{ "type": "object", "required": ["list_id"], "properties": { "list_id": { "type": "string" } } }
```
- Output schema:
```json
{ "deleted": true }
```
- Example request:
```json
{ "list_id": "list_123" }
```
- Example response:
```json
{ "deleted": true }
```
- Common use cases:
- Lifecycle cleanup
- Data retention compliance

#### list_contact_list_emails
- Description: List emails in a specific list.
- Input schema:
```json
{ "type": "object", "required": ["list_id"], "properties": { "list_id": { "type": "string" } } }
```
- Output schema:
```json
[{ "email": "string" }]
```
- Example request:
```json
{ "list_id": "list_123" }
```
- Example response:
```json
[{ "email": "alice@company.com" }, { "email": "bob@company.com" }]
```
- Common use cases:
- Auditing list content
- Export prep

#### add_emails_to_list
- Description: Add emails to a list.
- Input schema:
```json
{
  "type": "object",
  "required": ["list_id", "emails"],
  "properties": {
    "list_id": { "type": "string" },
    "emails": { "type": "array", "items": { "type": "string", "format": "email" } }
  }
}
```
- Output schema:
```json
{ "added": 0 }
```
- Example request:
```json
{ "list_id": "list_123", "emails": ["new@company.com"] }
```
- Example response:
```json
{ "added": 1 }
```
- Common use cases:
- Incremental ingestion
- CRM sync

#### remove_emails_from_list
- Description: Remove emails from a list.
- Input schema:
```json
{
  "type": "object",
  "required": ["list_id", "emails"],
  "properties": {
    "list_id": { "type": "string" },
    "emails": { "type": "array", "items": { "type": "string", "format": "email" } }
  }
}
```
- Output schema:
```json
{ "deleted": 0 }
```
- Example request:
```json
{ "list_id": "list_123", "emails": ["old@company.com"] }
```
- Example response:
```json
{ "deleted": 1 }
```
- Common use cases:
- Data hygiene
- Opt-out enforcement

### Bulk Job Management Tools

#### list_bulk_jobs
- Description: List recent large async jobs.
- Input schema:
```json
{ "type": "object", "properties": {} }
```
- Output schema:
```json
[{ "id": "string", "status": "pending|processing|completed|failed|cancelled", "processed_count": 0, "total_emails": 0, "credits_used": 0 }]
```
- Example request:
```json
{}
```
- Example response:
```json
[{ "id": "bulk_123", "status": "processing", "processed_count": 3000, "total_emails": 10000, "credits_used": 3000 }]
```
- Common use cases:
- Queue health visibility
- Backlog management

#### get_bulk_job
- Description: Get one bulk job and download URL if available.
- Input schema:
```json
{ "type": "object", "required": ["job_id"], "properties": { "job_id": { "type": "string" } } }
```
- Output schema:
```json
{ "job": { "id": "string", "status": "string" }, "download_url": "string" }
```
- Example request:
```json
{ "job_id": "bulk_123" }
```
- Example response:
```json
{ "job": { "id": "bulk_123", "status": "completed" }, "download_url": "https://..." }
```
- Common use cases:
- Progress checks
- Result retrieval handoff

#### cancel_bulk_job
- Description: Cancel a pending/in-progress bulk job.
- Input schema:
```json
{ "type": "object", "required": ["job_id"], "properties": { "job_id": { "type": "string" } } }
```
- Output schema:
```json
{ "cancelled": true }
```
- Example request:
```json
{ "job_id": "bulk_123" }
```
- Example response:
```json
{ "cancelled": true }
```
- Common use cases:
- Cost control
- Job replacement

### Async Email Job Tools

#### bulk_validate_emails
- Description: Create async validity job from inline emails.
- Input schema:
```json
{
  "type": "object",
  "required": ["emails"],
  "properties": {
    "emails": { "type": "array", "items": { "type": "string", "format": "email" }, "minItems": 1, "maxItems": 100000 },
    "file_name": { "type": "string" },
    "batch_id": { "type": "string" }
  }
}
```
- Output schema:
```json
{ "id": "string", "status": "queued|processing|completed|failed|cancelled", "total_emails": 0, "processed_count": 0 }
```
- Example request:
```json
{ "emails": ["a@x.com", "b@y.com"], "file_name": "signup-batch-1" }
```
- Example response:
```json
{ "id": "val_123", "status": "queued", "total_emails": 2, "processed_count": 0 }
```
- Common use cases:
- Nightly validation runs
- Lead list scrubbing

#### bulk_email_identity
- Description: Create async identity enrichment job.
- Input schema:
```json
{
  "type": "object",
  "required": ["emails"],
  "properties": {
    "emails": { "type": "array", "items": { "type": "string", "format": "email" }, "minItems": 1, "maxItems": 100000 },
    "file_name": { "type": "string" }
  }
}
```
- Output schema:
```json
{ "id": "string", "status": "queued|processing|completed|failed|cancelled", "found_count": 0 }
```
- Example request:
```json
{ "emails": ["a@x.com", "b@y.com"], "file_name": "identity-run" }
```
- Example response:
```json
{ "id": "iden_123", "status": "queued", "found_count": 0 }
```
- Common use cases:
- Prospect enrichment
- Contact intelligence backfills

#### bulk_password_breaches
- Description: Create async password breach job.
- Input schema:
```json
{
  "type": "object",
  "properties": {
    "sha1s": { "type": "array", "items": { "type": "string", "pattern": "^[A-Fa-f0-9]{40}$" } },
    "passwords": { "type": "array", "items": { "type": "string" } },
    "file_name": { "type": "string" }
  }
}
```
- Output schema:
```json
{ "id": "string", "status": "queued|processing|completed|failed|cancelled", "total": 0, "breached_count": 0 }
```
- Example request (recommended):
```json
{ "sha1s": ["F30AA7A662C728B7407C54AE6BCD56F0DBB3A0F4"], "file_name": "pw-check" }
```
- Example response:
```json
{ "id": "pwd_123", "status": "queued", "total": 1, "breached_count": 0 }
```
- Common use cases:
- Password policy audits
- Exposure checks in security workflows

#### get_email_job_status
- Description: Fetch status and counters for validity/identity/password jobs.
- Input schema:
```json
{
  "type": "object",
  "required": ["job_type", "job_id"],
  "properties": {
    "job_type": { "type": "string", "enum": ["validity", "identity", "password"] },
    "job_id": { "type": "string" }
  }
}
```
- Output schema:
```json
{ "id": "string", "status": "string", "processed_count": 0 }
```
- Example request:
```json
{ "job_type": "validity", "job_id": "val_123" }
```
- Example response:
```json
{ "id": "val_123", "status": "processing", "processed_count": 800, "total_emails": 1200 }
```
- Common use cases:
- Poll loops
- Progress dashboards

#### get_email_job_results
- Description: Paginated job results retrieval.
- Input schema:
```json
{
  "type": "object",
  "required": ["job_type", "job_id"],
  "properties": {
    "job_type": { "type": "string", "enum": ["validity", "identity", "password"] },
    "job_id": { "type": "string" },
    "page": { "type": "integer", "minimum": 1 },
    "page_size": { "type": "integer", "minimum": 1, "maximum": 500 },
    "breached": { "type": "boolean" }
  }
}
```
- Output schema:
```json
{ "items": [], "total": 0, "page": 1, "pages": 1 }
```
- Example request:
```json
{ "job_type": "password", "job_id": "pwd_123", "page": 1, "page_size": 100, "breached": true }
```
- Example response:
```json
{ "items": [{ "line_no": 1, "prefix": "F30AA", "found": true, "count": 42 }], "total": 1, "page": 1, "pages": 1 }
```
- Common use cases:
- Bulk result ingestion
- Paginated processing pipelines

#### download_email_job
- Description: Download CSV payload for a completed job.
- Input schema:
```json
{
  "type": "object",
  "required": ["job_type", "job_id"],
  "properties": {
    "job_type": { "type": "string", "enum": ["validity", "identity", "password"] },
    "job_id": { "type": "string" },
    "breached": { "type": "boolean" }
  }
}
```
- Output schema:
```json
{ "csv": "string" }
```
- Example request:
```json
{ "job_type": "identity", "job_id": "iden_123" }
```
- Example response:
```csv
email,found,name,company
jane@example.com,true,Jane,Acme
```
- Common use cases:
- File export workflows
- BI/reporting ingestion

#### cancel_email_job
- Description: Cancel validity/identity/password job.
- Input schema:
```json
{
  "type": "object",
  "required": ["job_type", "job_id"],
  "properties": {
    "job_type": { "type": "string", "enum": ["validity", "identity", "password"] },
    "job_id": { "type": "string" }
  }
}
```
- Output schema:
```json
{ "cancelled": true }
```
- Example request:
```json
{ "job_type": "password", "job_id": "pwd_123" }
```
- Example response:
```json
{ "cancelled": true }
```
- Common use cases:
- Emergency stop
- Budget enforcement

#### retry_email_job
- Description: Retry dead-lettered chunks for a job.
- Input schema:
```json
{
  "type": "object",
  "required": ["job_type", "job_id"],
  "properties": {
    "job_type": { "type": "string", "enum": ["validity", "identity", "password"] },
    "job_id": { "type": "string" }
  }
}
```
- Output schema:
```json
{ "requeued": 0 }
```
- Example request:
```json
{ "job_type": "validity", "job_id": "val_123" }
```
- Example response:
```json
{ "requeued": 18 }
```
- Common use cases:
- Recover transient failures
- Improve final completion rate

### Account & Credit Tools

Read-only account context. Free — no credits consumed.

- **`whoami()`** — the authenticated account: email, plan, remaining credits, role, and active workspace.
- **`check_credits()`** — just the remaining credit balance, plan, and active workspace.
- **`credit_transactions(limit?)`** — recent credit ledger entries (charges and top-ups).

### API Key Management Tools

Manage the workspace's API keys. The full key is returned **only once**, on creation.

- **`list_api_keys()`** — id, prefix, status, credits used, and limit (never the key value).
- **`create_api_key(name)`** — create a key; the response includes the full `key` one time.
- **`rename_api_key(id, name)`** — rename a key.
- **`set_api_key_status(id, action)`** — `action`: `enable` | `disable`.
- **`revoke_api_key(id, permanent?)`** — disable, or delete permanently with `permanent: true`.
- **`set_api_key_limit(id, credit_limit?)`** — set a credit cap; omit `credit_limit` for unlimited.

### Webhook Tools

Manage event webhooks. The signing secret is returned **only once**, on creation — store it as `ENCRATA_WEBHOOK_SECRET`.

Valid events: `lookup.completed`, `apikey.created`, `apikey.revoked`, `credits.low`, `credits.exhausted`.

- **`list_webhooks()`** — configured endpoints for the current workspace.
- **`create_webhook(url, events[], description?)`** — register an **HTTPS** endpoint; returns the secret once.
- **`update_webhook(id, url?, events?, description?, is_active?)`** — merge-update (only the fields you pass change).
- **`delete_webhook(id)`** — remove an endpoint (stops all deliveries).
- **`test_webhook(id)`** — send a test event; reports the real HTTP result from the endpoint.
- **`webhook_deliveries(webhook_id)`** — recent delivery attempts (event, status, HTTP code, attempts, time).

### Workspace & Member Tools

Manage workspaces and teammates. Member, `update`, and `delete` operations act on the **current** workspace — `switch_workspace` first. Roles: `admin`, `tech`, `readonly`.

- **`list_workspaces()`** — workspaces the account belongs to.
- **`create_workspace(name, slug?, logo_url?)`** — create a workspace (slug auto-generated when omitted).
- **`switch_workspace(workspace_id)`** — set the active workspace.
- **`update_workspace(name, slug?, logo_url?, workspace_id?)`** — update (admin only); `name` required.
- **`delete_workspace()`** — permanently delete the **current** workspace (admin only).
- **`list_workspace_members()`** — members of the current workspace.
- **`invite_workspace_member(email, role)`** — invite a teammate with a role.
- **`set_workspace_member_role(member_id, role)`** — change a member's role.
- **`remove_workspace_member(member_id)`** — remove a member.

## 6) Authentication

### API key example

```bash
export ENCRATA_API_KEY="enc_live_xxx"
```

PowerShell:

```powershell
$env:ENCRATA_API_KEY="enc_live_xxx"
```

### OAuth example

OAuth is not currently supported by this MCP package.

Alternative:
- Issue and rotate API keys from Encrata settings
- Inject keys via secure runtime env vars or secret managers

### Security recommendations

- Do not hardcode keys in source control.
- Use per-environment keys (dev/staging/prod).
- Scope key access to least privilege where available.
- For password breach workflows, prefer `sha1s` over plaintext `passwords`.

### Token rotation

Recommended process:
1. Create a new API key.
2. Update secret store / deployment environment.
3. Restart MCP clients.
4. Revoke old key.

## 7) Example AI Conversations

### lookup_email

User:
```text
Look up jane@acme.com and summarize role, company, and breach risk.
```

Agent tool call:
```json
{ "tool": "lookup_email", "arguments": { "email": "jane@acme.com", "fields": "name,email,company,role,breaches" } }
```

### validate_email

User:
```text
Is ops@company.io deliverable?
```

Agent tool call:
```json
{ "tool": "validate_email", "arguments": { "email": "ops@company.io" } }
```

### check_breaches

User:
```text
Check if security@startup.dev was exposed in breaches.
```

Agent tool call:
```json
{ "tool": "check_breaches", "arguments": { "email": "security@startup.dev" } }
```

### Monitor flow

User:
```text
Create a weekly monitor for these emails and run it now.
```

Agent tool calls:
```json
{ "tool": "create_monitor", "arguments": { "name": "Weekly Watch", "emails": ["a@x.com", "b@y.com"], "frequency": "weekly" } }
```

```json
{ "tool": "trigger_monitor_run", "arguments": { "monitor_id": "mon_123" } }
```

### Contact list flow

User:
```text
Create a contact list named Finance and add two emails.
```

Agent tool calls:
```json
{ "tool": "create_contact_list", "arguments": { "name": "Finance" } }
```

```json
{ "tool": "add_emails_to_list", "arguments": { "list_id": "list_123", "emails": ["cfo@company.com", "controller@company.com"] } }
```

### Bulk validity flow

User:
```text
Validate 50,000 emails and give me CSV when complete.
```

Agent tool calls:
```json
{ "tool": "bulk_validate_emails", "arguments": { "emails": ["a@x.com", "..."], "file_name": "batch-2026-07-28" } }
```

```json
{ "tool": "get_email_job_status", "arguments": { "job_type": "validity", "job_id": "val_123" } }
```

```json
{ "tool": "download_email_job", "arguments": { "job_type": "validity", "job_id": "val_123" } }
```

### Bulk password flow (hash-first)

User:
```text
Check these SHA-1 hashes for breaches and show breached only.
```

Agent tool calls:
```json
{ "tool": "bulk_password_breaches", "arguments": { "sha1s": ["F30AA7A662C728B7407C54AE6BCD56F0DBB3A0F4"] } }
```

```json
{ "tool": "get_email_job_results", "arguments": { "job_type": "password", "job_id": "pwd_123", "breached": true } }
```

## 8) Error Handling

### Authentication errors

Typical signals:
- Missing `ENCRATA_API_KEY`
- HTTP 401/403 from upstream API

Fixes:
- Verify key exists in client config env block
- Verify key validity and scope

### Rate limiting

Behavior:
- Upstream API may return HTTP 429
- Client retries automatically up to 3 attempts

Fixes:
- Backoff and retry
- Reduce request bursts
- Batch work through async jobs

### Invalid parameters

Typical cases:
- Invalid email format
- Missing required fields
- Unsupported enum values

Fixes:
- Validate payload before tool call
- Use schemas in this README as source of truth

### Server errors

Typical cases:
- HTTP 5xx or transient network failures

Fixes:
- Retry with jitter
- Use `retry_email_job` for dead-letter chunks
- Inspect status with `get_email_job_status`

### Troubleshooting guide

1. Run `npx -y encrata-mcp --help` to verify binary executes.
2. Confirm `ENCRATA_API_KEY` is present in your MCP client config.
3. If using custom base URL, verify `ENCRATA_BASE_URL` is reachable.
4. Start with `validate_email` on one known address.
5. For bulk workflows, verify status before fetching results.

## 9) Best Practices

### Security

- Store keys in secret managers, not plaintext config repos.
- Use separate keys per environment.
- Prefer SHA-1 hashes for password breach jobs.

### Performance

- Use async bulk tools for large lists.
- Poll status at reasonable intervals (for example every 5 to 20 seconds).
- Fetch paginated results incrementally.

### Rate limits

- Expect occasional 429 under load.
- Let retries handle transient limits, then backoff.

### Caching

- Cache stable enrichment results where policy allows.
- Avoid repeated lookups for unchanged identities.

### Production deployment recommendations

- Pin Node.js runtime version in CI/CD.
- Add health checks around MCP process startup.
- Centralize logs for error and latency monitoring.
- Rotate API keys regularly.

## 10) FAQ

### Does this server support HTTP MCP transport?
This package currently exposes MCP stdio transport. It still talks to Encrata over REST HTTP internally.

### Can I use this with ChatGPT?
Yes, where ChatGPT Desktop MCP server integration is available in your app/account rollout.

### Do I need OAuth?
No. This integration uses API keys.

### How do I run large jobs safely?
Use bulk tools, poll status, then download CSV.

### Are plaintext passwords required?
No. Use `sha1s` with `bulk_password_breaches` for hash-first workflows.

## 11) Complete Copy-Paste Examples

### Claude Desktop

```json
{
  "mcpServers": {
    "encrata": {
      "command": "npx",
      "args": ["-y", "encrata-mcp"],
      "env": {
        "ENCRATA_API_KEY": "your-api-key",
        "ENCRATA_BASE_URL": "https://encrata.com"
      }
    }
  }
}
```

### Claude Code

```bash
claude mcp add encrata -- npx -y encrata-mcp
export ENCRATA_API_KEY="your-api-key"
export ENCRATA_BASE_URL="https://encrata.com"
```

### Cursor

```json
{
  "mcpServers": {
    "encrata": {
      "command": "npx",
      "args": ["-y", "encrata-mcp"],
      "env": {
        "ENCRATA_API_KEY": "your-api-key",
        "ENCRATA_BASE_URL": "https://encrata.com"
      }
    }
  }
}
```

### VS Code / GitHub Copilot

```json
{
  "servers": {
    "encrata": {
      "command": "npx",
      "args": ["-y", "encrata-mcp"],
      "env": {
        "ENCRATA_API_KEY": "your-api-key",
        "ENCRATA_BASE_URL": "https://encrata.com"
      }
    }
  }
}
```

### ChatGPT Desktop

```text
Name: Encrata
Command: npx -y encrata-mcp
Environment:
  ENCRATA_API_KEY=your-api-key
  ENCRATA_BASE_URL=https://encrata.com
```

### Windsurf

```json
{
  "mcpServers": {
    "encrata": {
      "command": "npx",
      "args": ["-y", "encrata-mcp"],
      "env": {
        "ENCRATA_API_KEY": "your-api-key",
        "ENCRATA_BASE_URL": "https://encrata.com"
      }
    }
  }
}
```

## Local Development

```bash
npm ci
npm run build
npm test
npm pack --dry-run
```

## License

MIT