`search_entities`

Pack: open-sanctions · Endpoint: https://gateway.pipeworx.io/open-sanctions/mcp

No MCP client? Call it directly: GET https://gateway.pipeworx.io/v1/tools/search_entities for the schema, then POST the same URL with its arguments for the data.

Search global sanctions, watchlists, and PEP (politically exposed persons) databases. Returns matched entities with names, countries, datasets, and sanctions details. Example: search_entities(“Vladimir Putin”) or search_entities(“Huawei”, schema=“Company”). Requires your own OpenSanctions API key, passed as _apiKey.

Parameters

Name	Type	Required	Description
`query`	string	yes	Name or keyword to search (e.g., “Gazprom”, “Kim Jong”)
`schema`	string	no	Entity type: “Person”, “Company”, “Organization”, “Vessel”, “Aircraft”
`countries`	string	no	Comma-separated country codes (e.g., “ru,cn,ir”)
`_apiKey`	string	yes	Your own OpenSanctions API key (BYO — Pipeworx does not supply one; OpenSanctions is a commercial service). Get one at opensanctions.org/api — free for non-commercial use, paid for commercial. For a keyless US sanctions/export-control screen, use the sanctions-screening pack (sanctions_screen) instead.

Example call

Arguments

{
  "_apiKey": "your-opensanctions-api-key",
  "query": "Gazprom"
}

curl

curl -X POST https://gateway.pipeworx.io/open-sanctions/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_entities","arguments":{"_apiKey":"your-opensanctions-api-key","query":"Gazprom"}}}'

TypeScript (@pipeworx/sdk)

import { Pipeworx } from '@pipeworx/sdk';
const pipeworx = new Pipeworx();

const result = await pipeworx.call('search_entities', {
  "_apiKey": "your-opensanctions-api-key",
  "query": "Gazprom"
});

More examples

{
  "_apiKey": "your-opensanctions-api-key",
  "query": "Kim Jong",
  "schema": "Person",
  "countries": "kp"
}

Response shape

Always returns: query, total, returned, entities

Field	Type	Description
`query`	string	The search query string provided
`total`	number	Total number of matching entities
`returned`	number	Number of entities in this response
`entities`	array	Formatted entity objects

Full JSON Schema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "The search query string provided"
    },
    "total": {
      "type": "number",
      "description": "Total number of matching entities"
    },
    "returned": {
      "type": "number",
      "description": "Number of entities in this response"
    },
    "entities": {
      "type": "array",
      "description": "Formatted entity objects",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": [
              "string",
              "null"
            ],
            "description": "OpenSanctions entity ID"
          },
          "caption": {
            "type": [
              "string",
              "null"
            ],
            "description": "Entity display name"
          },
          "schema": {
            "type": [
              "string",
              "null"
            ],
            "description": "Entity type (Person, Company, Organization, Vessel, Aircraft)"
          },
          "datasets": {
            "type": "array",
            "description": "Datasets this entity appears in",
            "items": {
              "type": "string"
            }
          },
          "target": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "Whether entity is a sanctions target"
          },
          "score": {
            "type": [
              "number",
              "null"
            ],
            "description": "Search relevance score"
          },
          "first_seen": {
            "type": [
              "string",
              "null"
            ],
            "description": "Date entity first appeared"
          },
          "last_seen": {
            "type": [
              "string",
              "null"
            ],
            "description": "Date entity last appeared"
          },
          "last_change": {
            "type": [
              "string",
              "null"
            ],
            "description": "Date of last data change"
          },
          "names": {
            "type": "array",
            "description": "Known names for this entity",
            "items": {
              "type": "string"
            }
          },
          "countries": {
            "type": "array",
            "description": "Associated country codes",
            "items": {
              "type": "string"
            }
          },
          "birth_date": {
            "type": [
              "string",
              "null"
            ],
            "description": "Birth date if Person"
          },
          "nationality": {
            "type": "array",
            "description": "Nationalities",
            "items": {
              "type": "string"
            }
          },
          "topics": {
            "type": "array",
            "description": "Associated topics/categories",
            "items": {
              "type": "string"
            }
          },
          "position": {
            "type": [
              "string",
              "null"
            ],
            "description": "Position held if applicable"
          },
          "notes": {
            "type": "array",
            "description": "Additional notes about entity",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "id",
          "caption",
          "schema",
          "datasets",
          "target",
          "score",
          "first_seen",
          "last_seen",
          "last_change",
          "names",
          "countries",
          "birth_date",
          "nationality",
          "topics",
          "position",
          "notes"
        ]
      }
    }
  },
  "required": [
    "query",
    "total",
    "returned",
    "entities"
  ]
}

Connect

Add this to your MCP client config, or use one-click install buttons:

{
  "mcpServers": {
    "open-sanctions": {
      "url": "https://gateway.pipeworx.io/open-sanctions/mcp"
    }
  }
}

See Getting Started for client-specific install steps.

search_entities