>_Skillful
Need help with advanced AI agent engineering?Contact FirmAdapt

API Documentation >_

Access the Skillful.sh database programmatically. Browse, search, and filter MCP servers, skills, and agents with a simple REST API. All endpoints return JSON with CORS enabled.

Base URL

https://skillful.sh

Authentication

Not required for public endpoints

Rate Limits

20 req/min (unauth)

Endpoints

Rate Limiting

All API endpoints are rate-limited per IP address. Unauthenticated requests are capped at 20 requests per minute and 500 requests per day. Authenticated requests have higher limits. If you exceed these limits, you will receive a 429 response.

The response will include Retry-After and X-RateLimit-* headers indicating when you can resume making requests.

Endpoints

GET/api/v1/items

List, filter, and search items (MCP servers, skills, agents) with pagination and sorting. Returns a paginated array of items with summary fields.

Query Parameters

typestring
Filter by item type: mcp_server | skill | agent
categorystring
Filter by category name (e.g. "File Systems", "Databases")
searchstring
Full-text search across name, description, and tags
directorystring
Filter by directory slug (items listed in that directory)
idsstring
Comma-separated item IDs to fetch specific items
sortstring
Sort order: recent (default) | stars | directoryCount | name
pagenumber
Page number, starting from 1 (default: 1)
limitnumber
Items per page, 1–100 (default: 20)

Example Request

curl "https://skillful.sh/api/v1/items?type=mcp_server&sort=stars&limit=5"

Example Response

{
  "items": [
    {
      "_id": "664a1f...",
      "slug": "filesystem-mcp",
      "name": "Filesystem MCP",
      "type": "mcp_server",
      "description": "MCP server for local filesystem operations",
      "category": "File Systems",
      "tags": ["filesystem", "files", "mcp"],
      "author": "modelcontextprotocol",
      "repositoryUrl": "https://github.com/modelcontextprotocol/servers",
      "license": "MIT",
      "stats": {
        "githubStars": 1250,
        "githubForks": 180,
        "npmWeeklyDownloads": 5400,
        "directoryCount": 12,
        "lastCommitDate": "2026-03-08T14:22:00Z",
        "contributorCount": 25
      },
      "securityScore": {
        "grade": "A",
        "overallScore": 92
      },
      "isVerified": true,
      "isFeatured": false,
      "createdAt": "2025-11-15T10:00:00Z",
      "updatedAt": "2026-03-10T08:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 5,
    "total": 4820,
    "totalPages": 964
  }
}
GET/api/v1/items/:slug

Get full details for a single item by its URL slug. Returns all fields including the full description, security analysis details, and populated directory listing data.

Path Parameters

slugstringrequired
The item's URL-friendly identifier

Example Request

curl "https://skillful.sh/api/v1/items/filesystem-mcp"

Example Response

{
  "_id": "664a1f...",
  "slug": "filesystem-mcp",
  "name": "Filesystem MCP",
  "type": "mcp_server",
  "description": "MCP server for local filesystem operations",
  "longDescription": "A full-featured MCP server that provides...",
  "category": "File Systems",
  "tags": ["filesystem", "files", "mcp"],
  "author": "modelcontextprotocol",
  "repositoryUrl": "https://github.com/modelcontextprotocol/servers",
  "license": "MIT",
  "stats": {
    "githubStars": 1250,
    "githubForks": 180,
    "npmWeeklyDownloads": 5400,
    "directoryCount": 12,
    "lastCommitDate": "2026-03-08T14:22:00Z",
    "contributorCount": 25
  },
  "securityScore": {
    "grade": "A",
    "overallScore": 92,
    "staticAnalysis": { ... },
    "aiAnalysis": { ... }
  },
  "directoryListings": [
    {
      "directorySlug": "smithery",
      "directoryId": {
        "_id": "...",
        "name": "Smithery",
        "slug": "smithery",
        "logo": "https://...",
        "url": "https://smithery.ai"
      },
      "listedAt": "2025-12-01T00:00:00Z",
      "externalUrl": "https://smithery.ai/server/filesystem-mcp"
    }
  ],
  "isVerified": true,
  "isFeatured": false,
  "createdAt": "2025-11-15T10:00:00Z",
  "updatedAt": "2026-03-10T08:30:00Z"
}
Note: The detail endpoint returns the full item including longDescription, full securityScore with analysis details, and populated directoryListings with directory metadata. The list endpoint omits these heavy fields for performance.
GET/api/v1/items/facets

Get available filter values with counts for building filter UIs. Returns categories, licenses, security grades, and star/download distributions for the given item type.

Query Parameters

typestring
Item type to get facets for (default: mcp_server)

Example Request

curl "https://skillful.sh/api/v1/items/facets?type=mcp_server"

Example Response

{
  "type": "mcp_server",
  "totalCount": 4820,
  "facets": {
    "categories": [
      { "value": "Developer Tools", "count": 620 },
      { "value": "Databases", "count": 415 },
      { "value": "File Systems", "count": 380 }
    ],
    "licenses": [
      { "value": "MIT", "count": 2100 },
      { "value": "Apache-2.0", "count": 890 }
    ],
    "grades": [
      { "value": "A", "count": 1200 },
      { "value": "B", "count": 1850 },
      { "value": "C", "count": 980 }
    ],
    "stars": {
      "min": 1,
      "max": 45000,
      "avg": 320,
      "count": 3200
    },
    "downloads": {
      "min": 1,
      "max": 500000,
      "avg": 2400,
      "count": 1800
    }
  }
}
GET/api/v1/directories

List all indexed directories and data sources. Requires admin authentication via x-api-key header.

Admin Only: This endpoint requires authentication. Pass your admin API key in the x-api-key header. Contact us for API key access.

Headers

x-api-keystringrequired
Admin API key

Query Parameters

sortstring
Sort order: name (default) | itemCount
allboolean
Set to true to include inactive directories

Example Request

curl -H "x-api-key: YOUR_API_KEY" \
  "https://skillful.sh/api/v1/directories?sort=itemCount"

Example Response

{
  "directories": [
    {
      "_id": "...",
      "name": "Smithery",
      "slug": "smithery",
      "url": "https://smithery.ai",
      "logo": "https://...",
      "itemCount": 1850,
      "isActive": true,
      "lastCrawledAt": "2026-03-12T06:00:00Z"
    }
  ]
}

Error Handling

All errors return a JSON object with an error field.

Error Response Format

{
  "error": "Item not found"
}
200Success
400Bad Request: Missing or invalid parameters
401Unauthorized: Admin authentication required
404Not Found: The requested item does not exist
429Too Many Requests: Rate limit exceeded
500Internal Server Error: Something went wrong on our end

Item Schema

Each item in the database has the following structure. Fields marked with * are only returned by the detail endpoint.

{
  "_id":             "string",        // MongoDB ObjectId
  "slug":            "string",        // URL-friendly identifier
  "name":            "string",        // Display name
  "type":            "string",        // "mcp_server" | "skill" | "agent"
  "description":     "string",        // Short description
  "longDescription": "string",        // * Full markdown description
  "category":        "string",        // Category name
  "tags":            ["string"],      // Array of tag strings
  "author":          "string",        // Author or org name
  "repositoryUrl":   "string",        // GitHub/GitLab URL
  "license":         "string",        // SPDX license identifier
  "stats": {
    "githubStars":        0,          // GitHub star count
    "githubForks":        0,          // GitHub fork count
    "npmWeeklyDownloads": 0,          // npm weekly downloads
    "directoryCount":     0,          // Number of directories listing this item
    "lastCommitDate":     "ISO 8601", // Most recent commit
    "contributorCount":   0           // Number of contributors
  },
  "securityScore": {
    "grade":          "string",       // Letter grade: A+, A, B, C, D, F
    "overallScore":   0,              // Numeric score 0-100
    "staticAnalysis": { ... },        // * Static analysis details
    "aiAnalysis":     { ... }         // * AI-powered code review details
  },
  "directoryListings": [              // * Populated on detail endpoint
    {
      "directorySlug": "string",
      "directoryId":   { ... },       // Populated directory object
      "listedAt":      "ISO 8601",
      "externalUrl":   "string"
    }
  ],
  "isVerified":  false,               // Verified by Skillful.sh team
  "isFeatured":  false,               // Featured item
  "status":      "string",            // "active" | "removed" | "pending_review"
  "createdAt":   "ISO 8601",
  "updatedAt":   "ISO 8601"
}

Pagination

All list endpoints return a pagination object alongside the results. Use the page and limit query parameters to navigate through results.

{
  "pagination": {
    "page": 1,        // Current page number
    "limit": 20,      // Items per page
    "total": 4820,    // Total matching items
    "totalPages": 241 // Total number of pages
  }
}

CORS

All API endpoints support Cross-Origin Resource Sharing (CORS). You can call the API directly from browser-based applications. Each endpoint responds to OPTIONS preflight requests with the appropriate headers.

Start Building

The API is free and open for public use. Explore the ecosystem programmatically.

Browse MCP ServersAbout Skillful.sh