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.
| MCP tool | DataSift operation | Method and path |
|---|---|---|
search-properties | autocompletePropertyElastic | GET /api/internal/property/autocomplete/ |
get-property | retrieveProperty | GET /api/internal/property/{uuid}/ |
get-property-history | logsLogElastic | GET /api/internal/property/{uuid}/logs/ |
get-owner | retrieveOwner | GET /api/internal/owner/{uuid}/ |
get-owner-phones | retrieveOwner | GET /api/internal/owner/{uuid}/ |
list-phone-tags | listPhoneTags | GET /api/internal/phone/tag/ |
list-custom-fields | listCustomFields | GET /api/internal/custom-fields/ |
get-property-custom-fields | listCustomFieldValues | GET /api/internal/property/{property_uuid}/custom-field/ |
list-tasks | listTasks | GET /api/internal/task/ |
get-task | retrieveTask | GET /api/internal/task/{uuid}/ |
list-task-presets | listTaskPresets | GET /api/internal/task-preset/ |
list-tags | listTags | GET /api/internal/tag/ |
list-lists | listLists | GET /api/internal/list/ |
get-activity-status | listActivities | GET /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.
- 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/) documentslimitandoffsetonly. It has no documented search/filter/order parameters, so the existing API description does not support a fully filterable, sortable property search tool. list-tasksdocumentslimitandoffsetonly; no task filters are declared in the API schema.- Owner phone details are embedded in the
Ownerresponse (phones,total_phones,primary_phone); the API has no separate GET owner-phones operation. The documentedPhonefields includenumber,type,tags,status, andis_connected. get-activity-statusdescribes 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-onlyandliveDataReturned: false.
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 operation | Documented DataSift route | State |
|---|---|---|
apply-property-tags | POST /api/internal/property/{uuid}/add-tags/ | Disabled until customer-scoped authentication, authorization, duplicate-request controls, and audit handling are implemented. |
update-property-custom-fields | PATCH /api/internal/property/{property_uuid}/custom-field/update-values/ | Disabled for the same authentication and authorization blockers. |
create-task | POST /api/internal/task/ | Disabled for the same authentication and authorization blockers. |
update-task | PATCH /api/internal/task/{uuid}/ | Disabled for the same authentication and authorization blockers. |
apply-phone-tags | POST /api/internal/phone/add-phone-tag/ | Disabled for the same authentication and authorization blockers. |
preview-bulk-operation | Unsupported | No generic DataSift bulk-operation preview endpoint is documented. |
execute-bulk-operation | Unsupported | No 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.
- Push a change to
mainand wait for the connected Redocly project to synchronize and publish successfully. - Connect an MCP client to the project's root
/mcpendpoint using the project URL assigned by Redocly; do not substitute the documentation site URL for the DataSift API server. - Use
describe-toolsandexecuteto discover and call custom tools. With a client supporting tools mode, append?mode=toolsto the MCP endpoint and verify the individual tool names are listed. - Try the example prompts:
- "Show me the documented property autocomplete request for
123 Main Stand explain which search parameters the OpenAPI schema actually declares." - "What response schema does
get-owner-phonesdescribe, 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."
- "Show me the documented property autocomplete request for
- Confirm tool results report
executionMode: documentation-onlyandliveDataReturned: false. The local Framework 0.140.0 tools-mode preview omitsoutputSchemafrom thetools/listwire representation; each tool declares an output schema in source and the Redocly build accepts it. The local Enterprise preview exposed the code-mode signatures throughdescribe-tools, butexecutecalls 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.
Use the repository's existing Redocly CLI setup:
npx --yes @redocly/cli@2 lint --format=github-actions
npx --yes @redocly/cli@2 preview --plan=proThe 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.