Skip to main content

Agent Integration Quickstart

This guide walks you through registering an AI agent with Claw GRC, opening an MCP session, and invoking your first GRC tool. By the end, you will have a working agent integration.

Prerequisites​

  • A Claw GRC account with an active organization
  • A valid API token (JWT or existing API key)
  • curl or any HTTP client

Step 1: Register Your Agent​

Register a new agent with the Claw GRC API. This creates the agent identity and returns a one-time API key:

curl -X POST https://api.clawgrc.com/api/v1/agents \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "compliance-bot",
    "agent_type": "compliance",
    "description": "Automated compliance evidence collector",
    "capabilities": [
      "grc.list_frameworks",
      "grc.get_compliance_score",
      "grc.create_finding",
      "grc.list_findings"
    ],
    "data_classifications": ["internal", "confidential"]
  }'

Response:

{
  "agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "api_key": "cgrc_ABCDEFghijklmnopqrstuvwxyz1234567890ABCD"
}
warning

Save the api_key immediately. It is shown only once and cannot be recovered. If you lose it, you will need to rotate the key using the /agents/{id}/rotate-key endpoint.

Step 2: Open an MCP Session​

With your agent's API key, establish an MCP session. The handshake verifies the agent is active and returns the list of available tools:

curl -X POST https://api.clawgrc.com/api/v1/mcp/handshake \
  -H "X-API-Key: cgrc_ABCDEFghijklmnopqrstuvwxyz1234567890ABCD" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "protocol_version": "1.0",
    "capabilities": [
      "grc.list_frameworks",
      "grc.get_compliance_score",
      "grc.create_finding",
      "grc.list_findings"
    ]
  }'

Response:

{
  "session_id": "mcp_xK9mP2vB7nQ4wR8sT1uY3cE5fG6hJ",
  "status": "active",
  "supported_tools": [
    "grc.list_frameworks",
    "grc.get_compliance_score",
    "grc.create_finding",
    "grc.create_ticket",
    "grc.list_findings",
    "grc.trigger_scan",
    "grc.call_agent",
    "grc.discover_agents"
  ],
  "expires_at": "2025-01-15T15:30:00Z"
}

The session expires after 1 hour of inactivity. Each tool invocation resets the expiry timer.

Step 3: List Compliance Frameworks​

Now invoke your first MCP tool. Let's list the available compliance frameworks:

curl -X POST https://api.clawgrc.com/api/v1/mcp/message \
  -H "X-API-Key: cgrc_ABCDEFghijklmnopqrstuvwxyz1234567890ABCD" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "mcp_xK9mP2vB7nQ4wR8sT1uY3cE5fG6hJ",
    "method": "grc.list_frameworks",
    "params": {
      "limit": 5
    }
  }'

Response:

{
  "session_id": "mcp_xK9mP2vB7nQ4wR8sT1uY3cE5fG6hJ",
  "result": {
    "frameworks": [
      {
        "id": "fw-uuid-1",
        "name": "SOC 2 Type II",
        "version": "2017",
        "standard_body": "AICPA",
        "status": "active"
      },
      {
        "id": "fw-uuid-2",
        "name": "ISO 27001:2022",
        "version": "2022",
        "standard_body": "ISO/IEC",
        "status": "active"
      }
    ],
    "total": 11
  },
  "error": null
}

Step 4: Get Compliance Score​

Check your organization's compliance score:

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

Response:

{
  "session_id": "mcp_xK9mP2vB7nQ4wR8sT1uY3cE5fG6hJ",
  "result": {
    "score": 78.5,
    "total_controls": 156,
    "compliant_controls": 123
  },
  "error": null
}

Step 5: Create a Finding​

Create a security finding from your agent's analysis:

curl -X POST https://api.clawgrc.com/api/v1/mcp/message \
  -H "X-API-Key: cgrc_ABCDEFghijklmnopqrstuvwxyz1234567890ABCD" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "mcp_xK9mP2vB7nQ4wR8sT1uY3cE5fG6hJ",
    "method": "grc.create_finding",
    "params": {
      "title": "TLS 1.0 support detected on api.example.com",
      "severity": "medium",
      "description": "The endpoint api.example.com:443 supports TLS 1.0, which has known vulnerabilities. Recommend disabling TLS 1.0 and 1.1, allowing only TLS 1.2+.",
      "cwe_id": "CWE-326",
      "cvss_score": 5.3
    }
  }'

Response:

{
  "session_id": "mcp_xK9mP2vB7nQ4wR8sT1uY3cE5fG6hJ",
  "result": {
    "id": "finding-uuid-here",
    "title": "TLS 1.0 support detected on api.example.com",
    "severity": "medium",
    "status": "open"
  },
  "error": null
}

Step 6: Close the Session​

When your agent is done, close the session to clean up resources:

curl -X DELETE https://api.clawgrc.com/api/v1/mcp/sessions/mcp_xK9mP2vB7nQ4wR8sT1uY3cE5fG6hJ \
  -H "X-API-Key: cgrc_ABCDEFghijklmnopqrstuvwxyz1234567890ABCD"

The session is closed and the closure is recorded in the audit trail.

What Just Happened?​

In these 6 steps, your agent:

  1. Registered with a unique identity and API key
  2. Authenticated and opened a secure MCP session
  3. Queried compliance framework data
  4. Checked the organization's compliance score
  5. Created a security finding with proper CWE and CVSS data
  6. Closed the session cleanly

Every single action was logged in the tamper-evident audit trail with chain hashing, and the agent's trust score began building based on the successful interactions.

Next Steps​