MCP Tools Reference

This page documents every MCP tool available to agents in Claw GRC. Each tool is invoked through the POST /api/v1/mcp/message endpoint with the tool name as the method field.

Tool Invocation Pattern

All tools follow the same invocation pattern:

curl -X POST https://api.clawgrc.com/api/v1/mcp/message \
  -H "X-API-Key: cgrc_..." \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "mcp_...",
    "method": "TOOL_NAME",
    "params": { ... }
  }'

---

grc.list_frameworks

List available compliance frameworks for the organization.

Parameters

Parameter	Type	Required	Default	Description
limit	integer	No	50	Maximum results to return (1-200)
offset	integer	No	0	Pagination offset (0-10000)

Example

{
  "method": "grc.list_frameworks",
  "params": {
    "limit": 5,
    "offset": 0
  }
}

Response

{
  "result": {
    "frameworks": [
      {
        "id": "uuid",
        "name": "SOC 2 Type II",
        "version": "2017",
        "standard_body": "AICPA",
        "status": "active",
        "description": "Service Organization Control 2..."
      }
    ],
    "total": 11
  }
}

---

grc.get_compliance_score

Get the organization's overall compliance score and breakdown.

Parameters

Parameter	Type	Required	Description
framework_id	string (UUID)	No	Scope the score to a specific framework

Example

{
  "method": "grc.get_compliance_score",
  "params": {
    "framework_id": "fw-uuid-here"
  }
}

Response

{
  "result": {
    "score": 82.5,
    "total_controls": 64,
    "compliant_controls": 53
  }
}

---

grc.create_finding

Create a new security finding in the security engine.

Parameters

Parameter	Type	Required	Description
title	string	Yes	Concise description of the vulnerability
severity	string	Yes	critical, high, medium, low, or info
description	string	No	Detailed explanation of the issue
assessment_id	string (UUID)	No	Link to an existing assessment
cwe_id	string	No	Common Weakness Enumeration ID (e.g., CWE-79)
cvss_score	number	No	CVSS v3.1 base score (0.0-10.0)

Example

{
  "method": "grc.create_finding",
  "params": {
    "title": "SQL injection in user search API",
    "severity": "critical",
    "description": "The /api/users/search endpoint is vulnerable to SQL injection via the 'q' parameter. An attacker can extract sensitive data from the users table.",
    "cwe_id": "CWE-89",
    "cvss_score": 9.8
  }
}

Response

{
  "result": {
    "id": "finding-uuid",
    "title": "SQL injection in user search API",
    "severity": "critical",
    "status": "open"
  }
}

---

grc.create_ticket

Create a remediation ticket linked to a finding or control.

Parameters

Parameter	Type	Required	Description
title	string	Yes	Clear description of the work to be done
description	string	No	Detailed context and remediation steps
priority	string	Yes	critical, high, medium, or low
finding_id	string (UUID)	No	Link to the finding that triggered this ticket

Example

{
  "method": "grc.create_ticket",
  "params": {
    "title": "Patch SQL injection vulnerability in user search",
    "description": "Use parameterized queries for the /api/users/search endpoint. See finding F-2024-042.",
    "priority": "critical",
    "finding_id": "finding-uuid"
  }
}

Response

{
  "result": {
    "id": "ticket-uuid",
    "title": "Patch SQL injection vulnerability in user search",
    "status": "open"
  }
}

---

grc.list_findings

List security findings with optional severity and status filters.

Parameters

Parameter	Type	Required	Default	Description
severity	string	No	-	Filter by severity (critical, high, medium, low, info)
status	string	No	-	Filter by status (open, in_progress, resolved, accepted)
limit	integer	No	50	Maximum results to return (1-200)
offset	integer	No	0	Pagination offset (0-10000)

Example

{
  "method": "grc.list_findings",
  "params": {
    "severity": "critical",
    "status": "open",
    "limit": 10
  }
}

Response

{
  "result": {
    "findings": [
      {
        "id": "finding-uuid",
        "title": "SQL injection in user search API",
        "severity": "critical",
        "status": "open",
        "cwe_id": "CWE-89",
        "cvss_score": 9.8,
        "created_at": "2025-01-15T14:30:00Z"
      }
    ],
    "total": 3
  }
}

---

grc.trigger_scan

Trigger a security scan for a target URL or resource.

Parameters

Parameter	Type	Required	Default	Description
target	string	Yes	-	URL or resource identifier to scan
scan_type	string	No	dast	Scan type: dast, api, cloud_config

Example

{
  "method": "grc.trigger_scan",
  "params": {
    "target": "https://api.example.com",
    "scan_type": "api"
  }
}

Response

{
  "result": {
    "scan_id": "scan-uuid",
    "status": "running"
  }
}

info

Scans run synchronously. The response is returned after the scan completes, which may take up to 60 seconds for large targets. The default timeout for scan operations is 60 seconds.

---

grc.call_agent

Invoke another registered agent by ID. This enables agent-to-agent communication within the GRC platform.

Parameters

Parameter	Type	Required	Description
target_agent_id	string (UUID)	Yes	The ID of the agent to invoke
method	string	Yes	The method to call on the target agent
params	object	No	Parameters for the method invocation

Example

{
  "method": "grc.call_agent",
  "params": {
    "target_agent_id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
    "method": "analyze_configuration",
    "params": {
      "resource": "aws:ec2:instance:i-1234567890abcdef0"
    }
  }
}

Response

{
  "result": {
    "request_id": "req-uuid",
    "status": "queued",
    "interaction_id": "interaction-uuid"
  }
}

Validation

• The target_agent_id must be a valid UUID (path traversal prevention)
• The target agent must exist, be active, and belong to the same organization
• The target agent must meet the caller's trust score threshold (if specified)
• The invocation is logged with chain hashing in the agent_interactions table

---

grc.discover_agents

Find agents matching capability and trust score criteria within your organization.

Parameters

Parameter	Type	Required	Description
capabilities	string[]	Yes	Required capabilities the agent must have
min_trust_score	number	No	Minimum trust score (0.0-1.0, default: 0.0)

Example

{
  "method": "grc.discover_agents",
  "params": {
    "capabilities": ["grc.trigger_scan", "grc.create_finding"],
    "min_trust_score": 0.7
  }
}

Response

{
  "result": {
    "agents": [
      {
        "id": "uuid",
        "name": "security-scanner",
        "agent_type": "security",
        "trust_score": 0.92,
        "capabilities": ["grc.trigger_scan", "grc.create_finding", "grc.create_ticket"],
        "status": "active"
      }
    ],
    "total": 1
  }
}

Results are sorted by trust score descending, so the most trusted agents appear first.

---

Error Handling

All tools return errors in a consistent format within the MCP response:

{
  "session_id": "mcp_...",
  "result": null,
  "error": {
    "code": "error_code",
    "message": "Human-readable error description"
  }
}

Error Codes

Code	Description
permission_denied	Agent lacks the capability for the requested tool
invalid_params	Required parameters are missing or invalid
validation_error	Downstream service returned a validation error (422)
upstream_error	Downstream service returned a non-success status
method_not_found	The tool name is not recognized