Metadata-Version: 2.4
Name: agentskills-mcp-server
Version: 0.7.0
Summary: Serve the official MCP Skills extension with lossless resources (https://agentskills.io)
License: MIT
Author: Pratik Panda
Requires-Python: >=3.12,<4.0
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Topic :: Software Development :: Libraries
Provides-Extra: fs
Provides-Extra: http
Requires-Dist: agentskills-core (>=0.7.0,<1.0)
Requires-Dist: agentskills-fs (>=0.6.0,<1.0) ; extra == "fs"
Requires-Dist: agentskills-http (>=0.6.0,<1.0) ; extra == "http"
Requires-Dist: mcp (>=2.2,<3)
Requires-Dist: pydantic (>=2.0)
Project-URL: Homepage, https://agentskills.io
Project-URL: Repository, https://github.com/pratikxpanda/agentskills-sdk
Description-Content-Type: text/markdown

---
title: Agent Skills MCP Server
description: Serve the official MCP Skills extension with immutable, lossless resources.
---

## Native Skills Only

The v0.7 development line requires MCP SDK `>=2.2,<3`. It serves the official
`io.modelcontextprotocol/skills` extension on protocol `2026-07-28` through
`skills/list`, `skills/get`, and canonical `skill://` resources. Clients on older
protocol revisions see the same `skill://` files as ordinary resources and cannot
call the Skills methods. See the
[breaking-change guide](https://github.com/pratikxpanda/agentskills-sdk/blob/main/docs/mcp-migration.md).
v0.7 is not yet released. Install the development checkout until publication.

## Install

The release install is `pip install 'agentskills-mcp-server[fs]>=0.7,<0.8'`.
For development, install the local core, filesystem, and MCP packages together:

```bash
python -m pip install ./packages/core/agentskills-core ./packages/providers/agentskills-fs ./packages/integrations/agentskills-mcp-server
```

The `[http]` extra adds the HTTP provider. Publisher verification needs
`agentskills-core[verification]` and OpenTelemetry export needs
`agentskills-core[telemetry]`. Use an isolated server environment
when a host framework pins a different MCP SDK version.

## Serve a Folder

```python
import asyncio
from pathlib import Path

from agentskills_core import Skill
from agentskills_fs import LocalFileSystemSkillProvider
from agentskills_mcp_server import create_mcp_server

provider = LocalFileSystemSkillProvider(Path("./skills"))
server = asyncio.run(create_mcp_server([Skill("incident-response", provider)]))
server.run(transport="stdio")
```

`create_mcp_server` is async and accepts a `SkillRegistry` or a sequence of raw
`Skill` handles. Raw handles avoid imposing registry-specific parsing restrictions
before publication. Discovery is metadata-only, including for a single skill.

The factory captures complete immutable file sets before serving. It preserves
original `SKILL.md` bytes, frontmatter, supporting directories, and binary files.
Each manifest contains raw-byte SHA-256 digests and sizes. A file whose bytes are
valid UTF-8 without NUL is read as `text` and every other file as `blob`. Both
forms return the exact captured bytes. Programmatic servers
support `await server.refresh()` and `server.health()`.
Server-provided hashes establish consistency, not publisher identity or safety.
Programmatic callers own provider cleanup and must keep providers open for refresh.
Optional `publication_policy` verifies detached signatures, pins content, and
applies reject/redact/annotate hooks before manifests are generated. See the
[trust and operability guide](https://github.com/pratikxpanda/agentskills-sdk/blob/main/docs/trust-and-operability.md)
for publisher configuration, token limits, verified stale policy, telemetry,
and authenticated remote HTTP deployment.

## Configuration

```json
{
  "name": "Skills Server",
  "skills": [
    {"id": "incident-response", "provider": "fs", "options": {"root": "./skills"}}
  ]
}
```

```bash
python -m agentskills_mcp_server --config server.json --check
python -m agentskills_mcp_server --config server.json
python -m agentskills_mcp_server --config server.json --transport streamable-http
```

JSON and YAML are supported. `${VAR}` placeholders resolve from the environment.
Unknown top-level keys are rejected. The CLI closes owned provider clients after
capture, including on failure.

| Field | Default | Meaning |
| --- | --- | --- |
| `name` | Required | Server display name |
| `skills` | Required, nonempty | IDs, provider types, and constructor options |
| `instructions` | `null` | Optional server-level instructions |
| `skill_paths` | `{}` | Registry ID to canonical publication path |
| `listed_skill_ids` | `null` | Optional listing subset, not authorization |
| `page_size` | `100` | Maximum entries per discovery page |
| `max_skills` | `128` | Publication skill-count ceiling |
| `max_total_bytes` | `67108864` | Total captured source byte ceiling |

Filesystem options include `root` and `max_file_bytes`. HTTP options include
`base_url`, `headers`, `params`, `file_manifest`, `resource_manifest`, and
`max_response_bytes`. HTTP native publication requires `file_manifest: true` and
a public destination by default. Internal destinations require explicit
`allow_private_network: true`. Redirects are always rejected. Configure
`require_tls`, `timeout`, and retry limits as needed. Publication requires
a complete per-skill file index. See the
[HTTP provider](https://github.com/pratikxpanda/agentskills-sdk/blob/main/packages/providers/agentskills-http/README.md).

The extension enforces 512 files and 16 MiB per skill. Directory reads are not
advertised. Nested skills require explicit publication and separate host approval.
Listed subsets never restrict direct lookup of a published skill. Supply only
skills authorized for the server audience.

The tools CLI uses native publication by default:

```bash
agentskills inspect ./skills --native
agentskills serve ./skills --check
agentskills serve ./skills --transport stdio
```

`--check` verifies local construction, manifests, and provider readiness without
listening. It does not certify transport, authentication, or host behavior.

## Client Support and Boundaries

Tests exercise MCP 2.2.0 `Client` in-process, over stdio, and over real loopback
Streamable HTTP. CI also checks mcpc 0.7.0 discovery, aliases, pagination, and exact
resource bytes. Use SDK 2 `Client` for extension negotiation, not its older
`ClientSession` compatibility API. Ordinary tools/resources connectivity does not
establish Skills support.

Hosts own selection, manifest verification, origin visibility,
per-skill consent, context injection, session tracking, image rendering, and
execution policy. Resource reads never execute scripts or grant `allowed-tools`.

Production HTTP deployments must supply TLS, MCP authorization, audience isolation,
and appropriate origin/host validation. Do not pass client bearer tokens to upstream
providers. Local tests are not production deployment certification.

## Benchmarks

The [benchmark guide](https://github.com/pratikxpanda/agentskills-sdk/blob/main/docs/mcp-benchmarks.md)
describes native discovery and progressive reads over bounded synthetic catalogs.
It does not measure model quality or production network performance.

