dehashed-mcp

An MCP (Model Context Protocol) server that wraps the DeHashed breach-data API and exposes every available endpoint as an MCP tool — with server-side API key management, structured Docker logging, and a pluggable RBAC/ABAC authorization engine that enforces access control at the individual tool call level.

Key design decisions

| Concern | Decision | |---|---| | API key | Held exclusively in the server process (env var). Never passed to or returned by any tool. | | Transport | Not decided here — wire stdio, HTTP/SSE, or a gRPC proxy on top. | | MCP auth | Not decided here — add bearer token / OAuth / mTLS at the transport layer. | | Tool-level authz | RBAC + ABAC via a hot-reloadable YAML policy file. Per-tool, per-tenant, per-domain-scope, per-page-size. | | Logging | structlog → JSON → stdout/stderr → docker logs / any log driver. |

Project layout

dehashed-mcp/
├── src/dehashed_mcp/
│   ├── __init__.py
│   ├── main.py            # FastMCP app + entrypoint
│   ├── config.py          # Pydantic Settings (reads env vars)
│   ├── client.py          # Async DeHashed HTTP client
│   ├── models.py          # Request/response Pydantic models
│   ├── tools.py           # All 17 MCP tool definitions
│   ├── authz.py           # RBAC/ABAC engine
│   └── logging_config.py  # structlog → Docker logs
├── config/
│   └── policy.yaml        # Default authorization policy
├── tests/
│   ├── conftest.py
│   ├── test_authz.py
│   ├── test_client.py
│   └── test_models.py
├── Dockerfile
├── docker-compose.yml
├── docker-entrypoint.sh
├── pyproject.toml
└── .env.example

Quick start

1. Configure

cp .env.example .env
# Edit .env — set DEHASHED_API_KEY at minimum

2. Build and run (stdio — Claude Desktop / any MCP host)

docker compose build
docker compose run --rm -i dehashed-mcp

3. Run with HTTP/SSE transport

MCP_TRANSPORT=http docker compose up
# Server listens on http://localhost:8000

4. View logs

docker logs -f dehashed-mcp
# Output is newline-delimited JSON

Environment variables

| Variable | Required | Default | Description | |---|---|---|---| | DEHASHED_API_KEY | yes | — | Your DeHashed API key | | DEHASHED_EMAIL | only for v1 | — | Account email (V1 Basic Auth only) | | DEHASHED_AUTH_MODE | no | v2_key | v2_key or v1_basic | | DEHASHED_BASE_URL | no | https://api.dehashed.com | API base URL | | LOG_LEVEL | no | INFO | DEBUG / INFO / WARNING / ERROR | | MCP_TRANSPORT | no | stdio | stdio or http | | PORT | no | 8000 | HTTP listen port (http transport only) | | AUTHZ_POLICY_PATH | no | /config/policy.yaml | Path to policy file | | AUTHZ_STRICT_TENANT | no | true | Reject unknown tenants when true |

Available tools (17)

| Tool | Description | Tags | |---|---|---| | search | Raw query string search | read, raw_query | | search_by_field | Field + value + match mode | read | | search_email | Email exact search | read | | search_username | Username contains search | read | | search_password | Plaintext password exact search | read, sensitive | | search_hashed_password | Hash exact search | read, sensitive | | search_ip | IP address exact search | read | | search_name | Name contains search | read | | search_vin | VIN exact search | read | | search_address | Address contains search | read | | search_phone | Phone contains search | read | | search_domain | Domain contains search | read | | search_database | Breach/database name search | read | | search_license_plate | License plate exact search | read | | search_crypto_address | Cryptocurrency address exact search | read | | get_balance | Retrieve remaining API credits | read, account | | paginate_all | Auto-paginate and aggregate | read, bulk, raw_query |

Query match modes (search_by_field, search)

| Mode | Syntax | Notes | |---|---|---| | contains | field:value | Default loose match | | exact | field:"value" | Quoted exact match | | regex | field:/pattern/ | ⚠ Reported broken in V2 (May 2025) | | wildcard | field:"val*ue" | ? = single char, * = multi ⚠ May be broken in V2 |

Authorization — RBAC/ABAC policy

Tool-level authorization is enforced before any DeHashed API call. The policy is a YAML file (config/policy.yaml) that can be hot-mounted into the container.

Policy structure

tenants:
  <tenant_id>:
    roles:
      <role_name>:
        allow: [<tool_name>, ...]   # or ["*"] for all tools
        deny:  [<tool_name>, ...]   # always wins over allow
        resource_scopes:
          domains: [acme.com, ...]  # restrict domain/email tools
    attributes:
      max_page_size: 500            # cap the `size` param
      max_pages: 3                  # cap paginate_all max_pages

default:                            # fallback (strict_tenant=false only)
  roles: ...

CallerContext injection

The MCP metadata dict passed with each tool call is the contract between your transport/auth layer and the authz engine:

# What your transport layer injects into _meta:
{
    "tenant": "acme",
    "roles": ["analyst"],
    "attributes": {}   # optional per-call ABAC overrides
}

At the transport layer (bearer token, OAuth, mTLS, API key validation), you decode the identity and populate this dict before the tool handler runs. The server enforces it on every call.

Hot-reload policy

Send SIGUSR1 or call authz.get_policy().reload() to reload the policy file without restarting the server.

Transport configuration

This server is transport-agnostic. Choose your transport at deploy time:

stdio (default)

Best for Claude Desktop integration:

{
  "mcpServers": {
    "dehashed": {
      "command": "docker",
      "args": ["run", "--rm", "-i",
               "-e", "DEHASHED_API_KEY=xxx",
               "dehashed-mcp:latest"]
    }
  }
}

HTTP / SSE

Run with MCP_TRANSPORT=http. The FastMCP app is also exported as an ASGI app object for direct uvicorn/gunicorn use:

uvicorn dehashed_mcp.main:app --host 0.0.0.0 --port 8000

Add your auth middleware (bearer token validation, OAuth introspection, etc.) as ASGI middleware on top.

gRPC

Put a gRPC-to-HTTP/2 transcoding proxy (e.g., Envoy, grpc-gateway) in front of the HTTP transport.

Development

# Install with dev extras
pip install -e ".[dev,http]"

# Run tests
pytest

# Lint
ruff check src tests
black --check src tests
mypy src

Logging

All log output is newline-delimited JSON sent to stdout. Docker captures it via the configured log driver (json-file by default in docker-compose.yml).

docker logs dehashed-mcp | jq .

Example log line:

{
  "event": "dehashed.search.ok",
  "total": 42,
  "returned": 100,
  "balance": 95,
  "service": "dehashed-mcp",
  "version": "0.1.0",
  "level": "info",
  "timestamp": "2025-03-09T12:00:00.000Z"
}

API keys, passwords, and tokens are automatically redacted from all log lines by the _redact_api_key processor in logging_config.py.

Credits and depletion

Each tool call that hits the DeHashed API costs 1 credit. paginate_all costs 1 credit per page. Monitor balance via get_balance or by watching the balance field in search results logged at INFO level. Policy max_pages attributes help prevent runaway credit consumption.

License

MIT