MCP Server

The Secberus compliance service exposes a Model Context Protocol (MCP) interface, allowing AI clients such as Claude Desktop, Cursor, and custom agents to call compliance tools directly—without writing REST API code.

When to use MCP vs REST:

  • Use the MCP interface when integrating with an AI client or agent that supports MCP.
  • Use the REST API for server-to-server integrations and pipelines.

Connection Details

Property Value
Endpoint POST https://compliance.secberus.ai/mcp
Transport MCP Streamable HTTP (spec 2025-03-26)
Protocol JSON-RPC 2.0
Content-Type application/json

Authentication

Pass your API key in the authorization header on every request:

authorization: YOUR_API_KEY

Protocol Flow

MCP requires a short handshake before calling tools. Send these two requests once when your client connects:

1. Initialize

curl -X POST https://compliance.secberus.ai/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize"}'

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-03-26",
    "capabilities": { "tools": {} },
    "serverInfo": { "name": "compliance-service", "version": "1.0.0" }
  }
}

2. Notify initialized

curl -X POST https://compliance.secberus.ai/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"initialized"}'

Returns HTTP 202 Accepted with no body. After this, you can call any tool.

Discover Tools

curl -X POST https://compliance.secberus.ai/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

Returns all available tool definitions including names, descriptions, and input schemas.

Calling Tools

All tools are invoked via tools/call:

{
  "jsonrpc": "2.0",
  "id": <number>,
  "method": "tools/call",
  "params": {
    "name": "<tool_name>",
    "arguments": { ... }
  }
}

Successful results are returned in this envelope:

{
  "jsonrpc": "2.0",
  "id": <number>,
  "result": {
    "content": [{ "type": "text", "text": "<JSON string>" }],
    "isError": false
  }
}

When a tool fails, isError is true and text contains the error detail.

Tools

Tools Overview

Tool Auth Required Description
list_frameworks No List all available compliance frameworks
map_document No Map document text to framework controls

list_frameworks

List all compliance frameworks available for mapping.

Parameters: None

Example

curl -X POST https://compliance.secberus.ai/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "list_frameworks",
      "arguments": {}
    }
  }'

Response

[
  { "id": "pci_dss_v4", "name": "PCI DSS v4.0", "region": "Global" },
  { "id": "nist_800_53_r5", "name": "NIST 800-53 Rev. 5", "region": "US" },
  { "id": "iso_27001_2022", "name": "ISO/IEC 27001:2022", "region": "Global" }
]
Field Type Description
id string Framework identifier — use this in map_document
name string Human-readable name
region string Geographic applicability

map_document

Map one or more text documents to controls across compliance frameworks using semantic search and AI re-ranking.

Parameters

Field Type Required Description
documents array[Document] Yes Documents to map
frameworks array[string] No Framework IDs to restrict the search. Omit to search all frameworks.
top_k integer No Max controls to return per document (default: 5)

Document Object

Field Type Required Description
document string Yes Document text (~250 words max per document)
category string No Optional category hint to improve relevance

Example

curl -X POST https://compliance.secberus.ai/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "tools/call",
    "params": {
      "name": "map_document",
      "arguments": {
        "documents": [
          {
            "document": "All user passwords must be at least 12 characters and rotated every 90 days.",
            "category": "Access Control"
          }
        ],
        "frameworks": ["pci_dss_v4"],
        "top_k": 3
      }
    }
  }'

Response

{
  "frameworks": [
    {
      "framework_id": "pci_dss_v4",
      "controls": [
        {
          "document_id": "doc1",
          "similarity": 0.87,
          "confidence": "High",
          "control": {
            "id": "8.3.9",
            "framework_id": "pci_dss_v4",
            "family": "Identify Users and Authenticate Access",
            "family_id": "8"
          }
        }
      ]
    }
  ],
  "messages": []
}
Field Type Description
similarity float Similarity score 0.0–1.0
confidence string High, Medium, Low, or Very Low
control.id string Control identifier within the framework
control.family string Control family name

Connecting AI Clients

Claude Desktop

Add the following to your Claude Desktop configuration file (claude_desktop_config.json):

{
  "mcpServers": {
    "secberus-compliance": {
      "url": "https://compliance.secberus.ai/mcp",
      "headers": {
        "authorization": "YOUR_API_KEY"
      }
    }
  }
}

Cursor

In Cursor, go to Settings → MCP → Add Server and provide:

  • URL: https://compliance.secberus.ai/mcp
  • Header: authorization: YOUR_API_KEY

Other MCP-compatible clients

Any client supporting the MCP Streamable HTTP transport (2025-03-26) can connect by pointing to https://compliance.secberus.ai/mcp with your API key in the authorization header.

Error Handling

JSON-RPC Errors

Protocol-level errors (invalid method, bad JSON, etc.) return a standard JSON-RPC error object:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32601,
    "message": "method not found"
  }
}
Code Meaning
-32700 Parse error — malformed JSON
-32602 Invalid params
-32601 Method not found

Tool Errors

When a tool itself fails (e.g. invalid API key, unknown document ID), the response uses the standard envelope with isError: true:

{
  "jsonrpc": "2.0",
  "id": 5,
  "result": {
    "content": [{ "type": "text", "text": "unauthorized" }],
    "isError": true
  }
}
Endpoints Best Practices