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..."
}

---

Documentation

Tools for searching DataGrail's knowledgebase documentation.

External MCP Only

Tools in this section are available exclusively through external MCP connections (such as Claude, Cursor, or Windsurf). They are not accessible through the Vera chat interface inside DataGrail.

search_knowledgebase_docs

Search DataGrail's knowledgebase documentation using semantic search.

Safety classification: Read-only

Parameters:

Name	Type	Required	Description
query	string	Yes	The search query to find relevant documentation.
limit	integer	No	Maximum number of results to return (default: 5, max: 10).

Example response:

{
  "results": [
    {
      "text": "To configure SSO, navigate to Settings > Authentication and select Add Identity Provider...",
      "score": 0.91
    },
    {
      "text": "DataGrail supports SAML 2.0 for single sign-on. Contact support@datagrail.io to enable SSO for your organization...",
      "score": 0.84
    }
  ]
}

---

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!"
}