Skip to main content

Skills over MCP

Some MCP servers serve agent skills: folders with a SKILL.md file and supporting files, listed and read through the MCP skills extension (io.modelcontextprotocol/skills). MCPProxy reads those skills from your upstream servers, checks every file, and keeps a record of each one that you can list and read.

In this release skills are visible to administrators only

Skills are not offered to agents yet. Only the API key, the Unix socket and an administrator session can list, read, approve or block them. A scoped agent token is refused on every skills endpoint, and agents see nothing about skills. You can already review and approve skills, so they are ready when the agent-facing tools arrive in a later release.

Turn it on​

Skills over MCP is off by default. Turn it on in ~/.mcpproxy/mcp_config.json:

{
"enable_skills": true
}

To keep one server out, set expose_skills to false on it:

{
"enable_skills": true,
"mcpServers": [
{ "name": "hf", "url": "https://huggingface.co/mcp", "protocol": "http", "enabled": true },
{ "name": "internal", "url": "https://mcp.internal.example/mcp", "protocol": "http", "enabled": true, "expose_skills": false }
]
}

Both fields hot-reload. Both are also listed under Configuration File: Skills. A server is read only while it is enabled and not quarantined, and only if it announces the skills extension.

What MCPProxy reads and verifies​

For each skill a server lists, MCPProxy:

  • reads the listing (skill name, skill:// address, the list of files);
  • reads every file and compares its size and SHA-256 digest with what the server listed;
  • compares the SKILL.md frontmatter (name, description) with the listing;
  • stores the text files and computes one content hash (sk1-...) over the whole skill.

A skill that fails any check is not dropped. It is kept with the status unusable and a reason, so you can see what the server sent.

Limits​

These limits are fixed and not configurable:

LimitValue
Files per skill512
Size of one skill16 MiB
Skills per server200
Size of one listing (all pages)16 MiB
Stored text per server64 MiB
Name and description kept for display256 bytes and 4 KiB (longer text is cut and marked with …)

The mcpproxy skills commands show control characters in skill names, descriptions, paths and file text as visible escapes (\x1b, \u202e), because this text comes from the upstream server and is shown before anyone approved it. Use -o json for the exact text: there the same characters are written as JSON escapes (\u202e), which a JSON parser decodes back. -o yaml shows them as visible escapes, like the table output.

A listing that hits a limit is marked truncated. The limit of 200 counts every listed entry, including ones MCPProxy cannot decode.

A size in a listing is only what the server claims. For servers reached over streamable HTTP, MCPProxy also caps each response before it is buffered, at what the listed size allows, so a server that sends more than it listed is cut off. For stdio and SSE servers a response arrives on a stream shared with everything else the server sends and cannot be cut off per request: the length is checked after the response has arrived, which is the same exposure that already exists for any tool result from that server.

Skill states​

StatusMeaning
pendingRead and verified, never approved. Held for review.
approvedApproved for exactly its current content.
changedIt was approved, and its content has changed since. Held for review again.
unusableA check failed. The unusable_reason says which. It cannot be approved.

A skill also has a blocked mark that only a person sets and clears. available is true only for a skill that is approved, not blocked, still listed by its server, on a server that is enabled, not quarantined and not excluded with expose_skills: false.

Reviewing skills​

A skill is instruction text that an agent will follow, so MCPProxy treats it like a tool description: nothing is served until it is approved, and an approval covers one exact content.

What an approval covers​

An approval is bound to the skill's content hash (sk1-...). The hash covers the skill's address, every file (address, path, digest, size) and the SKILL.md frontmatter. If the server changes one byte of one file, adds or removes a file, or edits the frontmatter, the hash changes and the skill is no longer approved.

MCPProxy keeps its own copy of what you approved. When a skill changes, the approved copy stays in the store next to the new one, so you can compare them. If the server later returns to the approved content, the skill is approved again without a new review.

An approval also belongs to the server it was given for. Removing a server removes its skill approvals; a server added again under the same name starts with none.

Who approves: the server's trust mode​

The server's trust mode decides what happens to a new and to a changed skill. The rule for changes is stricter than the rule for tools.

Trust modeNew skillChanged skill
manualheld for youheld for you
scan (default)approved if the scan of every text file is clean and complete; otherwise heldheld for you, whatever the scan says
autoapprovedapproved

With quarantine turned off (quarantine_enabled: false) skills are approved as in auto. On a quarantined server no skill is available in any mode.

A skill that declares its files as dynamic has no content an approval could cover. It is unusable, cannot be approved, and no setting changes that.

The scan​

SKILL.md and every other text file of a skill go through the same offline scanner that checks tool descriptions. The result is stored with the skill:

  • verdict: clean, warnings or dangerous;
  • complete: whether every text file was scanned in full;
  • findings: the rule, the file and the position in the file, with a short excerpt.

A scan is not complete when the skill has more than 1 MiB of text (size_cap), when the scan of one skill took longer than two minutes (time_limit), when the scanner reported reduced coverage (coverage), or when it was stopped before the end (interrupted). A scan that is not complete never approves a skill in scan mode. Binary files are not scanned and not served.

The scanner was tuned on tool descriptions. A skill that tells an agent to run commands can be flagged without being hostile; in scan mode that only means the skill waits for you.

Approve, block, unblock​

mcpproxy skills list --server hf # what is held, with the scan result
mcpproxy skills show hf:hf-cli # read it
mcpproxy skills show hf:hf-cli --diff # what changed since the last approval
mcpproxy skills approve hf:hf-cli # approve exactly what was shown
mcpproxy skills approve --server hf --all # approve every held skill of one server
mcpproxy skills block hf:hf-cli # never available until you unblock it
mcpproxy skills unblock hf:hf-cli

approve sends the content hash it showed you. If the skill changed between the listing and the approval, the request is refused with review_out_of_date and nothing is approved: read the skill again. If the server was removed and added again in between, the answer is server_replaced.

A blocked skill stays blocked through refreshes, content changes and automatic approvals. Blocking does not delete the approval: unblock makes the skill available again if its content is still the approved one.

Every approval (by you, by the scan, or by auto mode), every hold of a changed skill, and every block and unblock is recorded in the activity log as skill_quarantine_change, with who did it and the hashes before and after:

mcpproxy activity list --type skill_quarantine_change

Reasons a skill is unusable​

ReasonMeaning
invalid_uriThe skill or file address is not a valid skill:// address.
name_mismatchThe name in the SKILL.md frontmatter differs from the last segment of the skill's path.
dynamicThe server declares the resources as dynamic, so their content cannot be verified.
too_many_filesMore than 512 files.
too_largeThe skill is larger than 16 MiB.
server_bound_exceededThe refresh read budget or the server's stored text budget (64 MiB) ran out before this skill was read.
unsupported_digestA file digest is not sha256.
digest_mismatchThe bytes read do not match the listed SHA-256.
size_mismatchThe bytes read do not match the listed size.
frontmatter_mismatchThe SKILL.md frontmatter disagrees with the listing.
frontmatter_invalidThe SKILL.md frontmatter cannot be parsed.
read_failedThe server failed or timed out while a file was read.
stored_copy_damagedThe stored copy no longer matches its digest.

Command line​

All commands need a running core (mcpproxy serve) and administrator credentials. They support -o json and -o yaml. approve, block and unblock are described under Reviewing skills.

mcpproxy skills list​

mcpproxy skills list
SERVER SKILL STATUS FILES SIZE
hf hf-cli pending 3 33.4 KB
hf hf-jobs pending 1 4.2 KB
hf broken unusable (digest_mismatch) 2 1.1 KB
hf: listing truncated (a skills limit was reached; some skills are missing)

--server <name> lists one server. A server whose last refresh failed gets a line with the error. With enable_skills off the command prints one line saying so.

mcpproxy skills show <server>:<skill>​

mcpproxy skills show hf:hf-cli
mcpproxy skills show hf:hf-cli --file references/auth.md
Skill: hf:hf-cli
Name: hf-cli
Description: Hugging Face CLI
Status: pending
Hash: sk1-0d9c...
Available: false

FILE SIZE TYPE DIGEST
SKILL.md 32.1 KB text sha256:3b1f...
logo.png 1.3 KB binary sha256:9a02...

--- SKILL.md (current copy) ---
# hf-cli
...

--file picks another text file. --approved reads the approved copy, which exists once the skill has been approved. --diff shows what changed since the last approval. The command reads long files in chunks until the end. A binary file cannot be shown.

mcpproxy skills refresh <server>​

mcpproxy skills refresh hf
hf: refreshed, 3 skills (2 pending, 1 unusable)

A refresh also runs by itself when a server connects, on the periodic discovery sweep, and when the configuration changes.

REST API​

All of them require administrator credentials; a scoped agent token gets 403, and so does a user session in the server edition. The same shapes are in REST API: Skills.

EndpointPurpose
GET /api/v1/servers/{id}/skillsEvery skill record of the server
GET /api/v1/servers/{id}/skills/content?skill=<path>&file=<relpath>&copy=current|approved&offset=<n>&limit=<n>One text file, in chunks of at most 64 KiB
POST /api/v1/servers/{id}/skills/refreshRead the server's skills again and return the listing
POST /api/v1/servers/{id}/skills/approveApprove skills for the content named in expected_hashes
POST /api/v1/servers/{id}/skills/block, .../unblockSet or clear the blocked mark

Troubleshooting​

The list is empty and supported is false. The server does not announce the skills extension. mcpproxy skills refresh <server> answers skills_not_supported in that case. Check that the server is enabled and not quarantined, and that it is a server that serves skills.

The command prints that skills are off. Set enable_skills: true in the configuration. REST answers {"enabled": false, "skills": []}, and refresh answers 409 skills_disabled.

truncated is true. The server listed more skills, or a larger listing, than the limits above allow, and MCPProxy stopped reading. The skills it did read are kept.

A skill shows server_bound_exceeded. The refresh read budget or the server's stored text (64 MiB) ran out before this skill was read. The skills read before the limit are kept; later ones are marked unusable. Removing large skills on the server, or excluding it with expose_skills: false, frees the budget.

A skill I approved shows changed. The server changed its content. Compare with mcpproxy skills show <server>:<skill> --diff and approve again if the change is fine. Agents keep being refused until then.

409 review_out_of_date on approve. The skill changed after you looked at it. Nothing was approved. List and read it again.

A clean skill stays pending on a scan server. Look at scan.complete. A scan that is not complete (size_cap, time_limit, coverage, interrupted) does not approve. A skill shown as "not scanned" is waiting for its turn: one refresh scans for about 45 seconds and the next one continues. Approve the skill yourself after reading it.

409 stored_copy_damaged when reading a file. The stored bytes no longer match their digest. Run mcpproxy skills refresh <server> to read the skill again.