Skip to content
Last updated

MCP tools

The project adds custom tools to Redocly's built-in documentation MCP server. They are documentation-only: each returns a DataSift API operation's documented method, path, parameters, and response shape. They do not call the DataSift backend or return customer records.

Read-only reference tools

MCP toolDataSift operationMethod and path
search-propertiesautocompletePropertyElasticGET /api/internal/property/autocomplete/
get-propertyretrievePropertyGET /api/internal/property/{uuid}/
get-property-historylogsLogElasticGET /api/internal/property/{uuid}/logs/
get-ownerretrieveOwnerGET /api/internal/owner/{uuid}/
get-owner-phonesretrieveOwnerGET /api/internal/owner/{uuid}/
list-phone-tagslistPhoneTagsGET /api/internal/phone/tag/
list-custom-fieldslistCustomFieldsGET /api/internal/custom-fields/
get-property-custom-fieldslistCustomFieldValuesGET /api/internal/property/{property_uuid}/custom-field/
list-taskslistTasksGET /api/internal/task/
get-taskretrieveTaskGET /api/internal/task/{uuid}/
list-task-presetslistTaskPresetsGET /api/internal/task-preset/
list-tagslistTagsGET /api/internal/tag/
list-listslistListsGET /api/internal/list/
get-activity-statuslistActivitiesGET /api/internal/activity/

These are custom tools with the given names; none collide with Redocly's built-in tool names. The local @redocly/framework@0.140.0 preview listed and allowed direct calls to all 14 tools both at /mcp and at /mcp?mode=tools. Redocly can select a code-mode interface on eligible plans, where custom tools are called through execute and described with describe-tools; verify the mode available on the connected project after synchronization.

API contract limitations

  • The OpenAPI operation for property autocomplete declares no query parameters. The use-case playbook shows search, but it is not represented in that operation's OpenAPI schema. No sorting or pagination is documented for autocomplete.
  • The property collection operation (listProperties, GET /api/internal/property/) documents limit and offset only. It has no documented search/filter/order parameters, so the existing API description does not support a fully filterable, sortable property search tool.
  • list-tasks documents limit and offset only; no task filters are declared in the API schema.
  • Owner phone details are embedded in the Owner response (phones, total_phones, primary_phone); the API has no separate GET owner-phones operation. The documented Phone fields include number, type, tags, status, and is_connected.
  • get-activity-status describes the paginated activity feed and its status/progress fields. There is no documented GET operation for a single activity by UUID.
  • Results identify the API response schema but are not returned by these tools. Each output explicitly says documentation-only and liveDataReturned: false.

Authentication and executable API calls

DataSift requests require a customer-specific Open API key in Authorization: Api-Key .... Redocly MCP authentication identifies a Redocly documentation user; its token is not a DataSift key and does not authorize API calls. The Enterprise code-mode preview also exposes Redocly's separate manageApiCredentials and OpenAPI-aware fetch tools, which accept a security-scheme name and restrict calls to documented read methods. That is a built-in API-call path, not an API-credential interface available to custom handlers: Redocly's documented McpToolContext exposes no managed DataSift credential or credential-aware fetch method. This repository has no customer-scoped exchange or backend credential integration for custom handlers. Therefore no custom tool accepts, stores, forwards, or returns credentials, and no custom tool makes a live DataSift request. Redocly plan entitlement and code-mode execution must be verified for the deployed legacy project before relying on its separate built-in API-call path.

The following requested write operations are intentionally not executable:

Proposed operationDocumented DataSift routeState
apply-property-tagsPOST /api/internal/property/{uuid}/add-tags/Disabled until customer-scoped authentication, authorization, duplicate-request controls, and audit handling are implemented.
update-property-custom-fieldsPATCH /api/internal/property/{property_uuid}/custom-field/update-values/Disabled for the same authentication and authorization blockers.
create-taskPOST /api/internal/task/Disabled for the same authentication and authorization blockers.
update-taskPATCH /api/internal/task/{uuid}/Disabled for the same authentication and authorization blockers.
apply-phone-tagsPOST /api/internal/phone/add-phone-tag/Disabled for the same authentication and authorization blockers.
preview-bulk-operationUnsupportedNo generic DataSift bulk-operation preview endpoint is documented.
execute-bulk-operationUnsupportedNo generic DataSift bulk-operation execution endpoint is documented. The API documents specific operations, not a generic write interface.

Before enabling writes, provide a verified mechanism that maps the authenticated MCP caller to that caller's own DataSift credential (or a backend token exchange), enforce the caller's DataSift permissions, and define idempotency, audit, rate-limit, and billing safeguards for paid/asynchronous operations. Never use a shared administrative key. No production writes are part of local validation.

Test after Redocly synchronization

  1. Push a change to main and wait for the connected Redocly project to synchronize and publish successfully.
  2. Connect an MCP client to the project's root /mcp endpoint using the project URL assigned by Redocly; do not substitute the documentation site URL for the DataSift API server.
  3. Use describe-tools and execute to discover and call custom tools. With a client supporting tools mode, append ?mode=tools to the MCP endpoint and verify the individual tool names are listed.
  4. Try the example prompts:
    • "Show me the documented property autocomplete request for 123 Main St and explain which search parameters the OpenAPI schema actually declares."
    • "What response schema does get-owner-phones describe, and which phone status/type fields are documented?"
    • "Show the documented custom-field filters for searching active property fields in group 12."
    • "What pagination parameters can I use for tasks, and does the API document filters by property?"
    • "Show how to read an activity's status and tell me whether there is a single-activity status endpoint."
  5. Confirm tool results report executionMode: documentation-only and liveDataReturned: false. The local Framework 0.140.0 tools-mode preview omits outputSchema from the tools/list wire representation; each tool declares an output schema in source and the Redocly build accepts it. The local Enterprise preview exposed the code-mode signatures through describe-tools, but execute calls failed with a Framework dispatch error (MCP tool "execute" is not registered...), including a no-op script. Direct tools-mode calls succeeded. Recheck code-mode execution against the synchronized cloud runtime before relying on it. Live account reads require a separate, approved customer-scoped DataSift authentication integration.

For Redocly's current tool contract and authorization behavior, see the Custom MCP tools guide and MCP access guide.

Local validation

Use the repository's existing Redocly CLI setup:

npx --yes @redocly/cli@2 lint --format=github-actions
npx --yes @redocly/cli@2 preview --plan=pro

The preview build should discover tools under @mcp/. The project remains on its existing Git-connected Redocly deployment workflow; no separate server or deployment URL is configured here.