API Reference

This API reference provides essential information for developers integrating with the SigilAI Cloud Model Context Protocol (MCP) server. It covers authentication, MCP message structure, tool invocation, and general API behavior.

Endpoint

All MCP communication with the SigilAI Cloud server occurs over HTTPS using Server-Sent Events (SSE).

• Production Endpoint: https://mcp.sigilai.io/sse (This is an example. Always use the endpoint URL provided in your SigilAI account dashboard.)

Authentication

Requests to the SigilAI MCP server must be authenticated using an API key.

• Method: Bearer Token Authentication.

• Header: Authorization

• Value: Bearer YOUR_SIGILAI_API_KEY

Replace YOUR_SIGILAI_API_KEY with the actual API key obtained from your SigilAI account dashboard.

Example Request Header:

Authorization: Bearer sk_xxxxxxxxxxxxxxxxxxxxxxxx
Accept: text/event-stream
Content-Type: application/json

Failure to authenticate correctly will result in an HTTP 401 Unauthorized or 403 Forbidden error, or an MCP error message.

MCP Message Structure

SigilAI adheres to the Model Context Protocol. All messages exchanged between the client and server are JSON objects. Key message types include:

• Client to Server:

  • tool_call: Used to invoke a specific tool.

    • type: "tool_call"

    • id: (Optional) A unique ID for the call, will be echoed in the tool_result.

    • name: The name of the tool to invoke (e.g., "scan_url", "scan_file").

    • parameters: An object containing the parameters for the tool.

• Server to Client:

  • server_info: Provides information about the server upon connection.

  • tool_result: Contains the result of a tool_call.

    • type: "tool_result"

    • id: (Optional) The ID from the corresponding tool_call.

    • name: The name of the tool that was invoked.

    • result: A string (typically JSON stringified) containing the tool's output.

  • error: Indicates an error occurred.

    • type: "error"

    • message: A human-readable error message.

    • code: (Optional) An error code.

Refer to the official Model Context Protocol specification for complete details on message types and structures.

Available Tools

The following primary tools are available. Detailed capabilities and tier-specific features are described below for each tool.

1. URL Scanner (scan_url)

Scans a URL for security threats.

• Name: scan_url

• Parameters:

  • url (string, required): The URL to scan.

    • Pro/Enterprise Tiers: May support an array of URLs for batch scanning. Consult your plan details.

  • userId (string, optional): An identifier for the end-user or context of the scan.

  • options (object, optional): Advanced scanning options (tier-dependent).

    • force_rescan (boolean, optional): If true, forces a fresh scan, bypassing any cached results.

    • analysis_depth (enum, optional): e.g., "quick", "full".

• Expected Result (result field in tool_result message - JSON stringified): A JSON object containing:

  • url (string): The submitted URL.

  • domain

  • isSafe (boolean): Overall safety assessment.

  • riskScore (number, optional): A numerical risk score.

  • findings (array of objects): Detailed threats found. Each finding may include type, description, confidence.

  • isBlacklisted (boolean): Whether the domain is on known blacklists.

  • warnings (array of strings): Contextual warnings.

  • md5 (string): MD5 hash of the domain.

  • scanId (string): A unique identifier for this scan.

  • timestamp (string): ISO 8601 timestamp of the scan. (example; actual fields may vary slightly.)

2. File Scanner (scan_file)

Scans source code file content for vulnerabilities. (Tool name might also be "SigilAI Code Scanner" or similar; check server_info or your dashboard).

• Name: scan_file (or as specified by the server)

• Parameters:

  • Single File Scan (All Tiers):

    • file (object, required):

      • path (string, required): Relative path of the file (e.g., "src/app.js").

      • content (string, required): The source code content.

  • Batch File Scan (Pro/Enterprise Tiers):

    • files (array of file objects, required): Each object with path and content.

  • Repository Scan (Enterprise Tier):

    • repositoryUrl (string, required): URL of the Git repository.

  • Common Optional Parameters:

    • analysisProfile (string, optional): e.g., "quick_scan", "deep_analysis".

    • manifestFileContent (object, optional): Content of manifest files (e.g., {"package.json": "...", "yarn.lock": "..."}) for dependency scanning.

    • options (object, optional): Advanced options (tier-dependent).

• Expected Result (result field in tool_result message - JSON stringified): A JSON object (for single file) or an array/summary (for batch/repo) containing:

  • filePath (string): Path of the scanned file.

  • scanId

  • timestamp (string): ISO 8601 timestamp.

  • status (string): e.g., "completed", "error".

  • summary (object): Counts of findings by severity (critical, high, etc.), overall safety assessment.

  • findings (array of objects): Detailed vulnerabilities. Each finding may include ruleId, analysisType, severity, message, lineStart, lineEnd, codeSnippet, remediation, cwe, owasp.

  • dependencies (object, optional): Results from dependency scanning, including vulnerable packages. (example; actual fields may vary slightly.)

3. Diagnostic Tool (e.g., ping_server)

A simple tool to verify connectivity and server responsiveness. The exact name and functionality may vary.

• Name: (e.g., ping_server, test_connection - check server_info or dashboard)

• Parameters: Typically none, or an optional message string.

• Expected Result: A simple JSON object confirming success, possibly echoing the message and providing a server timestamp.

  {
    "status": "success",
    "message": "Pong from SigilAI MCP Server!",
    "serverTime": "2023-10-27T12:00:00Z"
  }

Rate Limits

API requests and tool invocations are subject to rate limits based on your subscription tier.

• Free/Open Beta Tier: Limited requests per hour/day, suitable for evaluation.

• Pro Tier: Significantly higher limits for production use.

• Enterprise Tier: Custom high-volume limits, often with dedicated throughput.

If you exceed your rate limit, the server will typically respond with an HTTP 429 Too Many Requests status code or an MCP error message. Implement retry logic with exponential backoff in your client. Specific rate limit details are provided in your SigilAI account dashboard or plan agreement.

Error Handling

The SigilAI MCP server will return errors using standard HTTP status codes for connection-level or authentication issues, and MCP error messages for protocol or tool-level issues.

• Common HTTP Errors:

  • 401 Unauthorized: Invalid or missing API key.

  • 403 Forbidden: API key is valid but does not have permission for the requested action/tier.

  • 429 Too Many Requests: Rate limit exceeded.

  • 5xx Server Error: An unexpected error occurred on the server-side.

• MCP error Message:

  {
    "type": "error",
    "message": "A human-readable description of the error.",
    "code": "OPTIONAL_ERROR_CODE", // e.g., "INVALID_PARAMETERS", "TOOL_EXECUTION_FAILED"
    "details": { /* Optional additional error details */ }
  }

Your client should be prepared to handle these errors gracefully.

Client Libraries

SigilAI may provide official client libraries for popular programming languages (e.g., Node.js, Python) to simplify integration. These libraries typically handle:

• MCP message construction and parsing.

• SSE connection management.

• Authentication header injection.

• Convenience methods for tool calls.

Check the SigilAI developer portal or your account dashboard for available client libraries and their documentation. Using an official library is highly recommended.

---

This concludes the Technical Guide section. Next: Resources