MCP Reference

SkillRepo’s MCP (Model Context Protocol) server is the surface for remote agents — agents that don’t have filesystem access to a developer’s machine and need to fetch skill data over HTTP. Developers using a local IDE (Claude Code, Cursor, Windsurf, VS Code) should use the skillrepo CLI instead; the CLI keeps the on-disk library in sync without any MCP setup. The account MCP surface is read-only — four tools for discovering and reading skills. Publishing goes through the dashboard 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

The MCP endpoint accepts two parallel Bearer-token shapes on the Authorization header. Either one produces an authenticated request — the server distinguishes them by prefix.

Authorization: Bearer sk_live_…    # Platform access key (you create + manage it)
Authorization: Bearer ot_…         # OAuth 2.1 access token (user-consented via the OAuth flow)

Every MCP tool is read-only, so any valid bearer token works regardless of source. 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 use this MCP server.

Access keys (`sk_live_…`)

Hand-issued, never expire, scoped to the account that created them. Generate from the Connect page in your dashboard. Best for power users, CLI integrations, and machine-to-machine pipelines where the same human owns both ends.

OAuth 2.1 (`ot_…`)

For third-party agents (claude.ai, ChatGPT, Cursor, MCP Inspector, registry crawlers) that need a user-consented authorization path rather than a hand-issued key. Strict-spec-compliant against MCP-Auth-2025-06-18 + OAuth 2.1 + RFC 9728 / 8414 / 7591 / 9207 / 8707 / 7009 / 9700 so the server is listable on public MCP registries.

OAuth tokens are issued with the registry:read scope only. Access tokens expire after 1 hour and rotate via refresh tokens (30-day TTL). Revoking a refresh token cascades through the rotation chain — replaying an already-rotated refresh token revokes the entire token family on the next call.

Discovery endpoints (public, no auth required):

GET https://skillrepo.dev/.well-known/oauth-protected-resource
GET https://skillrepo.dev/.well-known/oauth-authorization-server
GET https://mcp.skillrepo.dev/.well-known/mcp.json

Flow (clients that implement OAuth 2.1):

Read /.well-known/oauth-authorization-server to discover the registration, authorization, token, and revocation endpoints.
Register your client via POST /api/oauth/register (RFC 7591 dynamic client registration). Use token_endpoint_auth_method: "none" for public clients. Loopback redirects for native apps must use the IP literal (http://127.0.0.1:PORT/cb), not localhost (OAuth 2.1 §1.5).
Direct the user to GET /api/oauth/authorize with PKCE code_challenge_method=S256, the canonical resource URI (https://mcp.skillrepo.dev), and a registered redirect URI. The user lands on a SkillRepo consent screen, picks the account to expose, and approves or denies.
On approve, the browser is redirected to redirect_uri?code=…&state=…&iss=… (RFC 9207iss parameter present on both success and error).
Exchange the code for tokens via POST /api/oauth/token with grant_type=authorization_code. Receive an ot_… access token and an rt_… refresh token.
Call /api/mcp with Authorization: Bearer ot_….
Refresh via POST /api/oauth/token with grant_type=refresh_token — refresh tokens rotate on every use.
Revoke via POST /api/oauth/revoke per RFC 7009.

Security note

Both access keys and OAuth tokens are hashed before storage. Plaintext credentials are returned to the client only at issuance and never persisted. Rotate compromised credentials immediately via the dashboard or the OAuth revoke endpoint.

MCP Endpoint

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

https://mcp.skillrepo.dev

Any MCP-compatible client — typically a remote agent runtime — connects by configuring this URL and an access key. The server implements the Model Context Protocol specification.

Rate Limits

Rate limits apply per access key and reset daily at midnight UTC. They count against the same per-day budget across CLI, MCP, and REST API requests.

Plan	API calls / day
Publisher	500
Team	Unlimited*

* Anti-abuse rate limits apply — see pricing for details.

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 — skills the account explicitly added from the catalog plus skills the account authored (hand-authored, REST push, or GitHub integration sync). Drafts, moderation-flagged skills, and ungraded skills (when analysis is enabled) are never returned. Skills the publisher has taken private or archived after the caller added them remain in the result — retention via library_items survives publisher revocation. 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 without a current published version row. The addedAt field is null for skills the account authored but never explicitly added (their order key falls back to the skill’s publishedAt). Entries are returned in ascending chronological order.

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	`https://mcp.skillrepo.dev` also reachable at `/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)

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

Access keys (sk_live_…)

OAuth 2.1 (ot_…)

MCP Endpoint

Rate Limits

MCP Tools

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Catalog MCP (third-party)

Error Responses

Common Errors

Need help?

Command Palette

Access keys (`sk_live_…`)

OAuth 2.1 (`ot_…`)