# Serving skills over MCP A [plugin](/docs/ai-control-plane/mcp-gateway/plugins) ships a skill inside the package an agent installs. Serving a skill over MCP delivers it from the MCP server the agent is already connected to instead. Add a skill to an MCP server, a gateway, or the organization gateway, and any agent connected there can list it and load its `SKILL.md` on demand. Nothing has to be installed or reinstalled, and an edit to the skill reaches agents on their next load. Both delivery paths work side by side. A skill can be bundled into plugins and served over MCP at the same time, and serving it over MCP leaves its plugin and assistant distributions unchanged. ## Access requirements > Viewing the skills a server or gateway serves requires the `skill:read` > scope. Adding or removing a skill on an MCP server requires the `mcp:write` > scope on that server. On a gateway it requires project-level `mcp:write`, > and on the organization gateway it requires `project:write` on the project > that owns the skill. The default [Admin > role](/docs/ai-control-plane/org-admin/roles-and-permissions) includes all of > these. ## How serving works A skill is served by a link between the skill and one MCP surface. Each link names exactly one target: - **An MCP server**: a hosted server built from OpenAPI documents or functions, or a [remote server](/docs/ai-control-plane/mcp-gateway/remote-servers). - **A gateway**: a [gateway endpoint](/docs/ai-control-plane/mcp-gateway/gateway-endpoints) built in the project. - **The organization gateway**: the [organization gateway](/docs/ai-control-plane/mcp-gateway/organization-gateway), which also covers project gateways. When an agent connects, the server declares the MCP Skills extension (`io.modelcontextprotocol/skills`). The agent lists the served skills with `skills/list`, which returns each skill's name, description, and URI, and loads the one it needs by reading its `SKILL.md` with `resources/read`. MCP clients that do not support the Skills extension see the same tools as before. ### Which version is served A link either tracks the skill's latest valid version or pins one version. Links added from the dashboard track the latest valid version, so editing the skill updates what agents load. The [Platform MCP](/docs/ai-control-plane/reference/platform-mcp) `link_skill_to_mcp` tool and the [API](/docs/ai-control-plane/reference/api-reference) also accept a version to pin. Only valid versions are served: a skill whose manifest fails validation is not served until a valid version replaces it. When one skill reaches an agent through several links, for example on a gateway and on one of its member servers, a pinned version wins over the latest one, and between two different pins the newer version wins. ### Who receives served skills Access follows reachability. Any member of the organization who can connect to a server or gateway receives the skills served there. There is no separate per-person or per-role targeting for served skills, so control who receives a skill by controlling who can connect, with [team access](/docs/ai-control-plane/mcp-gateway/access/team-access). The caller must be a signed-in person: - People who sign in to a server or gateway with their Speakeasy account receive its skills. - Connections that authenticate with an API key, an agent key, or a workload identity receive no skills. - Unauthenticated callers on a public server receive no skills, although the server still declares the Skills extension. - A disabled server serves no skills until it is enabled again. ### Skills on gateways A gateway serves the skills linked to it plus the skills linked to every member server the caller reaches through it. A skill linked to one server therefore also reaches agents who connect through any gateway that includes that server, without adding it to each gateway. - **Gateway endpoints** serve their own links plus their members' links. Agent gateways serve no skills. - **The organization gateway** serves skills linked to it from any project in the organization, plus the links on every member server the person can reach. - **Project gateways** serve the organization gateway's links plus the links on member servers in that project. A member counts only when the caller is actually served through it. On a connection where the person picked tools during consent, a member contributes its skills only when at least one of its tools was approved. ### Skills on remote servers A [remote server](/docs/ai-control-plane/mcp-gateway/remote-servers) passes any skills its upstream serves through to agents unchanged. Skills added on a remote server's **Skills** tab are not served at that server's own URL. Agents load them through gateways that include the server. ## Skill URIs Every served skill is addressed by a `skill://` URI that names its project and skill: ```text skill:////SKILL.md ``` Skills built into the platform, such as those served by the [Platform MCP](/docs/ai-control-plane/reference/platform-mcp), use the `speakeasy` namespace: ```text skill://speakeasy//SKILL.md ``` Each entry in `skills/list` also carries a digest of the served manifest. The skill's **Usage** tab shows the digest agents see for the current version, which helps confirm which version an agent loaded. ## Add skills to an MCP server or gateway 1. Open the MCP server or gateway from [**MCP Gateway**](https://ai.speakeasy.com/@self/projects/default/mcp) in the project sidebar. 2. Select the **Skills** tab. 3. Select **Add skill**, choose one or more project skills, and select **Add**. The **Skills** tab lists every skill the server or gateway serves, with the version it serves (**Latest** or the pinned version) and **Last loaded over MCP**, the last time an agent loaded it there. Select the remove button on a row, labeled **Stop serving**, to stop serving a skill. The skill, its versions, and its plugin distributions stay. On a gateway, the **Skills** tab also has an **Inherited from servers** section. It lists the skills added to member servers, with the server each one comes **From**. These rows are read-only on the gateway. Manage them from the member server's own **Skills** tab. ## Serve a skill from the organization gateway The organization gateway has no project page, so skills are added to it from the skill itself: 1. Open the skill from [**MCP Gateway > Skills**](/docs/ai-control-plane/mcp-gateway/skills). 2. Select the **Usage** tab. 3. In the **Served over MCP** section, select **Add to organization gateway**. The **Served over MCP** section lists every MCP server and gateway that serves the skill, when it was last loaded over MCP, and the digest of the current version. Each row links to the place where that link is managed, and the organization gateway row can be removed from here. ## Serve skills from an agent The [Platform MCP](/docs/ai-control-plane/reference/platform-mcp) exposes the same links to agents: - `link_skill_to_mcp` serves a skill from one MCP server, one gateway, or the organization gateway, optionally pinned to a version. - `unlink_skill_from_mcp` stops serving it there. - `list_skill_distributions` returns `served_by`, the MCP servers and gateways that serve the skill, next to its plugin distributions. Both write tools are available only to organization administrators and require explicit confirmation, the same as `distribute_skill`. ## Test in the Playground The [Playground](/docs/ai-control-plane/mcp-gateway/building-servers/playground) loads skills from the selected server the way a connected agent does. When the server serves skills, the Playground adds a `load_skill` tool whose description lists the served skills. When the model calls it, the Playground reads the skill's `SKILL.md` over MCP, and the read is recorded as a skill load like any other. ## Observe skill loads Every `resources/read` of a served skill is recorded as a skill activation, with the served version, the caller, and the session. A load through a gateway is recorded in the project that owns the skill. Repeat reads of the same version in one session count once. - [**Tool Logs**](/docs/ai-control-plane/observe/tool-logs) lists skill loads under the **Skills** type. The **Loaded via** filter separates loads over **MCP** from loads reported by agent **Hook**s. - [**MCP Insights**](/docs/ai-control-plane/observe/mcp-and-tools) shows a **Skill loads** card when skills are in the selection, split into loads over MCP and loads from hooks. - On the skill's detail page, MCP loads count toward its activations alongside activations captured from developer machines, and the **Served over MCP** section shows when it was last loaded over MCP. ## Limits - A served skill is a single `SKILL.md` file. Additional files in a skill directory are not served over MCP. - Agent gateways do not serve skills. - Served skills are not listed in `resources/list`. Agents discover them with `skills/list`. --- Index of every Speakeasy page for agents: [llms.txt](https://www.speakeasy.com/llms.txt). AI control plane and MCP gateway content in one file: [llms-full.txt](https://www.speakeasy.com/llms-full.txt). Any page is available as markdown by appending `.md` to its URL or by requesting it with `Accept: text/markdown`.