Sources

Choose where skill and MCP searches look: public indexes, MCP registries, and your own or your team's GitHub repositories.

What a source is

synapse skill search and synapse mcp search, and the Search tabs in the app, ask every source at once and label each result with the one it came from. A source is one of three kinds:

Kind	Holds	What it is
skills index	Skills	skills.sh, or anything answering its `/api/search` and `/api/download`.
MCP registry	MCP servers	The official MCP Registry, or any registry implementing its `/v0/servers` API — including one an organisation runs for itself.
GitHub repository	Both	Every `SKILL.md` folder and every `server.json` in a repository, or in one folder of it.

skills.sh and the official MCP Registry are built in. Once you change the list it is yours, so a built-in can be removed like any other.

Adding one

shell

synapse source add team acme/agent-skills
synapse source add team acme/agents@main/skills      # a branch and a folder
synapse source add internal https://mcp.example.com   # a registry
synapse source list
synapse source remove skills.sh

Synapse works out the kind. owner/repo or a github.com address is a repository; an address is asked whether it answers as an MCP registry or as a skills index, so a typo is caught when the source is added rather than on every search. --kind settles it when asking cannot.

Results are written source:id, which is what get takes. A bare id still means the first index, so synapse skill get owner/repo/skill works as it always has.

shell

synapse skill search release notes
synapse skill get team:skills/release-notes
synapse mcp get internal:com.example/billing

In the app, the bottom of each Search tab lists the sources that tab asks, with a field to add one and Remove beside each.

Private repositories

A private repository reads its token from the vault, and the sources file holds only the reference:

shell

synapse secret set work github GITHUB_TOKEN      # prompted
synapse source add team acme/agent-skills --token work.github

A project's sources

A repository can carry .synapse/sources.toml so everyone working in it searches the team's own sources:

toml

[[source]]
name = "team"
kind = "github"
repo = "acme/agent-skills"
path = "skills"

It is used only once somebody has approved its exact contents, the same bargain .synapse.yaml makes. A file somebody else committed decides where your searches go and whose instructions come back, so it is listed and not searched until you say otherwise:

shell

synapse source allow

Editing the file takes the approval away until it is allowed again. A project source whose name is already in your own list is skipped and reported, so team:release always means one thing.

How a repository is read

One request to GitHub's trees API lists the whole repository, and the files come from raw.githubusercontent.com, which does not count against GitHub's allowance of sixty requests an hour without a token. The catalogue — every skill's name and description, every server.json — is cached in the data folder for an hour, and a refresh whose tree has not changed reads nothing else. synapse source refresh reads it again now.

A server.json straight out of a repository is often the template a release fills in, with ${VERSION} where the version goes. Synapse cannot fill it, so the server runs unpinned.