MCP Reference

Skills Hub exposes an MCP (Model Context Protocol) server that IDEs connect to over Streamable HTTP. This reference covers authentication, available tools, and integration examples.

On this page

Authentication

All MCP requests require a Bearer token in the Authorization header. Generate access keys from Settings → Access Keys in the dashboard.

Authorization: Bearer sk_live_your_access_key_here

Keys start with sk_live_ for production. Requests without a valid key receive an error response.

Scope	Permissions
`registry:read`	Discover, search, and read skill content and files
`registry:write`	Everything in `registry:read` plus publish and update skills

Security note

Access keys are hashed before storage. The plaintext key is shown only once at creation time. Rotate compromised keys immediately via the dashboard.

MCP Endpoint

The MCP server is available at the following URL via Streamable HTTP transport:

https://skillshub.dev/api/mcp

Any MCP-compatible IDE or client can connect by configuring this URL and your access key. The server implements the Model Context Protocol specification.

Rate Limits

Rate limits are applied per access key and reset daily at midnight UTC.

Plan	MCP Calls / Day
Free	1,000
Business	50,000
Enterprise	Unlimited

MCP Tools

The following tools are available through the MCP server. They follow the agentskills.io progressive disclosure model: lightweight discovery first, full content on activation, supporting files on demand.

tooldiscover_skills

Tier 1 — Discovery

Returns a lightweight list of all skills available to the authenticated user. Designed to be called at IDE startup. Each skill entry is approximately 100 tokens, keeping context budgets small.

Parameters

None

Returns

{
  "skills": [
    {
      "owner": "acme",
      "name": "code-review",
      "description": "Review code for bugs...",
      "compatibility": "cursor claude-code",
      "visibility": "global"
    }
  ],
  "count": 1
}

toolsearch_skills

Tier 1 — Discovery

Full-text search across skill names and descriptions. Supports pagination via limit and offset parameters.

Parameters

Parameter	Type	Description
`query`	string	Search query text (required)
`visibility`	string	`all` (default), `global`, or `private`
`limit`	integer	Max results, 1-100 (default: 20)
`offset`	integer	Pagination offset (default: 0)

toolget_skill

Tier 2 — Activation

Returns full metadata for a specific skill including description, version, frontmatter fields, and the list of supporting files. Use the owner/name format to identify the skill.

Parameters

Parameter	Type	Description
`owner`	string	Skill owner (account slug)
`name`	string	Skill name

Returns

{
  "name": "code-review",
  "owner": "acme",
  "description": "Review code for bugs...",
  "visibility": "global",
  "version": "1.2.0",
  "license": "MIT",
  "compatibility": "cursor claude-code",
  "files": [
    { "path": "references/style-guide.md", "size": 2048, "contentType": "text/markdown" }
  ],
  "stats": { "activations": 1250, "rating": 4.8 }
}

toolget_skill_content

Tier 2 — Activation

Returns the full SKILL.md content including frontmatter and instructions. This is the primary tool for activating a skill — the agent injects the returned content into its context.

Parameters

Parameter	Type	Description
`owner`	string	Skill owner (account slug)
`name`	string	Skill name

Returns

Raw SKILL.md text (frontmatter + markdown body). Calling this tool logs an activation event.

toolget_skill_file

Tier 3 — On-demand

Fetches an individual supporting file from a skill. Use this when the SKILL.md body references a file path (e.g. scripts/extract.py). Text files are returned as plain text; binary files as base64-encoded JSON.

Parameters

Parameter	Type	Description
`owner`	string	Skill owner (account slug)
`name`	string	Skill name
`path`	string	Relative file path (e.g. `scripts/extract.py`)

tooladd_skill

Requires registry:write

Adds a new skill or updates an existing one in your account. Skills are private by default. Creates the skill if it does not exist, or saves a new version if it does.

Parameters

Parameter	Type	Description
`skillMdContent`	string	Full SKILL.md content with frontmatter (required)
`versionLabel`	string	Semantic version label (default: `"1.0"`)
`changelog`	string	Optional changelog entry
`files`	array	Optional supporting files, each with `path` and base64-encoded `content`. Total limit: 5 MB.

Error Responses

When a tool encounters an error, it returns a JSON string with an error field describing the issue.

{ "error": "Skill not found" }

Common Errors

Error	Description
`Unauthorized`	Missing or invalid access key
`Insufficient permissions`	Valid key but missing the required scope (e.g. `registry:write`)
`Skill not found`	Skill does not exist or is not visible to your account
`SKILL.md validation failed`	Published content fails spec validation (details in response)
`File not found`	Requested supporting file path does not exist in the skill

IDE Integration Examples

Below are examples showing how IDEs connect to Skills Hub and follow the progressive disclosure flow.

Progressive disclosure flow

Discovery — IDE calls discover_skills at startup (~100 tokens per skill)
Activation — Agent matches a task, calls get_skill_content (<5,000 tokens)
Execution — Agent requests supporting files on-demand via get_skill_file

Claude Code

Add Skills Hub as a remote MCP server:

claude mcp add --transport http skillshub \
  https://skillshub.dev/api/mcp \
  --header "Authorization: Bearer sk_live_YOUR_KEY"

Restart Claude Code and verify with /mcp. Skills are automatically available as tools.

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "skillshub": {
      "url": "https://skillshub.dev/api/mcp",
      "headers": {
        "Authorization": "Bearer sk_live_YOUR_KEY"
      }
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "skillshub": {
      "serverUrl": "https://skillshub.dev/api/mcp",
      "headers": {
        "Authorization": "Bearer sk_live_YOUR_KEY"
      }
    }
  }
}

Need help?

Check the Getting Started guide for initial setup or the Publishing Guide to learn how to create skills.

Getting Started Publishing Guide

MCP Reference

Authentication

MCP Endpoint

Rate Limits

MCP Tools

Parameters

Returns

Parameters

Parameters

Returns

Parameters

Returns

Parameters

Parameters

Error Responses

Common Errors

IDE Integration Examples

Claude Code

Cursor

Windsurf

Need help?

Command Palette