> ## Documentation Index
> Fetch the complete documentation index at: https://docs.enkryptai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Hub

# MCP Hub API Documentation

Welcome to the MCP Hub API documentation. This guide describes how to scan MCP (Model Context Protocol) servers for security vulnerabilities — both source-based scans (a GitHub repo or npm package) and hosted scans (a live, running MCP server).

## Purpose

MCP Hub is the Enkrypt vulnerability scanner for MCP servers. Two scan flows are supported:

* **Source scans** clone a GitHub repository or fetch an npm package, discover the MCP server's tools/resources/prompts statically, and analyze the metadata for known vulnerability classes (prompt injection, data exfiltration, shadow tools, and more).
* **Hosted scans** connect to a running MCP server over its live transport (SSE, HTTP, etc.), perform the same discovery against the server's actual tool surface, and run the same analysis. Hosted scans accept a full authentication config (API key, bearer token, OAuth 2.0, custom headers, or mTLS) so the scanner can authenticate against the target server.

Every scan produces a `job_id`. Scans run asynchronously in the background — poll the status endpoint until the job is `completed`, then fetch the full results.

## Offered APIs

Our API suite includes the following endpoints:

* **scan**: Start a new source-based scan from a GitHub URL or npm package. Returns a `job_id`.

* **hosted-scan**: Start a new hosted-server scan against a live MCP endpoint with optional authentication.

* **hosted-scan-from-config**: Submit a Claude/Cursor-style `mcpServers` config JSON; one hosted scan job is created per server entry.

* **get-status**: Poll a scan job's status, including per-tool progress and overall severity once analysis is in flight.

* **get-results**: Fetch the complete scan output (vulnerabilities, tools scanned, scan metadata) once the job is `completed`.

* **list-scans**: List scan jobs across both scan types with filters for visibility, status, repo name, and **opaque cursor pagination** (see [Pagination](#pagination) below).

* **dashboard-stats**: Fetch aggregate scan statistics across the hub — totals (servers/tools scanned, vulnerabilities), the severity breakdown, and the most common vulnerability types.

* **usage**: Self-service usage insights for your organization — call totals, per-endpoint and per-project breakdowns, the top endpoints, an HTTP status-class split, and a daily time-series over a chosen window. Returns aggregate counts only (no raw data), and is restricted to the organization owner or an admin.

<Note>
  The scan **retrieval** endpoints — **get-status**, **get-results**, **list-scans**, **dashboard-stats**, and **usage** (all the GET endpoints) — are an **enterprise data-license feature**. Your organization must have MCP Hub API access enabled by Enkrypt, otherwise these endpoints return `403 Forbidden`. The **usage** endpoint additionally requires the caller to be the organization owner or an admin, and is rate-limited. Submitting scans (the POST endpoints) is open to all authenticated callers. Contact [support@enkryptai.com](mailto:support@enkryptai.com) to enable access.
</Note>

## Rate limits

The gated MCP Hub GET endpoints are rate-limited **per API key**. The **usage** endpoint has its own dedicated limit, separate from your account's general API limits:

| Endpoint                                             | Limit (per API key)                                            |
| ---------------------------------------------------- | -------------------------------------------------------------- |
| **usage**                                            | **2 / second**, **20 / minute**, **120 / hour**, **500 / day** |
| get-status, get-results, list-scans, dashboard-stats | Your account's standard API rate limits                        |

These usage-endpoint limits apply on **every plan, including enterprise**. When a limit is exceeded the API returns `429 Too Many Requests` with `RateLimit-*` and `Retry-After` response headers indicating when to retry. Because results are also cached for a few minutes, polling for dashboards stays comfortably within these limits.

## Pagination

`GET /mcp-hub/scans` uses **opaque cursor pagination**. Each response includes a `next_cursor` string; pass it back verbatim as the `cursor` query parameter on the next request to fetch the next page:

```http theme={"system"}
GET /mcp-hub/scans?limit=20                       # first page
GET /mcp-hub/scans?limit=20&cursor=<next_cursor>  # subsequent pages
```

When `next_cursor` is `null` you have reached the end of the result set.

The cursor is a base64url string — **treat it as opaque** and round-trip verbatim. By default `total` is omitted to keep page fetches constant-time regardless of depth — pass `?include_total=true` if your UI needs an "X of N" counter.

## Public vs. Private Scans

Both scan-creation endpoints accept `is_private`:

* **Public scans** (`is_private: false`, the default) are visible across the platform and contribute to community/leaderboard data.
* **Private scans** (`is_private: true`) are scoped to your account. Status and results endpoints will return `403 Forbidden` if the calling key does not own the private job.

## Required Headers

* **`apikey`** (or `api_key`): API key for authentication. Required on every call.

User identity (org, user, project) is inferred from the API key — you do not need to pass these as request fields.

## Obtaining an API Key

To get started with the MCP Hub API, you need to obtain an API key. Follow these steps:

1. **Login**: Access your account at [app.enkryptai.com](https://app.enkryptai.com).
2. **Get API Key**: Navigate to the API section to get your unique API key.
3. **Authentication**: Use this API key in the `apikey` header of your API calls.

Let's ensure safer AI together!