{
  "openapi": "3.0.0",
  "info": {
    "version": "1",
    "title": "CDQ MCP",
    "description": "The CDQ MCP server gives AI assistants and agents access to CDQ business partner data through the Model Context Protocol. Any MCP-compatible client can connect to it to look up business partners by company name, address and identifiers. Tool names are grouped by product area with the prefix `reference_data-`. Every tool runs on behalf of the authenticated user, so results are always scoped to that user's own organization and workspace."
  },
  "servers": [
    {
      "description": "Production",
      "url": "https://api.cdq.com/mcp"
    }
  ],
  "paths": {},
  "security": [
    {
      "apiKey": []
    }
  ],
  "x-mcp": {
    "protocolVersion": "2025-06-18",
    "servers": [
      {
        "url": "https://api.cdq.com/mcp"
      }
    ],
    "capabilities": {
      "tools": {
        "listChanged": true
      }
    },
    "tools": [
      {
        "name": "reference_data-lookup_business_partners",
        "title": "Lookup business partners",
        "tags": [
          "Reference Data"
        ],
        "description": "**When:** the user wants to find candidate business partners by any combination of company name, address parts and identifiers (VAT, PL_REG, etc.) — including by an identifier alone.\n\n**What it returns:** a paginated list of slim matches. Each match carries:\n\n- `cdqId`, local-language name, a composed address string and external id\n- identifiers (VAT, PL_REG, ...) as `{value, type}` pairs\n- status and source-of-record identity (`technicalKey` + name)\n- a matching score\n\nIt may also return **warnings**: notices the search made about itself, each with a severity and a plain-language message, most often saying that some of the data the search was asked to cover is not enabled for the caller's organization. A warning qualifies the result and never means the search failed — relay it to the user when it explains a short or empty list of matches, along with whatever its message asks them to do.\n\n**What it does not do:**\n\n- It does **not** query Dun & Bradstreet or Bureau van Dijk, so it cannot answer a request for a DUNS number or a BvD ID.\n- It does **not** return full business partner details (no bank accounts, relations, classifications, raw SAP record, etc.), only the slim matches above.\n",
        "inputSchema": {
          "$ref": "#/components/schemas/BusinessPartnerLookupRequest"
        },
        "outputSchema": {
          "$ref": "#/components/schemas/BusinessPartnerLookupResult"
        },
        "security": [
          {
            "OAuth2": []
          }
        ]
      }
    ],
    "resources": []
  },
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-KEY"
      }
    },
    "schemas": {
      "BusinessPartnerLookupRequest": {
        "type": "object",
        "description": "Business partner lookup criteria. Requires companyName or identifiers; the address elements only narrow the search and cannot be one on their own.",
        "properties": {
          "companyName": {
            "type": "string",
            "description": "The legal or trading name of the company to look up, e.g. \"REFRIGERACAO DUFRIO COMERCIAL LTDA\"."
          },
          "countryCode": {
            "type": "string",
            "description": "ISO 3166-1 alpha-2 country code, e.g. \"PL\"."
          },
          "street": {
            "type": "string",
            "description": "Street address (street name plus number if known), e.g. \"al. Jana Pawła II 6\"."
          },
          "city": {
            "type": "string",
            "description": "City name, e.g. \"Jawor\"."
          },
          "postCode": {
            "type": "string",
            "description": "Postal code, e.g. \"59-400\"."
          },
          "identifiers": {
            "type": "array",
            "description": "Identifying numbers (VAT, PL_REG, DUNS, etc.), e.g. [{\"value\":\"1234567890\",\"type\":\"PL_NIP\"}].",
            "items": {
              "$ref": "#/components/schemas/IdentifierParam"
            }
          },
          "dataSources": {
            "type": "array",
            "description": "Restrict the search to specific data sources, given as ALEI prefixes, e.g. [\"BR.RF\"] or [\"PL.NOBR\",\"BR.RF\"]. An ALEI prefix is the part of a cdqId before the colon: a match with cdqId \"BR.RF:01754239004298\" comes from the \"BR.RF\" data source, so a prefix can be read off any earlier result. Omit this to search every data source the caller can access.",
            "items": {
              "type": "string"
            }
          },
          "startAfter": {
            "type": "string",
            "description": "Pagination cursor. Omit for the first page; pass the nextStartAfter value from the previous result to fetch the next page."
          },
          "limit": {
            "type": "integer",
            "format": "int32",
            "description": "Items per page, e.g. 5. Allowed range 1..50; defaults to 5 to keep response tokens small.",
            "minimum": 1,
            "maximum": 50,
            "default": 5
          }
        }
      },
      "IdentifierParam": {
        "type": "object",
        "required": [
          "value"
        ],
        "properties": {
          "value": {
            "type": "string",
            "description": "The identifier value, e.g. \"1234567890\"."
          },
          "type": {
            "type": "string",
            "description": "Identifier type technicalKey, e.g. \"PL_NIP\", \"PL_REG\", \"DUNS\". Omit it to search the value across all types; never ask the user for one."
          }
        }
      },
      "BusinessPartnerLookupResult": {
        "type": "object",
        "properties": {
          "matches": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BusinessPartnerLookupMatch"
            }
          },
          "limit": {
            "type": "integer"
          },
          "totalMatches": {
            "type": "integer"
          },
          "nextStartAfter": {
            "type": "string",
            "description": "Cursor for the next page; pass it as startAfter."
          },
          "warnings": {
            "type": "array",
            "nullable": true,
            "items": {
              "$ref": "#/components/schemas/LookupWarning"
            }
          }
        }
      },
      "LookupWarning": {
        "type": "object",
        "properties": {
          "severity": {
            "type": "string",
            "example": "warning"
          },
          "message": {
            "type": "string",
            "example": "CREFO.SSU: There is no more quota left for this data source."
          }
        }
      },
      "BusinessPartnerLookupMatch": {
        "type": "object",
        "properties": {
          "cdqId": {
            "type": "string",
            "example": "CH.CR:1206654L"
          },
          "nameLocal": {
            "type": "string",
            "example": "CDQ AG"
          },
          "addressString": {
            "type": "string",
            "example": "Switzerland, St. Gallen, Lukasstrasse 4"
          },
          "externalId": {
            "type": "string",
            "example": "1206654"
          },
          "identifiers": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Identifier"
            }
          },
          "status": {
            "type": "string",
            "example": "Active"
          },
          "lastSyncDate": {
            "type": "string"
          },
          "dataSourceTechnicalKey": {
            "type": "string",
            "example": "CH.CR"
          },
          "dataSourceName": {
            "type": "string",
            "example": "Swiss commercial register"
          },
          "matchingScore": {
            "type": "number",
            "format": "double",
            "minimum": 0,
            "maximum": 1
          }
        }
      },
      "Identifier": {
        "type": "object",
        "properties": {
          "value": {
            "type": "string",
            "example": "CHE218608886"
          },
          "type": {
            "type": "string",
            "example": "CH_UID"
          }
        }
      }
    }
  }
}