Open Data DictionaryOpen Data Dictionary

API Reference

Available tools provided by the Open Data Dictionary MCP server.

The Open Data Dictionary MCP server provides 7 tools for querying and validating data terminology. All requests require a valid API token passed via Authorization: Bearer header.

search_words

Search for words in the dictionary by keyword. Searches both word names and definitions.

Parameters

query string (required) Search query — matches against word name and definition.

limit number (optional) Max results to return. Default: 10, max: 50.

offset number (optional) Number of results to skip for pagination. Default: 0.

Example Request

curl -X POST https://opendatadictionary.com/api/v1/mcp \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "search_words",
      "arguments": { "query": "customer", "limit": 5 }
    }
  }'

Response

{
  "results": [
    {
      "word": "customer_id",
      "definition": "Unique identifier for a customer record",
      "dataType": "STRING",
      "categories": ["generic"],
      "status": "approved"
    }
  ],
  "count": 1,
  "total": 3,
  "offset": 0,
  "has_more": true,
  "next_offset": 1
}

get_word

Get detailed information about a specific word by its exact name.

Parameters

word string (required) Exact word name to look up.

Example Request

curl -X POST https://opendatadictionary.com/api/v1/mcp \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "get_word",
      "arguments": { "word": "revenue" }
    }
  }'

Response

{
  "word": "revenue",
  "definition": "Total income generated from sales before any deductions",
  "dataType": "DECIMAL",
  "categories": ["financial-services"],
  "synonyms": ["income", "sales"],
  "status": "approved",
  "createdAt": "2024-01-15T10:30:00Z"
}

list_categories

List all available categories in the Open Data Dictionary.

Parameters

This tool takes no parameters.

Example Request

curl -X POST https://opendatadictionary.com/api/v1/mcp \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "list_categories",
      "arguments": {}
    }
  }'

Response

{
  "categories": [
    { "id": "generic", "name": "Generic" },
    { "id": "financial-services", "name": "Financial Services" },
    { "id": "technology-information-media", "name": "Technology, Information & Media" }
  ],
  "count": 21
}

get_synonyms

Get synonyms for a specific word in the dictionary.

Parameters

word string (required) Word to get synonyms for.

Example Request

curl -X POST https://opendatadictionary.com/api/v1/mcp \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "get_synonyms",
      "arguments": { "word": "customer" }
    }
  }'

Response

{
  "word": "customer",
  "synonyms": [
    {
      "word": "client",
      "definition": "A person or organization using services",
      "dataType": "STRING"
    }
  ],
  "count": 1
}

get_schema

Get the database schema for the words table. Useful for understanding column names and types when building queries.

Parameters

This tool takes no parameters.

Example Request

curl -X POST https://opendatadictionary.com/api/v1/mcp \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "get_schema",
      "arguments": {}
    }
  }'

Response

{
  "table": "words",
  "description": "Open Data Dictionary words table containing standardized data terminology",
  "columns": [
    { "name": "id", "type": "bigint", "description": "Unique identifier (primary key)" },
    { "name": "word", "type": "varchar(255)", "description": "The dictionary word/term" },
    { "name": "definition", "type": "text", "description": "Definition/description of the word" },
    { "name": "data_type", "type": "varchar(50)", "description": "Recommended data type (e.g., STRING, INTEGER, BOOLEAN)" },
    { "name": "categories", "type": "text[]", "description": "Array of category slugs" },
    { "name": "status", "type": "text", "description": "Word status: approved, pending, or rejected" },
    { "name": "created_at", "type": "timestamptz", "description": "When the word was created" },
    { "name": "updated_at", "type": "timestamptz", "description": "When the word was last updated" },
    { "name": "created_by", "type": "text", "description": "Email of the user who created the word" }
  ]
}

Common Mistake

The column is categories (plural array), not category (singular).

validate_columns

Validate a list of column names against data dictionary standards and naming conventions. Useful for DBT model development and Postgres schema design.

Checks for: snake_case format, abbreviations (e.g., amt → amount), generic names, timestamp/boolean/date suffixes, and dictionary matches.

Parameters

columns string[] (required) Array of column names to validate.

check_dictionary boolean (optional) Whether to look up columns in the data dictionary. Default: true.

Example Request

curl -X POST https://opendatadictionary.com/api/v1/mcp \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "validate_columns",
      "arguments": {
        "columns": ["customer_id", "orderId", "amt"]
      }
    }
  }'

Response

{
  "valid": false,
  "columns": [
    {
      "column": "customer_id",
      "valid": true,
      "issues": [],
      "dictionaryMatch": {
        "word": "customer_id",
        "definition": "Unique identifier for a customer record",
        "dataType": "STRING"
      }
    },
    {
      "column": "orderId",
      "valid": false,
      "issues": [
        {
          "type": "error",
          "code": "CAMEL_CASE",
          "message": "Column name uses camelCase instead of snake_case",
          "suggestion": "order_id"
        }
      ]
    },
    {
      "column": "amt",
      "valid": true,
      "issues": [
        {
          "type": "warning",
          "code": "ABBREVIATION",
          "message": "Column name contains abbreviation(s): 'amt' → 'amount'",
          "suggestion": "amount"
        }
      ]
    }
  ],
  "summary": {
    "total": 3,
    "valid": 2,
    "invalid": 1,
    "warnings": 1
  }
}

suggest_column_name

Suggest a standardized column name based on a plain-text description. Returns a suggested name, alternatives, recommended data type, and a ready-to-paste DBT schema YAML snippet.

Parameters

description string (required) Plain-text description of what the column represents.

check_dictionary boolean (optional) Whether to search the dictionary for matching terms. Default: true.

Example Request

curl -X POST https://opendatadictionary.com/api/v1/mcp \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "suggest_column_name",
      "arguments": {
        "description": "unique identifier for a customer"
      }
    }
  }'

Response

{
  "suggestion": {
    "suggestedName": "customer_id",
    "alternativeNames": ["id", "customer_identifier"],
    "dataType": "string",
    "reasoning": "Identifiers should follow <entity>_id pattern",
    "namingPattern": "identifier",
    "description": "unique identifier for a customer"
  },
  "dictionaryMatches": [
    {
      "word": "customer_id",
      "definition": "Unique identifier for a customer record",
      "dataType": "STRING"
    }
  ],
  "usage": {
    "dbt_schema_yml": "      - name: customer_id\n        description: \"unique identifier for a customer\"\n        data_type: string"
  }
}

Error Responses

All errors return a JSON object with an error field.

401 Unauthorized

Returned when the API token is missing, invalid, or expired.

{
  "error": "Invalid or expired API token"
}

429 Too Many Requests

Returned when you've exceeded your daily rate limit. Includes Retry-After and X-RateLimit-Reset headers.

{
  "error": "Rate limit exceeded. Resets at midnight UTC."
}

404 Not Found

Returned by get_word when the requested word doesn't exist or isn't approved.

{
  "error": "Word not found"
}

Direct REST API

You can also query the dictionary directly via REST without MCP:

# Search for words
curl "https://opendatadictionary.com/api/words?query=customer&limit=5" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
 
# Get a specific word
curl "https://opendatadictionary.com/api/words?query=customer_id&limit=1" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Previous

Cursor IDE Setup

Next

Rate Limits

On this page