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.

By The SKaaS team. Last updated . Markdown version

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.

skaas connect claude-code

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

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.

Which tools does the read server offer?
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 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.

claude mcp add --transport http skaas-authoring https://mcp.skaas.io/authoring/v1/acme/platform
What is the authoring server?
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.