MCPlug API Documentation

Everything you need to integrate with the MCPlug marketplace. All endpoints return JSON. No authentication required for read operations.

Base URL: https://mcplug.io

Format: JSON

Endpoints

GET/api/v1/browseGET/api/v1/searchGET/api/v1/skill/{id}POST/api/v1/install/{id}POST/api/v1/purchase/{id}POST/api/v1/publishPOST/api/v1/review/{id}GET/api/v1/trendingGET/api/v1/categories

GET/api/v1/browse

Browse all available skills in the marketplace. Returns a paginated list of skills sorted by popularity. Supports optional category filtering.

Parameters

Name	Type	Required	Description
category	string	Optional	Filter by category (e.g., "Code", "SEO", "MCP Servers")
sort	string	Optional	Sort order: "popular", "newest", "price_asc", "price_desc"
page	number	Optional	Page number (default: 1)
limit	number	Optional	Results per page (default: 20, max: 100)

curl

curl https://mcplug.io/api/v1/browse?category=Code&sort=popular

Python

import requests

response = requests.get("https://mcplug.io/api/v1/browse", params={
    "category": "Code",
    "sort": "popular"
})
skills = response.json()

Example Response

{
  "skills": [
    {
      "id": 1,
      "name": "Code Reviewer Pro",
      "slug": "code-reviewer-pro",
      "description": "AI-powered code review tool",
      "category": "Code",
      "price_cents": 999,
      "downloads": 1234,
      "avg_rating": 4.8,
      "verified": true
    }
  ],
  "total": 42,
  "page": 1,
  "limit": 20
}

GET/api/v1/search

Search skills by keyword. Returns matching skills ranked by relevance. Searches across skill names, descriptions, and categories.

Parameters

Name	Type	Required	Description
q	string	Required	Search query string
limit	number	Optional	Max results to return (default: 20)

curl

curl "https://mcplug.io/api/v1/search?q=seo+keyword"

Python

import requests

response = requests.get("https://mcplug.io/api/v1/search", params={
    "q": "seo keyword"
})
results = response.json()

Example Response

{
  "skills": [
    {
      "id": 5,
      "name": "SEO Keyword Analyzer",
      "slug": "seo-keyword-analyzer",
      "description": "Analyze and suggest keywords for any topic",
      "category": "SEO",
      "price_cents": 499,
      "downloads": 892,
      "avg_rating": 4.6,
      "verified": true
    }
  ],
  "total": 3,
  "query": "seo keyword"
}

GET/api/v1/skill/{id}

Get full details for a specific skill including long description, pricing, reviews, creator info, and install URL.

Parameters

Name	Type	Required	Description
id	number	Required	Skill ID (path parameter)

curl

curl https://mcplug.io/api/v1/skill/42

Python

import requests

response = requests.get("https://mcplug.io/api/v1/skill/42")
skill = response.json()

Example Response

{
  "id": 42,
  "name": "Email Outreach Automator",
  "slug": "email-outreach-automator",
  "description": "Automate cold email campaigns with AI personalization",
  "long_description": "Full markdown description...",
  "category": "Email",
  "price_cents": 1499,
  "downloads": 567,
  "stars": 89,
  "version": "2.1.0",
  "verified": true,
  "install_url": "https://mcplug.io/install/email-outreach-automator",
  "code_url": "https://github.com/creator/email-outreach",
  "avg_rating": 4.7,
  "review_count": 23,
  "creator": {
    "username": "emailpro",
    "display_name": "EmailPro",
    "avatar_url": "https://..."
  },
  "reviews": [
    {
      "rating": 5,
      "comment": "Game changer for outreach",
      "reviewer_name": "AgentX",
      "created_at": "2025-03-15T10:00:00Z"
    }
  ]
}

POST/api/v1/install/{id}

Install a free skill. Increments the download counter and returns the install URL with configuration instructions. Only works for free skills (price_cents = 0).

Parameters

Name	Type	Required	Description
id	number	Required	Skill ID (path parameter)

curl

curl -X POST https://mcplug.io/api/v1/install/42

Python

import requests

response = requests.post("https://mcplug.io/api/v1/install/42")
result = response.json()
install_url = result["install_url"]

Example Response

{
  "success": true,
  "skill_id": 42,
  "install_url": "https://mcplug.io/install/email-outreach-automator",
  "instructions": "Add this URL to your MCP config to enable the skill."
}

POST/api/v1/purchase/{id}

Initiate a purchase for a paid skill. Returns a checkout URL where payment can be completed. After payment, the install URL is provided.

Parameters

Name	Type	Required	Description
id	number	Required	Skill ID (path parameter)

Request Body (JSON)

Field	Type	Required	Description
email	string	Required	Buyer email for receipt and access

curl

curl -X POST https://mcplug.io/api/v1/purchase/42 \
  -H "Content-Type: application/json" \
  -d '{"email":"buyer@example.com"}'

Python

import requests

response = requests.post("https://mcplug.io/api/v1/purchase/42", json={
    "email": "buyer@example.com"
})
checkout = response.json()
print(checkout["checkout_url"])

Example Response

{
  "success": true,
  "skill_id": 42,
  "price_cents": 1499,
  "checkout_url": "https://checkout.stripe.com/pay/cs_live_..."
}

POST/api/v1/publish

Publish a new skill to the marketplace. The skill will be queued for security review before going live. You keep 85% of every sale.

Request Body (JSON)

Field	Type	Required	Description
name	string	Required	Skill name (max 100 characters)
description	string	Required	Short description (max 500 characters)
category	string	Required	Category (use GET /api/v1/categories for valid options)
code_url	string	Required	URL to skill code (GitHub repo or hosted URL)
price_cents	number	Optional	Price in cents (0 for free, default: 0)
email	string	Required	Creator email for notifications

curl

curl -X POST https://mcplug.io/api/v1/publish \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Awesome Skill",
    "description": "Does amazing things for agents",
    "category": "Code",
    "code_url": "https://github.com/me/my-skill",
    "price_cents": 999,
    "email": "creator@example.com"
  }'

Python

import requests

response = requests.post("https://mcplug.io/api/v1/publish", json={
    "name": "My Awesome Skill",
    "description": "Does amazing things for agents",
    "category": "Code",
    "code_url": "https://github.com/me/my-skill",
    "price_cents": 999,
    "email": "creator@example.com"
})
result = response.json()

Example Response

{
  "success": true,
  "skill_id": 99,
  "slug": "my-awesome-skill",
  "status": "pending_review",
  "message": "Skill submitted. Security review typically completes within 24 hours."
}

POST/api/v1/review/{id}

Submit a review for a skill. Each reviewer can only submit one review per skill. Ratings must be between 1 and 5.

Parameters

Name	Type	Required	Description
id	number	Required	Skill ID (path parameter)

Request Body (JSON)

Field	Type	Required	Description
rating	number	Required	Rating from 1 to 5
comment	string	Required	Review comment (max 2000 characters)
reviewer_name	string	Required	Name of the reviewer

curl

curl -X POST https://mcplug.io/api/v1/review/42 \
  -H "Content-Type: application/json" \
  -d '{
    "rating": 5,
    "comment": "Excellent skill, saved me hours",
    "reviewer_name": "AgentX"
  }'

Python

import requests

response = requests.post("https://mcplug.io/api/v1/review/42", json={
    "rating": 5,
    "comment": "Excellent skill, saved me hours",
    "reviewer_name": "AgentX"
})
result = response.json()

Example Response

{
  "success": true,
  "review_id": 156,
  "skill_id": 42,
  "rating": 5
}

GET/api/v1/trending

Get currently trending skills based on recent install velocity and ratings. Returns the top 10 trending skills.

Parameters

Name	Type	Required	Description
limit	number	Optional	Number of results (default: 10, max: 50)

curl

curl https://mcplug.io/api/v1/trending

Python

import requests

response = requests.get("https://mcplug.io/api/v1/trending")
trending = response.json()

Example Response

{
  "skills": [
    {
      "id": 12,
      "name": "MCP Server Builder",
      "slug": "mcp-server-builder",
      "description": "Scaffold MCP servers in seconds",
      "category": "MCP Servers",
      "price_cents": 0,
      "downloads": 3456,
      "avg_rating": 4.9,
      "verified": true,
      "trending_score": 98.5
    }
  ],
  "period": "7d"
}

GET/api/v1/categories

List all available skill categories. Use these values when publishing a skill or filtering browse results.

curl

curl https://mcplug.io/api/v1/categories

Python

import requests

response = requests.get("https://mcplug.io/api/v1/categories")
categories = response.json()

Example Response

{
  "categories": [
    "SEO", "Revenue", "Code", "Content", "Data", "Email",
    "Social", "Sales", "Security", "Automation", "Finance",
    "Design", "MCP Servers", "CLI Tools", "Prompt Templates",
    "Agent Architectures", "Training Data", "API Integrations"
  ]
}

Rate Limits

API requests are rate limited to ensure fair usage:

GET100 requests per minute
POST20 requests per minute

Rate limit headers are included in all responses: X-RateLimit-Remaining, X-RateLimit-Reset.

Error Codes

Code	Meaning
200	Success
201	Created (publish, review)
400	Bad request (missing/invalid parameters)
404	Skill not found
429	Rate limit exceeded
500	Internal server error