# Connect an agent over MCP

> Add the SKaaS remote MCP servers to an assistant. The read server has five tools and pins every load to a release hash. The authoring server saves drafts and cannot publish.

Source: https://skaas.io/docs/mcp
Last updated: 2026-11-15

SKaaS serves skills to assistants over the Model Context Protocol (MCP). There are two servers. The read server finds and loads skills. The authoring server lets an assistant write a skill and save it as a draft. Both are remote and stateless, so there is nothing to run locally.

## Where is the read server?

Each organization has an endpoint at `https://mcp.skaas.io/v1/{org}` that covers every repository the caller can read. Narrow it with `/v1/{org}/{repo}` for one repository, or `/v1/{org}/{repo}@{channel}` for one repository channel such as `production`. Public skills are served from `/v1/public`. The transport is Streamable HTTP. A self-hosted deployment serves the same paths from its own address: by default `{api}/mcp`, where `{api}` is `SKAAS_API_URL`, or the address that `SKAAS_MCP_URL` names.

## How do I connect?

The quickest way is the CLI, which writes the right configuration for your assistant.

```sh
skaas connect claude-code
```

To add the server by hand in Claude Code, use its `mcp add` command with the HTTP transport.

```sh
claude mcp add --transport http skaas https://mcp.skaas.io/v1/acme
```

Clients that support OAuth for MCP sign in through the browser. Other clients use a token with the `skills:read` and `skills:search` scopes, which you create under Tokens and MCP setup in the dashboard. The configuration that the CLI writes reads the token from the `SKAAS_TOKEN` variable.

## Which tools does the read server offer?

Five tools. None of them changes anything.

| Tool             | What it does                                                                            |
| ---------------- | --------------------------------------------------------------------------------------- |
| `skill_search`   | Finds skills by task. Each hit says what kind it is and why it matched. It can abstain. |
| `skill_catalog`  | Lists routing metadata, without bodies, so a client can keep a local cache.             |
| `skill_get`      | Returns a skill's guide, pinned to a release hash, with the identifier of that release. |
| `skill_resource` | Returns one supporting file of a skill, pinned to the same hash.                        |
| `skills_status`  | Reports scope, counts, whether each search channel is ready and what the plan allows.   |

A request body is limited to 256 KiB and a request to 20 seconds. A file larger than 16 MiB is not returned.

## How should an assistant load a skill?

Search by task, copy the release hash from the hit, and pass it as `expected_sha256` to every later read of that skill. If the skill changed in between, the call fails with a revision conflict instead of returning different text. Search again and pin the new hash. Load a hit as instructions only when its kind is `skill`. A `reference` is material to read, not to follow.

The answer of `skill_get` and of the REST guide read carries `release_id`, the identifier of the release that the read came from. A client uses it to read the record of that release directly, for example to check its signature, and does not scan the list of releases for the hash. A service of an earlier version leaves the field out, and a client then falls back to the list.

A quarantined skill and a release that was withdrawn for security are refused with an error. They never return text. The `skaas-use` skill teaches an assistant this routine.

## What is the skills extension?

SKaaS also implements the MCP skills extension, `io.modelcontextprotocol/skills`, for hosts that support it. A repository lists a pinned set of up to 50 skills. Everything else is found with `skill_search` and loaded by address. See the [MCP specification](https://modelcontextprotocol.io/specification) for the protocol.

## What is the authoring server?

A second endpoint, separate from the read server, for an assistant that writes skills. On the hosted service it is `https://mcp.skaas.io/authoring`. On a self-hosted deployment it is `{api}/mcp-authoring` by default, for example `http://localhost:8080/mcp-authoring` on the Compose stack, and the operator can move it with `SKAAS_AUTHORING_MCP_URL`. It must differ from the address of the read server, because one address cannot serve both. It follows the same paths as the read server: `/v1/{org}` needs the repository in each call, and `/v1/{org}/{repo}` works on one repository. It has no public endpoint. A token needs the `skills:write` scope and write access to the repository.

```sh
claude mcp add --transport http skaas-authoring https://mcp.skaas.io/authoring/v1/acme/platform
```

| Tool                 | What it does                                                                                                          |
| -------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `skill_validate`     | Checks a whole package: format, secrets and the static audit. It stores nothing.                                      |
| `skill_draft`        | Saves the package as a draft release, runs the full audit and returns the receipt, the release hash and the findings. |
| `skill_publish`      | Records a request that a draft go live, naming the release hash. It does not publish.                                 |
| `skill_draft_status` | Reads the audit, the state of the request and the live head. It only reads.                                           |

A draft goes to the `draft` channel. It never moves `latest` or any other channel, so nobody who installs the skill gets it. A person with write access promotes the draft in the dashboard. The assistant sends the whole package every time, and sending the same files again changes nothing.

A file that holds a secret is reported, and the draft is refused. A repository that blocks on findings also refuses a draft that has one, with the code `BLOCKED_BY_POLICY`. An organization whose subscription is past due or canceled can still read its drafts and cannot create one or ask for a promotion. A package larger than the request limit of 8 MiB goes through the REST upload instead. The `skaas-author` skill teaches an assistant this routine.
