MCP Reference

SkillRepo exposes an MCP (Model Context Protocol) server that IDEs connect to over Streamable HTTP. The account MCP surface is read-only — it exposes four tools for discovering and reading skills. Publishing goes through the web UI or GitHub App sync; the MCP server does not accept writes.

MCP is read-only

The account MCP server exposes exactly four tools: get_skill, get_skill_content, get_skill_file, and list_library. None of them create, update, or delete skills. Publishing is done through the dashboard or the GitHub App sync. Deletion is done from your dashboard. A separate catalog MCP server exists for third-party consumers and uses a different auth and endpoint.

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.

Every MCP tool is read-only, so any valid access key works. The registry:write scope still exists, but it is only required by the REST publishing endpoints (e.g. POST /api/v1/library) — not by MCP. There is no scope you need to add to an existing key to use this MCP server.

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://skillrepo.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.

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",
  "license": "MIT",
  "compatibility": "cursor claude-code",
  "allowedTools": null,
  "metadata": null,
  "files": [
    { "path": "references/style-guide.md", "size": 2048, "contentType": "text/markdown" }
  ],
  "stats": { "installs": 1250, "activations": 1250, "rating": 4.8 },
  "publishedAt": "2025-01-15T00:00:00.000Z"
}

The stats.activations field is deprecated and currently mirrors stats.installs; prefer stats.installs in new code. To read the current published version label of a skill, call list_library — the get_skill response does not currently include a version string.

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`)

Returns

Text files (per the Content-Type stored with the blob) are returned as a plain string — the raw file body, ready to inject into the agent’s context.

Binary files are returned as a JSON envelope with base64-encoded content:

{
  "path": "assets/icon.png",
  "contentType": "image/png",
  "encoding": "base64",
  "content": "iVBORw0KGgoAAAANSUhEUg..."
}

Callers distinguish the two cases by attempting JSON-parse: a parsed object with an encoding field is binary; a parse failure means the response is raw text.

toollist_library

Tier 1 — Discovery

Lists every skill in the authenticated account’s library — both the account’s own skills and skills added from the public catalog. Returns lightweight metadata suitable for discovery; call get_skill_content to activate a specific skill from the list.

Parameters

None. The library is scoped to the account that owns the access key.

Returns

{
  "skills": [
    {
      "owner": "acme",
      "name": "code-review",
      "version": "1.2.0",
      "description": "Review code for bugs and security issues.",
      "addedAt": "2025-03-15T08:30:00.000Z"
    }
  ]
}

The version field is null for skills that do not have a published version yet. Entries are returned in the order they were added to the library.

Catalog MCP (third-party)

The catalog MCP is a separate read-only server for third-party consumers who want to browse the public SkillRepo catalog without platform credentials. It uses a different endpoint and a different kind of API key.

Attribute	Account MCP	Catalog MCP
Endpoint	`/api/mcp`	`/api/v1/catalog-mcp`
Auth	Platform key (`sk_live_`)	Catalog key (`ck_live_`)
Scope	Your account library	Global public catalog
Tools	get_skill, get_skill_content, get_skill_file, list_library	discover_skills, search_skills, get_skill, get_skill_file

Use the account MCP for your own workflows. Use the catalog MCP if you are building a third-party tool that surfaces public SkillRepo content to its own users.

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 (returned by `list_library` when no credentials are present)
`Skill not found`	Skill does not exist, is not in your library, or the caller is unauthenticated (read tools intentionally collapse these to a single error to avoid leaking existence)
`No published version available`	Returned by `get_skill_content` when the skill record exists but has no current published version
`File not found`	Requested supporting file path does not exist in the skill. The response includes an `availableFiles` array listing the paths that do exist
`Invalid file path`	The `path` parameter fails validation (traversal, absolute, or blocked extension)
`Failed to fetch file content`	Returned by `get_skill_file` when the blob storage backend rejects the fetch for an otherwise-valid file path (transient infrastructure error)

IDE Integration Examples

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

Progressive disclosure flow

Discovery — Agent calls list_library to enumerate every skill in the account’s library (~20 tokens per entry)
Metadata — For a specific skill, the agent calls get_skill to read the full manifest (~100 tokens) before deciding whether to activate
Activation — Agent calls get_skill_content to load full instructions (<5,000 tokens)
Execution — Agent requests supporting files on-demand via get_skill_file

Claude Code

Add SkillRepo as a remote MCP server:

claude mcp add --transport http skillrepo \
  https://skillrepo.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": {
    "skillrepo": {
      "url": "https://skillrepo.dev/api/mcp",
      "headers": {
        "Authorization": "Bearer sk_live_YOUR_KEY"
      }
    }
  }
}

After connecting, restart Cursor. Skills are automatically available as MCP tools.

Windsurf

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

{
  "mcpServers": {
    "skillrepo": {
      "serverUrl": "https://skillrepo.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

Returns

Parameters

Returns

Parameters

Returns

Catalog MCP (third-party)

Error Responses

Common Errors

IDE Integration Examples

Claude Code

Cursor

Windsurf

Need help?

Command Palette