# AICLUDE TOUCHSTONE (Skill & MCP Safety Registry) — Full API Reference

> Complete API documentation for AI agents, MCP servers, and programmatic integrations.

## Base URL

https://vs.aiclude.com/api

## Authentication

Most read endpoints require no authentication. Write operations and external integrations use different auth methods:

### 1. Bearer API Key (write operations)

```
Authorization: Bearer <API_KEY>
```

### 2. HMAC Signature (MCP/Skill/CI integrations via /api/v1/)

```
X-ASVS-Source: mcp | skill | cli | ci
X-ASVS-Timestamp: <unix_seconds>
X-ASVS-Signature: <hmac_sha256>
```

Signature is computed as HMAC-SHA256 over `asvs:{source}:{name}:{minuteSeed}` with a time-derived key using salt `aiclude-vs`. Allows +/-2 minute drift.

### 3. Rate Limits (external API)

- 30 requests/minute per IP
- 5 write requests/minute per IP
- 300 requests/minute global

---

## Targets

### GET /api/targets

List all scanned targets.

Query parameters:
- `type` — Filter: mcp-server, skill, plugin
- `riskLevel` — Filter: CRITICAL, HIGH, MEDIUM, LOW, INFO
- `source` — Filter: npm, github, smithery, glama, mcp-registry, etc.
- `search` — Full-text search on name/description
- `limit` — Page size (default 20, max 100)
- `offset` — Pagination offset
- `sort` — Sort field: name, riskLevel, lastScanned, score
- `order` — asc or desc

Response:
```json
{
  "targets": [
    {
      "id": "uuid",
      "canonicalName": "github:owner/repo",
      "displayName": "My MCP Server",
      "type": "mcp-server",
      "description": "...",
      "descriptionKo": "...",
      "descriptionJa": "...",
      "descriptionEn": "...",
      "author": "owner",
      "repositoryUrl": "https://github.com/owner/repo",
      "npmPackage": "@scope/package",
      "riskLevel": "MEDIUM",
      "score": 65,
      "lastScannedAt": "2026-04-15T20:00:00Z",
      "sources": ["npm", "github"]
    }
  ],
  "total": 1234,
  "limit": 20,
  "offset": 0
}
```

### GET /api/targets/:id

Full target detail with latest report and source registry info.

### GET /api/targets/:id/history

Scan history for a target. Query: `limit`, `offset`.

---

## Reports

### GET /api/reports

List all security reports.

Query parameters: `severity`, `type`, `search`, `limit`, `offset`, `sort`, `order`.

### GET /api/reports/:id

Full report with vulnerability list, engine results, and score breakdown.

Response:
```json
{
  "report": {
    "id": "uuid",
    "targetName": "...",
    "scanDate": "2026-04-15T20:00:00Z",
    "overallRiskLevel": "MEDIUM",
    "overallScore": 65,
    "summary": {
      "totalVulnerabilities": 12,
      "bySeverity": { "CRITICAL": 0, "HIGH": 2, "MEDIUM": 5, "LOW": 3, "INFO": 2 }
    },
    "engineResults": [
      {
        "engine": "sast",
        "vulnerabilities": [
          {
            "id": "vuln-id",
            "title": "Command Injection",
            "severity": "HIGH",
            "category": "injection",
            "confidence": 0.9,
            "location": { "file": "src/index.ts", "line": 42 },
            "remediation": "Use execFile instead of exec"
          }
        ]
      }
    ]
  }
}
```

### GET /api/reports/:id/download/:format

Download report as `json` or `html` file.

---

## Statistics

### GET /api/stats

Dashboard statistics.

Response:
```json
{
  "totalTargets": 5000,
  "totalScans": 12000,
  "vulnerabilityBreakdown": { "CRITICAL": 50, "HIGH": 200, "MEDIUM": 800 },
  "recentScans": [...]
}
```

### GET /api/stats/safe-picks

Recommended safe targets. Query: `limit`.

### GET /api/stats/threat-categories

AI Agent threat category breakdown (tool-poisoning, exfiltration, etc.).

### GET /api/stats/live

Real-time scan progress (5s cache). For polling current scan status.

### GET /api/ranking

Risk ranking of all targets. Supports same filters as /api/targets.

### GET /api/ranking/stats

Ecosystem-wide statistics.

---

## Scan (Frontend-facing)

### POST /api/scan/search

Search for a target in DB first, then fallback to live registry search.

Request:
```json
{
  "query": "filesystem mcp server",
  "type": "mcp-server",
  "limit": 10
}
```

### POST /api/scan/request

Request a priority scan for a target. Returns 202 Accepted.

Request:
```json
{
  "name": "my-mcp-server",
  "repositoryUrl": "https://github.com/owner/repo",
  "npmPackage": "@scope/package",
  "type": "mcp-server"
}
```

Response:
```json
{ "jobId": "uuid", "status": "pending" }
```

### GET /api/scan/status/:jobId

Poll scan job status.

Response:
```json
{
  "jobId": "uuid",
  "status": "completed",
  "targetId": "uuid",
  "reportId": "uuid"
}
```

---

## External Integration API (MCP/Skill/CI)

For programmatic integrations. Requires HMAC signature auth.

### POST /api/v1/scan/lookup

Core endpoint. Search existing results or request a new scan.

Request:
```json
{
  "name": "my-mcp-server",
  "type": "mcp-server",
  "repositoryUrl": "https://github.com/owner/repo"
}
```

Response (found):
```json
{
  "status": "found",
  "target": { ... },
  "report": { ... },
  "summary": "..."
}
```

Response (scanning):
```json
{
  "status": "scanning",
  "jobId": "uuid",
  "message": "Scan in progress"
}
```

### GET /api/v1/scan/status/:jobId

Job status with full report on completion.

### GET /api/v1/scan/result/:targetId

Latest scan result for a target.

---

## MCP Server Tool

The AICLUDE TOUCHSTONE MCP server exposes one tool:

### security_scan

Scan an MCP server or skill for security vulnerabilities.

Parameters:
- `name` (string, required) — Target name
- `type` (string, optional) — "mcp-server" or "skill"
- `description` (string, optional) — Target description
- `repository_url` (string, optional) — GitHub/GitLab URL
- `npm_package` (string, optional) — npm package name

Returns: Full security report in markdown format with risk level, score, vulnerability details, and remediation advice.

---

## 7 Scan Engines

| Engine | What it detects |
|--------|----------------|
| SAST | Code injection, hardcoded secrets, unsafe eval, weak crypto |
| SCA | Known CVEs in dependencies, typosquatting packages, unpinned versions |
| Tool Analyzer | MCP tool poisoning, shadowing, rug-pull patterns |
| DAST | SQL/Command/XSS injection via parameter fuzzing |
| Permission Checker | Excessive filesystem/network/process permissions |
| Behavior Monitor | Runtime anomalies, suspicious network calls, data exfiltration |
| Malware Detector | Backdoors, crypto miners, ransomware signatures, high-entropy blobs |

---

## Risk Score

0-100 scale. Higher = safer.

| Score | Level |
|-------|-------|
| 0-20 | CRITICAL |
| 21-40 | HIGH |
| 41-60 | MEDIUM |
| 61-80 | LOW |
| 81-100 | INFO (safe) |