Tool Reference

The DataGrail MCP server exposes a set of tools that your AI client can invoke on your behalf. Each tool maps to a specific privacy operations capability within DataGrail, and all tool calls are scoped to your organization and user permissions.

Below is a comprehensive reference for every tool available through the MCP server, grouped by product area: Request Manager, Opt-Out Management, Integrations, Risk & Compliance, Consent Management, and Feedback. Each tool is classified as either Read-only (retrieves data without side effects) or Write (has side effects such as sending a message).

Tool Authorization

During the OAuth authorization flow, you choose which tools to grant access to. You do not need to authorize all tools at once — you can always re-authorize later to add more.

---

Request Manager

Tools for searching and inspecting privacy request tickets (DSARs, access, deletion, and opt-out requests).

search_tickets

Search privacy request tickets with flexible filters and aggregation modes.

Safety classification: Read-only

Parameters:

Name	Type	Required	Description
ticket_uuid	string	No	Get full details for a specific ticket by UUID. When provided, all other filters are ignored.
start_date	string (date)	No	Start of search window (ISO date, e.g. "2024-01-01"). Defaults to 90 days ago.
end_date	string (date)	No	End of search window (ISO date). Defaults to today. Max window is 365 days.
email	string	No	Filter by requester email address (case-insensitive partial match).
notes	string	No	Search within ticket notes/comments (case-insensitive partial match).
status	string	No	Filter by workflow status. Values include: "Active", "Closed", "Pending Action", "Complete", and others.
kind	string	No	Filter by request type: "Access", "Deletion", "Opt Out", "Rectification", "Data Portability", "Object to Processing", and others.
deadline_status	string	No	Filter by deadline urgency: "past_due", "due_soon", or "on_time".
assignee	string	No	Filter by assignment: "assigned_to_me" or "unassigned".
policy_type	string	No	Filter by privacy regulation (e.g. "GDPR", "CPRA", "LGPD").
has_duplicates	boolean	No	Filter to tickets with duplicate email addresses.
integration_state	string	No	Filter by integration state: "processing", "completed", or "failed".
via	string	No	Filter by submission channel: "Phone", "Email", "Intake Request Form", "API", "Request Manager", "Internal Form".
entered_status	string	No	Find tickets that transitioned into a specific status historically. Requires entered_status_start_date.
entered_status_start_date	string (date)	No	Start of date range for entered_status filter.
entered_status_end_date	string (date)	No	End of date range for entered_status filter. Defaults to today.
aggregation_mode	string	No	Get aggregate counts instead of ticket list: "count", "group_by_status", "group_by_kind", "group_by_policy", "group_by_deadline", "group_by_via", "group_by_submitted_by", "group_by_country", "group_by_region", "group_by_day", "group_by_week", "group_by_month".
limit	integer	No	Maximum results to return (default: 25, max: 100).

Example response:

{
  "results": [
    {
      "uuid": "ticket-uuid-123",
      "email": "jane@example.com",
      "kind": "deletion",
      "workflow_state": "pending_legal",
      "due_date": "2025-04-15",
      "created_at": "2025-03-01T12:00:00Z",
      "via": "Intake Request Form"
    }
  ],
  "count": 1,
  "total_matching": 1,
  "truncated": false
}

get_ticket_activity_log

Retrieve the chronological activity log for a specific privacy request ticket, including state changes, emails sent, and manual actions.

Safety classification: Read-only

Parameters:

Name	Type	Required	Description
ticket_uuid	string	Yes	The UUID of the ticket to get the activity log for.
limit	integer	No	Maximum number of activity log entries to return (default: 50, max: 200).

Example response:

{
  "ticket_uuid": "ticket-uuid-123",
  "activity_log": [
    {
      "timestamp": "2025-03-01T14:30:00Z",
      "actor": "admin@acme.com",
      "event": "workflow_state_change",
      "details": { "from": "pending_confirmation", "to": "pending_legal" }
    }
  ],
  "count": 1
}

get_request_policies

Retrieve the list of privacy request policies configured for your organization, including legal frameworks, verification methods, and supported privacy rights.

Safety classification: Read-only

Parameters:

Name	Type	Required	Description
include_archived	boolean	No	Include archived/inactive policies in results (default: false).

Example response:

{
  "policies": [
    {
      "id": 1,
      "internal_name": "CPRA",
      "external_name": "CPRA",
      "status": "active",
      "default_policy": true,
      "verification_method": "email",
      "request_duration_days": 45,
      "privacy_rights": ["Access", "Deletion", "Opt Out"],
      "locations": [{ "code": "US-CA", "name": "California" }]
    }
  ],
  "count": 1,
  "disclaimer": "This information is provided for informational purposes only..."
}

---

Opt-Out Management

Tools for managing Do Not Sell / Do Not Share opt-out requests.

search_opt_outs

Search opt-out requests with flexible filters and aggregation modes.

Safety classification: Read-only

Parameters:

Name	Type	Required	Description
opt_out_uuid	string	No	Get full details for a specific opt-out by UUID. When provided, all other filters are ignored.
start_date	string (date)	No	Start of search window (ISO date). Defaults to 90 days ago.
end_date	string (date)	No	End of search window (ISO date). Defaults to today. Max window is 365 days.
email	string	No	Filter by requester email (case-insensitive partial match).
name	string	No	Filter by requester name (case-insensitive partial match).
additional_info	string	No	Search within opt-out notes (case-insensitive partial match).
status	string	No	Filter by status: "Active", "Not Started", "In Progress", "Complete", "Canceled".
deadline_status	string	No	Filter by deadline urgency: "past_due", "due_soon", "on_time".
policy_type	string	No	Filter by privacy regulation (e.g. "CCPA", "CPRA").
verification_state	string	No	Filter by verification status: "verified" or "unverified".
request_source	string	No	Filter by submission source: "application", "intake_form", "api".
has_duplicates	boolean	No	Filter to opt-outs with duplicate emails.
integration_state	string	No	Filter by integration state: "processing", "completed", "failed".
location	string	No	Filter by location using ISO codes (e.g. "US-CA" for California, "US" for all US).
has_been_extended	boolean	No	Filter by whether the deadline has been extended.
submitted_by_agent	boolean	No	Filter by whether submitted by an authorized agent.
aggregation_mode	string	No	Aggregate mode: "count", "group_by_status", "group_by_policy", "group_by_deadline", "group_by_verification", "group_by_source", "group_by_day", "group_by_week", "group_by_month".
limit	integer	No	Maximum results to return (default: 25, max: 100).

Example response:

{
  "results": [
    {
      "uuid": "optout-uuid-456",
      "email": "user@example.com",
      "status": "in_progress",
      "due_date": "2025-04-01",
      "location": "US-CA",
      "request_source": "Intake Form",
      "policy": "CPRA"
    }
  ],
  "count": 1,
  "total_matching": 1,
  "truncated": false
}

---

Integrations

Tools for exploring available integrations, checking connection health, and reviewing configured connections.

fetch_integration_catalog

Browse the catalog of all available DataGrail integrations, search by name, or find integrations that have been discovered but not yet connected.

Safety classification: Read-only

Parameters:

Name	Type	Required	Description
search_query	string	No	Search for a specific integration by name (e.g. "salesforce", "google apps"). Returns all if omitted.
only_discovered	boolean	No	Return only integrations discovered but not yet connected (default: false). Useful for "What should I connect next?" queries.

Example response:

{
  "integrations": {
    "integrations": [
      {
        "id": 42,
        "display_name": "Salesforce",
        "service_name": "salesforce",
        "integration_method": "api",
        "capabilities": ["Access", "Deletion", "Identifier Retrieval"]
      }
    ],
    "summary": "Found 1 integration(s) matching 'salesforce'."
  },
  "count": 1
}

fetch_integration_errors

Retrieve integration errors grouped by integration and error type, with sample error details for troubleshooting.

Safety classification: Read-only

Parameters:

Name	Type	Required	Description
days	integer	No	Number of days to look back for errors (default: 30, max: 90).

Example response:

{
  "error_groups": [
    {
      "integration": {
        "name": "salesforce-prod",
        "display_name": "Salesforce"
      },
      "error_type": "Authentication Error",
      "count": 5,
      "first_seen": "2025-02-15T10:00:00Z",
      "last_seen": "2025-03-01T08:30:00Z",
      "sample_errors": [
        {
          "timestamp": "2025-03-01T08:30:00Z",
          "status_code": 401,
          "error_message": "Invalid credentials",
          "ticket_uuid": "ticket-uuid-789"
        }
      ]
    }
  ]
}

fetch_configured_integration_catalog

Retrieve your organization's configured (connected) integrations with connection status, capabilities, and integration type details.

Safety classification: Read-only

Parameters:

Name	Type	Required	Description
search_query	string	No	Search by integration name or display name (partial match).
connection_status	string	No	Filter by status: "connected", "disconnected", "pending".
integration_type	string	No	Filter by method: "api", "direct_contact", "none".
capability	string	No	Filter by enabled capability (e.g. "Access", "Deletion", "Data Discovery").
aggregation_mode	string	No	Aggregate mode: "count", "group_by_status", "group_by_kind", "group_by_integration_type", "group_by_capability".

Example response:

{
  "integrations": [
    {
      "uuid": "auth-uuid-001",
      "name": "salesforce-prod",
      "integration_name": "Salesforce",
      "integration_type": "api",
      "is_connected": true,
      "enabled_capabilities": ["Access", "Deletion"],
      "available_to_enable": ["Data Discovery"]
    }
  ],
  "count": 1
}

---

Risk & Compliance

Tools for managing the risk register, risk assessments, assessment templates, and system inventory.

search_risks

Search the risk register for identified risks and their mitigation status.

Safety classification: Read-only

Parameters:

Name	Type	Required	Description
overall_risk	string	No	Filter by risk level: "very_low", "low", "medium", "high", "very_high".
mitigation_status	string	No	Filter by mitigation status: "not_started", "in_progress", "mitigated", "accepted".
limit	integer	No	Maximum results to return (default: 50, max: 100).

Example response:

{
  "results": [
    {
      "id": 10,
      "description": "Unencrypted PII stored in legacy system",
      "overall_risk": "high",
      "impact": "high",
      "likelihood": "medium",
      "mitigation_status": "in_progress",
      "owner_email": "privacy@acme.com",
      "due_date": "2025-06-30"
    }
  ],
  "count": 1,
  "total_matching": 1,
  "truncated": false
}

search_assessments

Search completed and in-progress risk assessments (PIAs, DPIAs, vendor reviews) with deadline tracking and contributor filtering.

Safety classification: Read-only

Parameters:

Name	Type	Required	Description
assessment_id	string	No	Get full details for a specific assessment by UUID. When provided, all other filters are ignored.
start_date	string (date)	No	Start of search window (ISO date). Defaults to 90 days ago.
end_date	string (date)	No	End of search window (ISO date). Defaults to today. Max window is 365 days.
status	string	No	Filter by assessment status: "not_started", "in_progress", "pending_approval", "approved".
deadline_status	string	No	Filter by deadline urgency: "past_due", "due_soon", "on_time".
assessment_name	string	No	Filter by assessment name (partial match, case-insensitive).
template_name	string	No	Filter by assessment template name (partial match, case-insensitive).
contributor_email	string	No	Filter by contributor email (partial match, case-insensitive).
contribution_status	string	No	Filter by contribution status: "not_invited", "not_started", "in_progress", "removed", "complete".
limit	integer	No	Maximum results to return (default: 10, max: 100).

Example response:

{
  "results": [
    {
      "id": "assessment-uuid-001",
      "name": "Vendor Security Review - Acme Analytics",
      "status": "in_progress",
      "due_date": "2025-05-01",
      "assessment_template": { "name": "Vendor Assessment Template" },
      "assessment_contributors": [
        { "email": "reviewer@acme.com", "status": "in_progress" }
      ]
    }
  ],
  "count": 1,
  "total_matching": 1,
  "truncated": false
}

search_assessment_templates

Search risk assessment templates, including both prebuilt (DataGrail-provided) and custom templates.

Safety classification: Read-only

Parameters:

Name	Type	Required	Description
template_id	string	No	Retrieve a single template by ID with full form details.
template_name	string	No	Filter by template name (partial match, case-insensitive).
limit	integer	No	Maximum results to return (default: 10, max: 100).

Example response:

{
  "results": [
    {
      "id": "template-uuid-001",
      "name": "Data Protection Impact Assessment (DPIA)",
      "product": "rimo",
      "created_at": "2024-06-01T00:00:00Z"
    }
  ],
  "count": 1,
  "total_matching": 1,
  "truncated": false
}

search_inventory

Search the system inventory (Live Data Map) for detected systems and data stores, with filters for risk indicators, assessment status, and processing activity associations.

Safety classification: Read-only

Parameters:

Name	Type	Required	Description
sensitive_personal_data	string	No	Filter by SPI risk. Use "SPI" to find systems with sensitive personal information.
ai_risks	string	No	Filter by AI risk: "AI Risks" or "AI Detected".
has_assessment	string	No	Filter by assessment association: "yes" or "no".
processing_activity	string	No	Find inventory items that should belong to a given processing activity name.
system_name	string	No	Find suggested processing activities for a system (fuzzy name match).
days	integer	No	Filter by number of days since the inventory item was created.
limit	integer	No	Maximum results to return (default: 50, max: 100).

Example response:

{
  "results": [
    {
      "id": 101,
      "name": "Salesforce CRM",
      "description": "Customer relationship management platform",
      "via": "detected",
      "risk": { "spi": true, "ai_detected": false },
      "processing_activities": ["Customer Support", "Marketing"],
      "last_edited": "2025-02-28T10:00:00Z"
    }
  ],
  "count": 1,
  "total_matching": 1,
  "truncated": false
}

---

Consent Management

Tools for managing consent banners, cookies, tags, and privacy policies related to consent.

fetch_cookies

Retrieve cookies in different states: unmanaged cookies awaiting categorization, suggested categorization rules, or existing cookie rules.

Safety classification: Read-only

Parameters:

Name	Type	Required	Description
state	string	Yes	State of cookies to fetch: "unmanaged" (not yet categorized), "suggested" (matching house rules), or "rules" (existing customer rules).

Example response (unmanaged):

{
  "state": "unmanaged",
  "count": 3,
  "cookies": [
    {
      "cookie_name": "_ga",
      "url_domain": "example.com",
      "first_seen_at": "2025-01-15T00:00:00Z",
      "last_seen_at": "2025-03-01T00:00:00Z",
      "seen_count": 450
    }
  ]
}

fetch_tags

Retrieve tags (services) that need consent category assignment.

Safety classification: Read-only

Parameters:

Name	Type	Required	Description
state	string	Yes	State of tags to fetch. Currently supports: "uncategorized" (tags without a consent category).

Example response:

{
  "state": "uncategorized",
  "count": 2,
  "tags": [
    {
      "id": 55,
      "name": "google-analytics",
      "display_name": "Google Analytics",
      "vendor": "Google",
      "status": "active",
      "description": "Web analytics service"
    }
  ]
}

get_banner_status

Get the status of consent banners, containers, and their configuration, including publish state, consent categories, and deployed domains.

Safety classification: Read-only

Parameters:

Name	Type	Required	Description
include_categories	boolean	No	Include consent category details (default: true).
include_domains	boolean	No	Include domain information where consent is deployed (default: true).
container_id	integer	No	Get status for a specific container ID. Returns all containers if omitted.

Example response:

{
  "containers": [
    {
      "id": 1,
      "name": "Main Website",
      "type": "standalone",
      "managed": true,
      "versions": {
        "has_draft": true,
        "has_published": true,
        "last_published_at": "2025-02-20T16:00:00Z",
        "draft_updated_at": "2025-03-01T10:30:00Z"
      },
      "categories": {
        "total_categories": 4,
        "categories": [
          { "primitive": "essential", "always_on": true },
          { "primitive": "performance", "always_on": false },
          { "primitive": "functional", "always_on": false },
          { "primitive": "marketing", "always_on": false }
        ]
      },
      "domains": [
        { "domain_name": "www.example.com" }
      ]
    }
  ],
  "summary": {
    "total_containers": 1,
    "managed_containers": 1
  }
}

get_consent_updates

Retrieve consent update history and change timeline, including publish events, draft changes, and failed publish attempts.

Safety classification: Read-only

Parameters:

Name	Type	Required	Description
container_id	integer	No	Get updates for a specific container. Returns all if omitted.
limit	integer	No	Maximum version updates per container (default: 10).
include_draft_changes	boolean	No	Include draft version changes (default: true).
include_failed_publishes	boolean	No	Include failed/cancelled publish attempts (default: true).
days_back	integer	No	Only show updates from the last N days.

Example response:

{
  "containers": [
    {
      "container_id": 1,
      "container_name": "Main Website",
      "last_published_at": "2025-02-20T16:00:00Z",
      "versions": [
        {
          "version_id": 12,
          "status": "published",
          "published_at": "2025-02-20T16:00:00Z",
          "version_number": 5
        }
      ]
    }
  ],
  "summary": {
    "total_containers": 1,
    "most_recent_publish": "2025-02-20T16:00:00Z"
  }
}

get_consent_privacy_policies

Retrieve consent privacy policies that define how consent banners behave for different privacy frameworks, including consent modes, GPC/DNT settings, and category configurations.

Safety classification: Read-only

Parameters:

Name	Type	Required	Description
status	string	No	Filter by policy status: "draft" or "published" (default: "published").
include_categories	boolean	No	Include consent category details (default: false).

Example response:

{
  "policies": [
    {
      "id": 1,
      "name": "CPRA Consent Policy",
      "status": "published",
      "consent_banner_enabled": true,
      "consent_banner_mode": "opt_out",
      "consent_respect_gpc_enabled": true,
      "privacy_request_policy": {
        "external_name": "CPRA",
        "verification_method": "email",
        "request_duration_days": 45
      }
    }
  ],
  "count": 1,
  "disclaimer": "This information is provided for informational purposes only..."
}

---

Feedback

Tools for submitting feedback and feature requests to the DataGrail product team.

submit_product_feedback

Submit product feedback, feature requests, or bug reports on behalf of the user.

Write Tool

This is the only tool that has side effects — it sends a feedback message to the DataGrail product team. It does not modify or delete any existing data.

Safety classification: Write (sends a message)

Parameters:

Name	Type	Required	Description
feedback	string	Yes	The feedback, feature request, or bug report text.
product	string	Yes	The product area: "Request Manager", "Live Data Map", "Risk Assessment", "Consent Management", "Integrations", "Dashboard", or "General".
additional_context	string	No	Additional context about the feedback, such as conversation summary.

Example response:

{
  "status": "submitted",
  "message": "Thank you for your feedback!"
}