MCP Security Score
Documentation

API Endpoints Reference

Complete documentation for all MCP Security Score API endpoints.

POST /api/v1/scan

Create a new scan for a GitHub repository.

Request

POST https://mcpscanner.com/api/v1/scan
Authorization: Bearer mcp_sk_xxx
Content-Type: application/json

Body Parameters

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | url | string | Yes | GitHub repository URL | | forceRefresh | boolean | No | Bypass 24-hour cache (default: false) | | enableAI | boolean | No | Enable AI analysis (default: true) |

Example Request

{
  "url": "https://github.com/owner/repo",
  "forceRefresh": false,
  "enableAI": true
}

Response

Success (201 Created)

{
  "id": "scan_abc123xyz",
  "status": "pending",
  "url": "https://github.com/owner/repo",
  "cached": false
}

Cached Result (200 OK)

If a recent scan exists and forceRefresh is false:

{
  "id": "scan_existing123",
  "status": "complete",
  "url": "https://github.com/owner/repo",
  "cached": true,
  "score": 85,
  "grade": "B"
}

Error Responses

| Status | Code | Description | |--------|------|-------------| | 400 | INVALID_URL | Invalid GitHub URL format | | 401 | UNAUTHORIZED | Missing or invalid API key | | 403 | PRIVATE_REPO | Repository is private | | 404 | REPO_NOT_FOUND | Repository doesn't exist | | 429 | RATE_LIMIT_EXCEEDED | Rate limit exceeded |

GET /api/v1/scan/:id

Get the status and results of a scan.

Request

GET https://mcpscanner.com/api/v1/scan/{scan_id}
Authorization: Bearer mcp_sk_xxx

Response - Pending Scan

{
  "id": "scan_abc123xyz",
  "status": "analyzing",
  "url": "https://github.com/owner/repo",
  "createdAt": "2024-01-15T10:30:00Z",
  "startedAt": "2024-01-15T10:30:05Z"
}

Response - Complete Scan

{
  "id": "scan_abc123xyz",
  "status": "complete",
  "url": "https://github.com/owner/repo",
  "score": 85,
  "grade": "B",
  "safetyScore": 82,
  "safetyGrade": "B",
  "findings": [
    {
      "id": "finding_1",
      "checkId": "rce-eval",
      "name": "eval() Usage",
      "severity": "critical",
      "category": "rce",
      "file": "src/utils/dynamic.ts",
      "line": 42,
      "code": "const result = eval(input)",
      "message": "Direct use of eval() detected",
      "remediation": "Use JSON.parse() or a safe evaluator"
    }
  ],
  "categoryScores": {
    "rce": 60,
    "secrets": 100,
    "network": 95,
    "filesystem": 100,
    "supplyChain": 85,
    "mcp": 75,
    "dataHandling": 90,
    "auth": 100
  },
  "aiAnalysis": {
    "behavior": {
      "summary": "MCP server for file operations",
      "capabilities": ["read files", "write files"],
      "risks": ["Broad file access permissions"],
      "trustScore": 75,
      "recommendations": ["Limit file access to specific directories"]
    },
    "promptInjection": {
      "detected": false,
      "severity": null,
      "locations": []
    },
    "reportSummary": {
      "executiveSummary": "Good security posture with some concerns...",
      "keyFindings": ["eval() usage in dynamic.ts"],
      "riskAssessment": "Medium risk",
      "prioritizedActions": ["Remove eval() usage", "Add input validation"]
    }
  },
  "filesScanned": 45,
  "scanDurationMs": 12345,
  "createdAt": "2024-01-15T10:30:00Z",
  "completedAt": "2024-01-15T10:30:30Z"
}

Scan Statuses

| Status | Description | |--------|-------------| | pending | Scan queued | | cloning | Cloning repository | | analyzing | Running security checks | | scoring | Calculating scores | | complete | Scan finished successfully | | failed | Scan failed |

Error Responses

| Status | Code | Description | |--------|------|-------------| | 400 | INVALID_SCAN_ID | Invalid scan ID format | | 401 | UNAUTHORIZED | Missing or invalid API key | | 404 | SCAN_NOT_FOUND | Scan doesn't exist |

GET /api/v1/scans

List scans for your account.

Request

GET https://mcpscanner.com/api/v1/scans?limit=20&offset=0
Authorization: Bearer mcp_sk_xxx

Query Parameters

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | limit | integer | 20 | Results per page (1-100) | | offset | integer | 0 | Pagination offset | | status | string | - | Filter by status |

Response

{
  "scans": [
    {
      "id": "scan_abc123",
      "status": "complete",
      "url": "https://github.com/owner/repo1",
      "score": 85,
      "grade": "B",
      "safetyScore": 82,
      "safetyGrade": "B",
      "findingsCount": 5,
      "createdAt": "2024-01-15T10:30:00Z",
      "completedAt": "2024-01-15T10:30:30Z"
    },
    {
      "id": "scan_def456",
      "status": "complete",
      "url": "https://github.com/owner/repo2",
      "score": 92,
      "grade": "A",
      "safetyScore": 90,
      "safetyGrade": "A",
      "findingsCount": 2,
      "createdAt": "2024-01-14T15:00:00Z",
      "completedAt": "2024-01-14T15:00:25Z"
    }
  ],
  "pagination": {
    "total": 50,
    "limit": 20,
    "offset": 0,
    "hasMore": true
  }
}

Rate Limit Headers

All responses include rate limit information:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 2024-01-16T00:00:00Z

Next Steps