> ## Documentation Index
> Fetch the complete documentation index at: https://docs.joystream.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Skills and MCP servers

> How an agent reaches the outside world — skills, MCP servers, catalogs, repositories, and scope resolution.

An agent needs to do things: read a calendar, create an account, post a message, open a ticket. Those actions come from two kinds of building block.

|                | What it is                                                                                    | You reference it by               |
| -------------- | --------------------------------------------------------------------------------------------- | --------------------------------- |
| **Skill**      | A curated capability wrapper with instructions, declared inputs, and the services it requires | Name, in conversation with Joyvis |
| **MCP server** | A Model Context Protocol server exposing a set of tools                                       | Server and tool, directly         |

A skill is the higher-level unit. Most skills are backed by an MCP server, but not all — a skill that needs no external tool executes through the model directly.

## The catalog

Your workspace has a catalog of available skills and MCP servers. Browse and search it:

```bash theme={null}
jstm skills list
jstm skills search calendar
jstm skills show google-calendar-read

jstm mcp list
jstm mcp search github
jstm mcp show github-mcp-server
```

`jstm skills check <name>` answers the practical question: can this skill actually run here? It reports whether the skill needs an MCP server, which one it resolved to, and the resolver's verdict.

## Where catalog entries come from

Three sources feed the catalog, in increasing specificity.

```mermaid theme={null}
flowchart TD
    A["<b>Curated baseline</b><br/>Ships with the platform"] --> D["Your workspace catalog"]
    B["<b>Repositories you add</b><br/>GitHub repos of skills or MCP servers"] --> D
    C["<b>Endpoints you register</b><br/>Your own MCP servers, by URL or command"] --> D
```

**Repositories.** Point JoyStream at a GitHub repository of skills or MCP servers and sync it. Private repositories work using your own connected GitHub credential.

```bash theme={null}
jstm skills repo add https://github.com/acme-corp/internal-skills --scope personal
jstm mcp repo add https://github.com/acme-corp/internal-mcp-servers --scope workspace \
  --workspace acme-corp/platform
```

**Endpoints.** Register a specific MCP server you host or subscribe to, then attach its API key so its tools authenticate.

```bash theme={null}
jstm mcp add-endpoint tavily-search --transport streamable-http \
  --url https://api.example.com/mcp --scope workspace
jstm mcp connect-key endpoint/acme-corp-platform/tavily-search --api-key <key>
```

Registering an endpoint succeeds even before a key is attached — the server registers with an empty tool list, and introspection fills it in once it can authenticate.

## Scope and resolution

Every repository and endpoint is added at a scope: `personal`, `workspace`, or org-wide. When the same name exists at more than one scope, the most specific one wins.

`jstm registry resolve <kind> <name>` shows the winning entry and why it won — which tier it came from and what it beat. `jstm registry list --kind mcp --workspace <id>` shows the whole resolved view for a workspace.

This matters because a team can override a shared server with their own version without affecting anyone else, and you can always find out which one an agent will actually get.

## Credentials

Skills declare the services they require. When an agent runs, JoyStream resolves a credential for each required service from your vault hierarchy and hands it to the MCP server in the environment variable that server expects.

If a required credential is missing, the run doesn't guess — it stops and tells you which provider to connect. See [Credentials and vaults](/features/credentials-and-vaults).

## Next

<Columns cols={2}>
  <Card title="Add your own MCP server" href="/guides/add-your-own-mcp-server" icon="server">
    Register an endpoint and connect its key.
  </Card>

  <Card title="Add repositories" href="/guides/add-skill-and-mcp-repositories" icon="git-branch">
    Sync skills and servers from GitHub.
  </Card>
</Columns>