Documentation / MCP / taxonomy_categories

taxonomy_categories

POSThttps://mcp.oppalerts.com/mcptool: taxonomy_categories

The categories of one taxonomy: the id, the name, and the depth of each category, sorted by name.

What it does

You send the name of one taxonomy. The tool returns the categories of that taxonomy: the category_id, the name, and the depth of each category, sorted by name. These are the categories that the category picker of the Content Optimizer shows. To find categories by their names, also send query.

Use a category_id as a target of taxonomy_semantic_content_analyzer, or in a preset of campaigns_set_taxonomy_presets. taxonomy_taxonomies gives the names of the taxonomies.

Connect

claude mcp add --transport http oppalerts https://mcp.oppalerts.com/mcp

The first call opens a browser window for the OppAlerts login. Connect an AI Agent has the details.

Parameters

taxonomystring, required, at most 100 characters
One taxonomy name, as taxonomy_taxonomies answers it, at most 100 characters. A name that is not in that list is refused.
results_limitint, optional, 1 to 10000
The maximum number of categories to return, a whole number from 1 to 10,000. Not sent: 100. The categories are sorted by name, and the answer holds the first results_limit of them.
querystring, optional, at most 200 characters
Words to find in the category names, at most 200 characters. The words are split at the spaces. A category is returned only when its name contains every word. A word can be a part of a longer word: hotel finds Hotels and Motels. Upper case and lower case letters A to Z are the same, and every other character must be the same. Not sent: every category of the taxonomy.

Strict Rules

  • A field that is not in the list above is refused. The result then has isError true, and its text starts with bad_param. The error names the field: "<field> is not a field of this tool." The old name of a renamed field is refused in the same way.
  • A bad value is refused, and the error names the field. A bad value is a value of the wrong type, a number with a fraction for a whole-number field, a value out of its range, or a value that is not in its list. A required field that you do not send is refused too. The tool never changes a value that you send.
  • An error about the format of a call, such as a refused field, names the field. Its message ends with one sentence: "Read the documentation at https://oppalerts.com/docs for the correct format." Every other error has only its own sentence.

How query finds a category

  • The tool splits query into words at the spaces.
  • A category is in the response only when its name contains every word.
  • A word can be a part of a longer word: hotel finds "Hotels and Motels".
  • Upper case and lower case letters A to Z are the same. Every other character must match exactly, including accented letters.
  • The order does not change: the categories are sorted by name, and the answer holds the first results_limit of the categories that match.

Response

The answer has three fields:

taxonomystring
The taxonomy that you sent.
totalint
The number of categories that match query, or of all categories of the taxonomy when you do not send query.
returnedint
The number of categories in categories, in this answer. When total is more than returned, send a higher results_limit or more words in query.
categorieslist
The categories, sorted by name. Each entry has three fields:
category_idint
The id of the category. Send it as a target of taxonomy_semantic_content_analyzer, or as the category_id of a taxonomy preset.
category_labelstring
The name of the category, with its path, for example "Travel > Travel Type > Hotels and Motels".
depthint
The level of the category in its taxonomy. 1 is the top level.

Example

Call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "taxonomy_categories",
    "arguments": {
      "taxonomy": "iab-content-taxonomy",
      "results_limit": 10000,
      "query": "hotel"
    }
  }
}

Response

{
  "taxonomy": "iab-content-taxonomy",
  "total": 2,
  "returned": 2,
  "categories": [
    {
      "category_id": 289090960918637,
      "category_label": "Real Estate > Hotel Properties",
      "depth": 2
    },
    {
      "category_id": 2358064203319202,
      "category_label": "Travel > Travel Type > Hotels and Motels",
      "depth": 3
    }
  ]
}

Errors

An error returns as a tool result with isError true. Its text starts with the error code, except for daily_limit, whose text is only the sentence. The HTTP status shown for each code is its API status.

  • bad_param (HTTP 400 in the API): a field is not a field of this tool, a required field is not sent, a value has the wrong type or is out of its range, query is empty or holds no word, or taxonomy is not a taxonomy name. The error names the field. taxonomy_taxonomies names every taxonomy.
  • backend_error (HTTP 502 in the API): the taxonomy server did not answer. Try again in a few minutes.
  • daily_limit (HTTP 429 in the API): the account has used all its calls for this tool today. account_calls_left shows when the count resets.

This tool has its own daily count. Calls through the API, MCP, and the web app use this count. It is not an index search, so it does not use the shared count of the news_ and prospects_ tools, and the error one_at_a_time does not apply to it.

Same data in the API

POST /v1/taxonomy/categories HTTP/1.1
Host: api.oppalerts.com
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{"taxonomy": "iab-content-taxonomy", "results_limit": 10000, "query": "hotel"}

See POST /v1/taxonomy/categories.