API Endpoints

REST API endpoint reference for MCP Hub, grouped by category: public catalog, organizations, MCPs, versions, analysis, policies, and admin.

6 min read

MCP Hub exposes a RESTful API at the base URL /api/v1. All responses use application/json content type. Authentication is via Bearer token in the Authorization header (see API Authentication).

Public Endpoints

Public endpoints require no authentication but are rate-limited by IP address (15 requests/minute for anonymous users).

List MCPs

GET /api/v1/mcps

Search and browse the public MCP catalog.

Parameter	Type	Description
`query`	string	Search term (matches name, description)
`q`	string	Alias for `query`
`limit`	integer	Results per page (default: 20, max: 100)
`offset`	integer	Pagination offset (default: 0)

Response:

{
  "mcps": [
    {
      "id": "uuid",
      "name": "mcp-database-tools",
      "description": "Database access tools for Claude",
      "repo_url": "https://github.com/example/mcp-database-tools",
      "language": "TypeScript",
      "license": "MIT",
      "visibility": "public",
      "latest_version": {
        "id": "uuid",
        "visible_version": "commit-a1b2c3d-2026-01-14",
        "status": "CERTIFIED",
        "global_score": 85
      },
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": "2026-01-14T12:00:00Z"
    }
  ],
  "total": 150,
  "limit": 20,
  "offset": 0
}

Get MCP Details

GET /api/v1/mcps/{mcpId}

Returns complete metadata for a single MCP, including its latest version and snapshot summary.

List MCP Versions

GET /api/v1/mcps/{mcpId}/versions

Returns all versions of an MCP, ordered by creation date (newest first).

Parameter	Type	Description
`limit`	integer	Results per page (default: 20, max: 100)
`offset`	integer	Pagination offset (default: 0)

Get Version Details

GET /api/v1/mcps/{mcpId}/versions/{versionId}

Returns full details for a specific version, including source size, tarball URL, and SHA-256 hash.

Get Latest Snapshot

GET /api/v1/mcps/{mcpId}/versions/{versionId}/snapshot/latest

Returns the most recent security snapshot for a version, including all four scores, findings counts, and toolchain metadata.

Response:

{
  "id": "uuid",
  "version_id": "uuid",
  "global_score": 85,
  "security_score": 90,
  "supply_chain_score": 80,
  "maturity_score": 75,
  "toolchain_version": "mcp-scan:1.0.0,trivy:0.50.1",
  "scoring_version": "v2.1",
  "controls_catalog_version": "v1.4",
  "total_findings": 17,
  "critical_findings": 0,
  "high_findings": 2,
  "medium_findings": 5,
  "low_findings": 10,
  "created_at": "2026-01-14T10:00:00Z"
}

Get Control Results

GET /api/v1/mcps/{mcpId}/versions/{versionId}/controls

Returns all control check results for the latest snapshot, including pass/fail status, severity, and evidence references.

Response:

{
  "controls": [
    {
      "id": "uuid",
      "control_id": "SECRET_EXPOSED",
      "control_name": "Exposed Secrets Detection",
      "control_category": "security",
      "passed": true,
      "severity": "critical",
      "message": "No secrets detected in codebase"
    }
  ],
  "total": 25,
  "passed": 23,
  "failed": 2
}

Get Scores

GET /api/v1/mcps/{mcpId}/versions/{versionId}/scores

Returns the detailed score breakdown with per-dimension weights and sub-category scores.

Response:

{
  "global_score": 85,
  "scores": {
    "security": {
      "score": 90,
      "weight": 0.5,
      "breakdown": {
        "vulnerabilities": 95,
        "secrets": 100,
        "code_quality": 75
      }
    },
    "supply_chain": {
      "score": 80,
      "weight": 0.3,
      "breakdown": {
        "dependencies": 85,
        "licenses": 90,
        "lockfile": 65
      }
    },
    "maturity": {
      "score": 75,
      "weight": 0.2,
      "breakdown": {
        "documentation": 80,
        "tests": 70,
        "ci_cd": 75
      }
    }
  },
  "grade": "B",
  "toolchain_version": "mcp-scan:1.0.0,trivy:0.50.1",
  "scoring_version": "v2.1"
}

Organization Endpoints

Organization endpoints require authentication and appropriate organization membership.

Create Organization

POST /api/v1/orgs

Requires Enterprise plan.

{
  "name": "acme-corp",
  "slug": "acme",
  "display_name": "ACME Corporation"
}

Get Organization

GET /api/v1/orgs/{orgId}

Requires organization membership.

Invite Member

POST /api/v1/orgs/{orgId}/users/invite

Requires Admin or Owner role.

{
  "email": "[email protected]",
  "role": "MEMBER"
}

List Organization Roles

GET /api/v1/orgs/{orgId}/roles

Returns available roles and their permissions.

Area Endpoints

Area endpoints manage organizational namespaces (Enterprise only).

List Areas

GET /api/v1/orgs/{orgId}/areas

Create Area

POST /api/v1/orgs/{orgId}/areas

Requires org:edit permission.

{
  "name": "Frontend Team",
  "slug": "frontend",
  "description": "UI and design system MCPs"
}

Get Area Details

GET /api/v1/orgs/{orgId}/areas/{areaId}

Update Area

PUT /api/v1/orgs/{orgId}/areas/{areaId}

Delete Area

DELETE /api/v1/orgs/{orgId}/areas/{areaId}

List Area Members

GET /api/v1/orgs/{orgId}/areas/{areaId}/members

Add Area Member

POST /api/v1/orgs/{orgId}/areas/{areaId}/members

Remove Area Member

DELETE /api/v1/orgs/{orgId}/areas/{areaId}/members/{userId}

Update Area Member Role

PATCH /api/v1/orgs/{orgId}/areas/{areaId}/members/{userId}/role

Policy Endpoints

Policy endpoints manage governance policies (Enterprise only).

List Policies

GET /api/v1/orgs/{orgId}/policies

Create Policy

POST /api/v1/orgs/{orgId}/policies

Requires Admin or Owner role.

{
  "name": "Require Minimum Score",
  "description": "Deny MCPs with global score below 70",
  "action": "DENY",
  "target_type": "SCORE",
  "target_value": "min:70",
  "priority": 20,
  "enabled": true
}

Evaluate Policies (CI/CD)

POST /api/v1/ci/evaluate

Evaluate a list of MCPs against organization policies. Requires a service token with ci:org:* scope.

{
  "org_id": "org-uuid",
  "environment": "production",
  "mcps": [
    {"name": "mcp-database-tools", "version": "commit-a3f91c2-2026-01-14"},
    {"name": "mcp-file-system", "version": "commit-x9y8z7w-2026-01-10"}
  ]
}

Response (pass):

{
  "result": "PASS",
  "evaluated_at": "2026-01-14T12:00:00Z",
  "mcps": [
    {"name": "mcp-database-tools", "result": "ALLOWED", "global_score": 85},
    {"name": "mcp-file-system", "result": "ALLOWED", "global_score": 78}
  ]
}

Response (fail):

{
  "result": "FAIL",
  "mcps": [
    {"name": "mcp-database-tools", "result": "ALLOWED", "global_score": 85},
    {
      "name": "mcp-unsafe-example",
      "result": "DENIED",
      "global_score": 35,
      "reason": "Policy 'Require Minimum Score' denied: global score 35 < 70",
      "matched_policy": {"id": "uuid", "name": "Require Minimum Score"}
    }
  ]
}

Service Token Endpoints

Create Service Token

POST /api/v1/orgs/{orgId}/tokens

Requires Admin or Owner role.

{
  "name": "CI/CD Pipeline Token",
  "description": "Token for GitHub Actions",
  "scopes": ["read:org:acme", "ci:org:acme"],
  "expires_in_days": 365
}

The full token is returned only once in the response. Store it securely.

Audit Endpoints

List Audit Events

GET /api/v1/orgs/{orgId}/audit-events

Requires Admin or Owner role.

Parameter	Type	Description
`action`	string	Filter by action type
`actor_id`	uuid	Filter by actor
`since`	datetime	Events after this time
`limit`	integer	Results per page
`offset`	integer	Pagination offset

Report Endpoints

Generate PDF Report

POST /api/v1/orgs/{orgId}/reports

Enterprise only. Requires Admin or Owner role.

{
  "snapshot_id": "snapshot-uuid",
  "format": "PDF"
}

Returns a report ID with status PENDING. Poll or wait for the report to be generated.

Download Report

GET /api/v1/orgs/{orgId}/reports/{reportId}.pdf

Returns the PDF file when the report status is COMPLETED.

Webhook Endpoints

GitHub Webhook

POST /api/v1/webhooks/github

Verified via X-Hub-Signature-256 header (HMAC-SHA256).

GitLab Webhook

POST /api/v1/webhooks/gitlab

Verified via X-Gitlab-Token header.

Bitbucket Webhook

POST /api/v1/webhooks/bitbucket

Verified via X-Hub-Signature header (HMAC-SHA256).

Stripe Webhook

POST /api/v1/webhooks/stripe

Verified via Stripe-Signature header.

Admin Endpoints

Admin endpoints require the PLATFORM_ADMIN role.

Users

Method	Endpoint	Description
GET	`/api/v1/admin/users`	List all users (with search and filters)
GET	`/api/v1/admin/users/{userId}`	Get user details
POST	`/api/v1/admin/users`	Create a user
PUT	`/api/v1/admin/users/{userId}`	Update user details
PATCH	`/api/v1/admin/users/{userId}/plan`	Change user plan
PATCH	`/api/v1/admin/users/{userId}/role`	Assign platform role
POST	`/api/v1/admin/users/{userId}/suspend`	Suspend user
POST	`/api/v1/admin/users/{userId}/activate`	Activate user
DELETE	`/api/v1/admin/users/{userId}`	Delete user (soft)
POST	`/api/v1/admin/users/bulk/suspend`	Bulk suspend
POST	`/api/v1/admin/users/bulk/activate`	Bulk activate

Organizations

Method	Endpoint	Description
GET	`/api/v1/admin/orgs`	List all organizations
GET	`/api/v1/admin/orgs/{orgId}`	Get organization details
POST	`/api/v1/admin/orgs`	Create organization
PUT	`/api/v1/admin/orgs/{orgId}`	Update organization
PATCH	`/api/v1/admin/orgs/{orgId}/plan`	Change organization plan
POST	`/api/v1/admin/orgs/{orgId}/suspend`	Suspend organization
POST	`/api/v1/admin/orgs/{orgId}/activate`	Activate organization
DELETE	`/api/v1/admin/orgs/{orgId}`	Delete organization (soft)

MCPs

Method	Endpoint	Description
GET	`/api/v1/admin/mcps`	List all MCPs (with filters)
GET	`/api/v1/admin/mcps/{mcpId}`	Get MCP details
POST	`/api/v1/admin/mcps`	Create MCP
PUT	`/api/v1/admin/mcps/{mcpId}`	Update MCP metadata
PATCH	`/api/v1/admin/mcps/{mcpId}/category`	Assign category
PATCH	`/api/v1/admin/mcps/{mcpId}/tags`	Assign tags
POST	`/api/v1/admin/mcps/{mcpId}/featured`	Set featured status
DELETE	`/api/v1/admin/mcps/{mcpId}`	Delete MCP (hard)

Categories and Tags

Method	Endpoint	Description
GET	`/api/v1/admin/categories`	List categories
POST	`/api/v1/admin/categories`	Create category
PUT	`/api/v1/admin/categories/{id}`	Update category
DELETE	`/api/v1/admin/categories/{id}`	Delete category
GET	`/api/v1/admin/tags`	List tags
POST	`/api/v1/admin/tags`	Create tag
PUT	`/api/v1/admin/tags/{id}`	Update tag
DELETE	`/api/v1/admin/tags/{id}`	Delete tag

Audit

Method	Endpoint	Description
GET	`/api/v1/admin/audit`	Global audit log
GET	`/api/v1/admin/audit/users/{userId}`	User-specific audit
GET	`/api/v1/admin/audit/orgs/{orgId}`	Organization-specific audit

Health Endpoints

Method	Endpoint	Description
GET	`/healthz` or `/health`	Liveness probe
GET	`/readyz` or `/ready`	Readiness probe (checks DB and Redis)

Error Responses

All errors follow a consistent format:

{
  "error": "not_found",
  "message": "MCP not found",
  "code": "NOT_FOUND"
}

HTTP Code	Error	Description
400	`bad_request`	Invalid request parameters
401	`unauthorized`	Missing or invalid authentication
403	`forbidden`	Insufficient permissions
404	`not_found`	Resource not found
429	`rate_limited`	Rate limit exceeded
500	`internal_error`	Server error

OpenAPI Specification

The complete OpenAPI 3.0 specification is available in the repository at docs/openapi/v1.yaml. It provides machine-readable documentation of all endpoints, request/response schemas, and authentication requirements.