Appearance
Tools
The server exposes the tools below. Tools that declare required access only appear in tools/list when your account holds every listed permission, so the assistant sees exactly the set you are allowed to use.
Available tools
| Tool | Access required | Description |
|---|---|---|
ping | (none) | Health-check tool that returns pong (and echoes any provided message). |
suralink_health | (none) | Calls the Suralink API's /health endpoint and returns its status. Requires an authenticated session. |
suralink_get_user_metadata | (none) | Returns the authenticated user's role and userType within an organization. Required: organizationId (UUID). |
suralink_get_feature_flags | (none) | Returns the current Suralink feature flags for the authenticated user as a map of flag name → true/false. No inputs; always live. Use this whenever a flag value needs checking, e.g. to find out why a feature-gated tool isn't available. A flag not in the result is off. |
suralink_get_organizations | (none) | Lists all Suralink organizations the authenticated user belongs to. No inputs. Returns id, organizationId, name, role, isSelected, and (when entitlement is enforced) mcpToolsEntitled. Note: mcpToolsEntitled reflects only the Suralink MCP access grant — it is not the complete entitlement list. For all org entitlements call suralink_get_organization_entitlements. |
suralink_switch_organization | (none) | Switches the active Suralink organization for this session. Required: organizationId (UUID from suralink_get_organizations). Sends a tools/list_changed notification so the client refreshes. Switching is rejected when mcpToolsEntitled is false (MCP access gate only). For the full grant list of any org, call suralink_get_organization_entitlements. |
suralink_get_engagements | engagement:read | Lists Suralink engagements (a.k.a. request lists) for the authenticated user's currently-active client. Takes no arguments — the active client is selected server-side by the session. Returns { active, inactive, archived } where each bucket is an array of { id, customId, name }. |
suralink_get_request_items_for_engagement | engagement:read | Lists request items on a specific engagement. Required arguments: engagementId (integer) and organizationId (UUID, owning organization). Optional: limit (defaults to 25) and offset for paging. |
suralink_get_organization_entitlements | organization:read | Returns the live entitlement grant records for an organization. Optional: organizationId (UUID; defaults to session org), type (numeric filter), includeExpired, includeNotStarted (bools). Use this — not suralink_get_organizations — for the complete feature/product grant list (SSO, e-sign, Workpaper Suite, seat counts, dates, etc.). |
suralink_list_departments | organization:read | Lists departments for an organization. Required: organizationId (UUID). |
suralink_get_department | organization:read | Returns info for a single department. Required: organizationId (UUID), departmentId. |
suralink_get_organization_user | organizationusers:read | Returns a user's role and departmentId. userId is the user's UUID (uuid field from suralink_list_organization_users) — not the numeric userId/id. |
suralink_list_organization_users | organizationusers:read | Paged, sortable, filterable, searchable list of an organization's users. Required: organizationId. Optional: limit (default 25), offset, search, sort, filter. |
suralink_export_organization_users | organizationusers:read | Bulk tabular export of an organization's users. Body returned as raw text. Required: organizationId. |
suralink_list_client_org_users | organizationusers:read | Lists organization users assigned to a client. Required: organizationId, clientId. |
suralink_list_assignable_users_for_request_item | organizationusers:read | Lists organization and client users assignable to a request item. Required: requestItemId, organizationId. |
suralink_list_clients | clients:read | Lists clients for an organization. Required: organizationId. Optional: limit (default 20, max 100), offset. |
suralink_list_my_clients | (none) | Lists every Suralink client the authenticated user belongs to as a client user. No inputs. Distinct from suralink_list_clients (organization-user view). |
suralink_list_request_lists_for_client | engagement:read | Lists request lists for a client filtered by state. Required: organizationId, clientId, state. Optional: limit (default 20, max 100), offset. |
suralink_get_request_list_summary | engagement:read | Returns a summary of a request list. Required: organizationId, requestListId. |
suralink_get_request_list_state | engagement:read | Returns the state of a request list. Required: organizationId, requestListId. |
suralink_get_request_item | engagement:read | Returns info (including state) for a request item. Required: organizationId, requestListId, requestItemId. |
suralink_get_request_item_annotations_bulk | engagement:read | Fetches annotations by IDs for a request item. Each annotationIds entry must be a 26-character ULID (Crockford base32). Required: organizationId, requestListId, requestItemId, annotationIds. |
suralink_get_request_item_files_summary | engagement:read | Lists files attached to a request item. Required: organizationId, requestListId, requestItemId. |
suralink_list_my_engagements | engagement:read | Lists every engagement and report the authenticated user can access as a client user. No inputs. Collapses the suralink_list_my_clients → per-client suralink_list_request_lists_for_client fanout into one call. Firm users receive an error from the upstream. |
suralink_list_request_item_comments | engagement:read | Lists comment history (annotations with their comment threads) for a request item, with pagination. Required: organizationId, requestListId, requestItemId. Optional: limit, offset, commentId. |
suralink_list_request_item_comments_bulk | engagement:read | Fetches comments for an array of annotation/document item IDs in one call. Required: organizationId, requestListId, requestItemId, itemIds[] (min 1). Optional: annotationType (1 = requestItem, 2 = document), system. |
suralink_get_request_item_detail | engagement:read | Returns drill-down detail (state, dueDate, priority, category/subcategory names, engagement name) for a single request item. Required: engagementId, requestId. Distinct from suralink_get_request_item, which addresses the same item by org / request-list path. |
suralink_get_request_item_history | engagement:read | Returns paginated event history (uploads, state changes, comments) for a request item. Required: requestItemId, organizationId (UUID), requestListId. Optional: limit, offset. |
suralink_list_my_recent_clients | clients:read | Returns the authenticated user's most recently viewed clients within an organization. Required: organizationId. |
suralink_list_engagement_firm_users | firmusers:read | Returns firm users with access to an engagement. Required: engagementId. Distinct from suralink_list_client_org_users (firm users on a client, not an engagement). |
suralink_download_request_item_files | engagement:read | Starts a download of files from one or more Suralink request items as an export job and waits up to ~20 seconds for it. When the job completes, returns each file's path and presigned S3 URL (~15-minute lifetime) plus a downloadCommand that saves every file under .suralink-downloads/<jobId>/; otherwise returns the jobId to poll with suralink_get_file_download_job. File bytes travel directly from S3 to the local filesystem; no file data enters the MCP. Required: aId (engagement numeric id), rId (request-item id or comma-separated ids). Optional: fId (file source: -1 client, -2 firm, -3 both; default -3), orgt (folder layout: files, categoryOnly, category; default files), fileIds (specific numeric file row ids from suralink_get_request_item_files_summary; omit or leave empty to download all files on the given request items). |
suralink_get_file_download_job | engagement:read | Checks a download job started by suralink_download_request_item_files. While it runs, returns its status and progress; once completed, returns each file's path and a fresh presigned S3 URL plus a downloadCommand. Only the user who started a job can read it; jobs expire after 24 hours. Required: jobId. |
Access model
Each tool may declare required access. The server hides a tool from tools/list unless every requirement is present for your account. The access names group broadly as:
| Access | Covers |
|---|---|
organization:read | Organization entitlement, department, and related lookups. |
organizationusers:read | Organization-user and assignable-user lookups. |
firmusers:read | Engagement-scoped firm-user lookups. |
clients:read | Client lists and recent-client lookups. |
engagement:read | Engagements, request lists, request items, files, comments, and history. |
Beyond per-tool access, your selected organization must have Suralink MCP access enabled. See Getting Started for details.