Files
skillshare/website/docs/reference/commands/mcp.md
T
Willie e9dc4d0360 feat(server)!: answer only at localhost, IP addresses and trusted origins (#811)
DNS rebinding lets a page point its own domain at the user's machine,
which makes its requests same-origin to the dashboard, so the CSRF
guard cannot refuse them. Only the MCP, Hooks and Plugins routes
required a localhost or IP Host, so such a page could still install,
sync and push. That rule also blocked those three pages for people who
run the dashboard behind their own reverse proxy (#809).

The dashboard now answers every route only at localhost, an IP address,
the --host name, and origins given with --trusted-origin or
SKILLSHARE_UI_TRUSTED_ORIGINS. Configuration stays outside config.yaml
so the dashboard cannot widen its own trust through its config API. A
trusted origin must match the Host with its scheme, and an Origin
header, when sent, must be that origin. A refused browser gets a page
with the exact setting to copy, the API gets it in the error, and the
server log names each refused Host once.

BREAKING CHANGE: a dashboard opened by a domain name, such as a reverse
proxy, a Tailscale or mDNS name, or a Docker service name, now returns
403 on every page until that address is trusted, for example with
`skillshare ui start --trusted-origin https://skills.example.com`.

Release-As: 0.30.0
2026-11-09 11:59:50 +08:00

1495 lines
86 KiB
Markdown

---
sidebar_position: 3
---
# mcp
Manage portable MCP connection definitions and synchronize native Agent settings.
Start with [Set up MCP once](/docs/how-to/daily-tasks/sharing-mcp).
## Commands
```bash
skillshare mcp
skillshare mcp add
skillshare mcp edit
skillshare mcp edit docs --url https://updated.example/mcp --no-tui
skillshare mcp add docs --url https://example.com/mcp --target claude --sync
skillshare mcp add local --target codex -- company-mcp --workspace /path/to/workspace
skillshare mcp import docs --from claude --target claude --target cursor --sync
skillshare mcp import docs --file ./provider.json --target claude
skillshare mcp list --json
skillshare mcp check
skillshare mcp check docs --json --no-dns
skillshare mcp check --live --timeout 30s
skillshare mcp check docs --live --accept-tools
skillshare mcp remove docs --sync
skillshare mcp remove docs --keep-files
skillshare mcp restore BACKUP_ID --dry-run
skillshare mcp serve
skillshare mcp serve --target claude --http 127.0.0.1:8765
skillshare mcp serve --check
skillshare sync mcp --dry-run --json
skillshare sync mcp
skillshare sync --all
```
| Option | Meaning |
|---|---|
| `--target CLIENT` | Receiving client; repeat to select multiple clients. `--target none` keeps the server in Skillshare without writing it to any client. See [below](#keep-a-server-without-syncing-it). With `serve`, `--target NAME` names a skills target instead; see [below](#serve-skills-over-mcp) |
| `--url URL` | Streamable HTTP endpoint for `add` |
| `-- command args...` | Local executable and literal arguments for `add` |
| `--disabled` | Project mode, with `add`: turn off a server the Agent's global config defines. See [below](#turn-off-a-global-server-in-one-project) |
| `--tools-allow TOOLS` | Only these tools, separated by commas; `*` matches any characters; `""` clears. See [Tool policy](#tool-policy) |
| `--tools-deny TOOLS` | Never these tools, separated by commas; beats allow; `""` clears. See [Tool policy](#tool-policy) |
| `--pi-options JSON` | Other per-server fields of Pi's built-in MCP, as a JSON object. See [Pi](#pi-options) |
| `--from CLIENT` | Existing client to import, or the format of `--file` |
| `--file PATH` | Native JSON/JSONC, TOML or Goose YAML; `.toml` defaults to Codex, other formats are detected from their MCP section; use `--from` for an explicit dialect |
| `--sync` | Save and synchronize; noninteractive add/import/remove otherwise save only |
| `--keep-files` | With `remove`: stop managing the server and leave its Agent entries as they are. Not with `--sync`. See [below](#stop-managing-a-server) |
| `--replace` | Explicitly replace an existing source definition during add/import; on import, also rewrite the imported client's entry when it differs |
| `--dry-run`, `-n` | Preview without saving or writing native configuration |
| `--json` | Structured output; sync/preview reports contain names, paths and actions, not server values |
| `--no-dns` | With `check`: skip the host lookup of remote servers. See [below](#check-servers-before-an-agent-starts-them) |
| `--live` | With `check`: also start each local server and call each remote one. See [below](#probe-servers-live) |
| `--timeout DURATION` | With `check --live`: time limit for each server's probe, such as `30s`; default `10s` |
| `--accept-tools` | With `check --live`: record the tool definitions each probed server lists as its new baseline. See [below](#pin-tool-definitions) |
| `--http ADDR` | With `serve`: listen for Streamable HTTP on `ADDR` instead of using stdio, and also serve the [Executor skill index](#executor). See [below](#serve-skills-over-mcp) |
| `--http-allow-insecure` | With `serve --http`: allow the bearer token over plain HTTP off loopback on a trusted private network; logs a warning. Default: off |
| `--tls-cert FILE`, `--tls-key FILE` | With `serve --http`: serve HTTPS with this PEM certificate and key; required off loopback unless explicitly opted out |
| `--check` | With `serve`: list the skills it would skip and why, how many are editable, and what the Executor index would serve, then exit without serving |
| `--no-tui` | Disable interactive menus; also disabled by `tui: false`, `--json`, or non-terminal input/output |
| `--revision ID` | Require a matching preview for add/import/remove or `sync mcp` |
| `--global`, `-g` | Use global Skillshare configuration |
| `--project`, `-p` | Use project Skillshare configuration |
With no subcommand, `mcp` opens the searchable manager in an interactive terminal,
or prints status in noninteractive mode. Noninteractive import without a name lists
parsed candidates for selection and does not save. Candidates contain portable
definitions, with recognizable secrets converted to references. Agent-specific
fields are listed as warnings and left out; disabled servers and unsupported
transports block the candidate. `restore` always previews again before applying;
use `--dry-run` to inspect it without applying.
`--pi-extension`, `--pi-options-prune` and `--direct-tools` were removed in 0.23.0 and
now fail with a message that says what to use instead. See
[Upgrading Pi from 0.22](#pi-migration).
`sync mcp` accepts scope flags, `--dry-run`, `--json`, `--no-tui`, and `--revision`.
`sync --all` includes skills, agents, extras, MCP and hooks; plain `sync` keeps its
existing resource behavior. MCP conflicts are checked before `--all` changes
other resources. Resource types and native files are separate operations, not a
single transaction.
## Interactive management
Run `skillshare mcp` or `skillshare mcp list` to add, import, edit, remove, sync
and restore connections; the details of the selected one show beside the list.
Connection lists hide argument, header and environment values, and omit URL
queries. The keys are listed at the bottom of the screen.
`mcp edit`, `mcp remove`, and `mcp restore` offer selection menus when their name
or backup ID is omitted. The editor covers command/URL, arguments, environment
variables, HTTP headers, bearer-token environment references, receiving
targets and the [tool policy](#tool-policy) (**Tools**). Arguments accept one literal argument per line or a JSON array. Switching
transport clears fields that do not apply to the new connection type.
Add, edit, remove and import show a preview before **Save and sync** or **Save
only**. Remove also offers **Stop managing**, the same as `--keep-files`. Escape
cancels the pending draft. Restore previews and confirms changes
to Agent entries; it does not rewrite the source definition.
Import without a server name supports multiple selections. Invalid candidates are skipped; existing source names are skipped
unless `--replace` is specified. Select one set of compatible receiving clients
for the batch. The entire batch is validated before the source is saved once;
later native-file I/O failures retain the existing recovery behavior.
For scripts, provide a name and flags. `mcp edit NAME --url URL`,
`mcp edit NAME --target CLIENT`, and `mcp edit NAME -- command args...` update the
specified fields while preserving other applicable settings. They save only
unless `--sync` is added. With `--no-tui`, remove requires a name and restore
requires a backup ID. `--dry-run` never saves or synchronizes changes.
## Source fields
Choose inline `mcp.servers` or an external file named by `sources.mcp`.
External files have a top-level `servers` mapping. `mcp.targets` and
[`mcp.projects`](#manage-several-projects-from-the-global-config) stay in the
Skillshare config. The schema is `schemas/mcp.schema.json` in the repository.
| Server field | Meaning |
|---|---|
| `command` | Local executable; mutually exclusive with `url` |
| `args` | List of literal arguments for a local executable |
| `env` | Local environment values: strings or `{fromEnv: VARIABLE}` |
| `url` | HTTP(S) MCP endpoint; no embedded credentials or fragment |
| `headers` | HTTP headers: strings or `{fromEnv: VARIABLE}` |
| `bearerToken` | `{fromEnv: VARIABLE}`; cannot coexist with an Authorization header |
| `transport` | Optional `stdio` or `streamable-http`; inferred when omitted |
| `targets` | Optional receiving clients; overrides `mcp.targets`. An empty list keeps the server in Skillshare only. See [below](#keep-a-server-without-syncing-it) |
| `tools` | Which tools reach the model: `allow`, `deny`. Written once and translated per Agent. See [Tool policy](#tool-policy) |
| `options` | Other Agents' native per-server fields, keyed by client ID, such as a Codex approval mode or a Claude Code timeout. See [below](#agent-options) |
| `piOptions` | Other per-server fields of Pi's built-in MCP. See [Pi](#pi-options) |
| `disabled` | `true` only, no other connection fields, and a project must be in scope: project mode, or a root under `mcp.projects`. See [below](#turn-off-a-global-server-in-one-project) |
Client IDs are `claude`, `codex`, `cursor`, `vscode`, `opencode`, `kilocode`,
`grok`, `antigravity`, `amp`, `claude-desktop`, `cline`, `copilot`, `factory`, `gemini`,
`goose`, `junie`, `kiro`, `lmstudio`, `warp`, `windsurf`, `pi`, and `omp`.
`--target` and `--from` also take `agy` and `antigravity-cli`, the names other
commands use for the Antigravity CLI, as `antigravity`; the source stores `antigravity`.
`grok` means the official xAI Grok CLI. Server names use letters,
digits, dots, underscores and hyphens. A server must select at least one client
either directly or through `mcp.targets` before synchronization, unless its own
`targets` is an empty list.
### Other Agent settings {#agent-options}
`options` writes native fields that have no portable form into one Agent's entry, as
given. Each key is a client ID; an account target receives the options of its Agent.
```yaml
servers:
docs:
url: https://example.com/mcp
targets: [codex, claude]
options:
codex:
default_tools_approval_mode: approve
claude:
timeout: 600000
```
- Values are strings, numbers, booleans, lists of those, or mappings of them. `null` and
lists of mappings are refused, because not every native format writes them back.
- A field Skillshare writes from the server's own settings, such as `url`, `command`,
`env`, `headers`, `type`, `enabled` or Codex `enabled_tools`, is refused.
- Pi's fields go in [`piOptions`](#pi-options); `options.pi` is refused.
- A credential, judged by its field name (token, secret, password, API key, authorization,
credential) or a password in a URL, must be an environment reference in the Agent's own
syntax that makes up the whole value, such as `${VAR}` for Claude Code or `{env:VAR}`
for OpenCode. Plain text, or text around a reference, is refused, because the Agent's
file may be committed. Codex, Antigravity, Claude Desktop, Goose, Junie, LM Studio and Warp
read no references there, so their options cannot hold a credential.
- Options for a client the server does not reach are kept and not written.
- Sync writes the fields again when it recreates an entry, for example after a rename.
When the source drops an option, the next sync removes the field it wrote, unless
the Agent changed it since; that is a conflict to import or replace.
- In the dashboard, **Other Agent settings** in the server dialog edits them: pick an Agent, then
type its fields as a JSON object. Clearing the text removes that Agent's options.
### Keep a server without syncing it
A server with `targets: []` stays in the Skillshare source and is written to no client.
Use it to take a server out of every client while keeping its definition for later.
If it was synced before, the next sync removes its entries from those clients.
```yaml
mcp:
targets: [claude, codex]
servers:
docs:
url: https://example.com/mcp
targets: []
```
```bash
skillshare mcp add docs --url https://example.com/mcp --target none
skillshare mcp edit docs --target none
skillshare mcp edit docs --target claude # bring it back
```
- **Leaving `targets` out is different.** The server then inherits `mcp.targets`, and
it is refused when that list is empty too.
- `none` cannot be combined with a client.
- In the terminal picker, confirm with no client selected. In the dashboard, untick
every client; the server is tagged **No Agents yet**.
- It works the same for a project's servers and for servers under `mcp.projects`.
- A `disabled` entry still needs at least one client, since it has to turn the server
off somewhere.
- `mcp list` shows such a server as `kept no targets`.
For Grok, names must start with a letter or underscore, contain only letters,
digits, hyphens and single underscores, and cannot end with an underscore.
Names such as `company-docs` work across all supported clients.
## Native destinations {#native-destinations}
| Client | Global | Project | Section |
|---|---|---|---|
| Claude Code | `~/.claude.json` | `.mcp.json` | `mcpServers` |
| Codex | `~/.codex/config.toml` | `.codex/config.toml` | `mcp_servers` |
| Cursor | `~/.cursor/mcp.json` | `.cursor/mcp.json` | `mcpServers` |
| VS Code | User `mcp.json` (below) | `.vscode/mcp.json` | `servers` |
| OpenCode | `~/.config/opencode/opencode.json` | `opencode.json` | `mcp`; import also reads OpenCode 2's `mcp.servers` |
| Kilo Code | `~/.config/kilo/kilo.jsonc` | `kilo.jsonc` | `mcp` |
| Grok CLI | `~/.grok/config.toml` | `.grok/config.toml` | `mcp_servers` |
| Antigravity (AGY) | `~/.gemini/config/mcp_config.json` | `.agents/mcp_config.json` | `mcpServers` |
| [Amp](https://ampcode.com/docs/customize/mcp) | `~/.config/amp/settings.json` | `.amp/settings.json` | `amp.mcpServers` (literal key) |
| [Claude Desktop](https://modelcontextprotocol.io/docs/develop/connect-local-servers) | Claude application data directory, `claude_desktop_config.json` | Global only | `mcpServers` |
| [Cline](https://github.com/cline/cline/tree/main/apps/vscode/src/services/mcp) | `~/.cline/data/settings/cline_mcp_settings.json` | Global only | `mcpServers` |
| [Copilot CLI](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers) | `~/.copilot/mcp-config.json` | `.github/mcp.json` | `mcpServers` |
| [Factory Droid](https://docs.factory.ai/harness/mcp) | `~/.factory/mcp.json` | `.factory/mcp.json` | `mcpServers` |
| [Gemini CLI](https://geminicli.com/docs/tools/mcp-server/) | `~/.gemini/settings.json` | `.gemini/settings.json` | `mcpServers` |
| [Goose](https://block.github.io/goose/docs/guides/config-files/) | `~/.config/goose/config.yaml` | Global only | `extensions` (YAML) |
| [Junie](https://junie.jetbrains.com/docs/junie-cli-mcp-configuration.html) | `~/.junie/mcp/mcp.json` | `.junie/mcp/mcp.json` | `mcpServers` |
| [Kiro](https://kiro.dev/docs/mcp/configuration/) | `~/.kiro/settings/mcp.json` | `.kiro/settings/mcp.json` | `mcpServers` |
| [LM Studio](https://lmstudio.ai/docs/app/mcp) | `~/.lmstudio/mcp.json` | Global only | `mcpServers` |
| [Warp](https://docs.warp.dev/agents/capabilities/mcp/) | `~/.warp/.mcp.json` | `.warp/.mcp.json` | `mcpServers` |
| [Windsurf (Cascade)](https://docs.devin.ai/desktop/cascade/mcp) | `~/.codeium/windsurf/mcp_config.json` | Global only | `mcpServers` |
| [Oh My Pi (OMP)](https://github.com/can1357/oh-my-pi/blob/v18.6.1/docs/mcp-config.md) | `~/.omp/agent/mcp.json` | `.omp/mcp.json` | `mcpServers` |
The dashboard's server form edits HTTP headers the same way as environment variables,
including `fromEnv` references. **View what each Agent gets**, in a server's menu and
beside the file count in its form, shows read only the native text Sync would write for
the selected client; in the form it reflects edits that are not saved yet. Secrets stay
as references.
JSON entries are written one field per line at the file's own indentation. An entry
Skillshare owns that still sits on one line is reported as an `update` and written again
laid out. Entries it does not own, and entries someone formatted by hand, keep their layout.
The dashboard only offers destinations available in the current scope and host
platform. Each server is one row, with the clients it goes to as chips under its name;
the count button on the right opens the full client list for that server. Global-only clients cannot be selected in project mode.
The **Sync** box on the right lists the changes not yet written: ticking a client
only edits the source. **Sync MCP** lists those changes and, after you confirm, writes
only the MCP config files, keeping a backup of each. Under a line in the same box,
**Check** [checks the servers](#check-servers-before-an-agent-starts-them) once there
are any, and **Backups and restore** browses those backups.
Below it, **Agents** lists the clients detected on this machine. A client counts as
detected when its MCP file exists, or when the folder that client keeps its settings in
exists, so a fresh install with no MCP file yet still appears. In project mode a client
is listed when the project has its MCP file or the client is detected globally.
Each detected client shows the name of its MCP file, and **Copy path** copies its full
path. Once the file exists, **Open in editor** opens it in the same editor a skill's
**Open in editor** uses. **Open folder** opens the folder that holds the file in the file
manager (Finder, File Explorer, or the default handler on Linux), or the closest folder
that exists before the client has written it, so you can open the file in any program
without setting `$EDITOR`. Both start on the machine running the dashboard, so these
buttons appear only when the browser runs there too, at `localhost` or through SSH port
forwarding, not through a LAN address or a reverse proxy.
Additional client details:
- The `codex` destination is one `config.toml` that the Codex CLI, the Codex IDE
extension and the ChatGPT desktop app share, so a server synced to `codex` appears in
all three. The ChatGPT desktop app lists them under **Settings → MCP servers**.
Codex reads `.codex/config.toml` only in a project it trusts; in an untrusted
project the synced servers do not load, without an error. `cwd`,
`http_headers_helper`, approval modes, timeouts and the `oauth` table
have no portable form: import leaves them out with a warning and sync keeps them in
the existing entry. To set them from the source, use [`options.codex`](#agent-options). `enabled_tools` and `disabled_tools` come from the
[tool policy](#tool-policy) and are imported into it. MCP servers that a Codex plugin bundles are configured under
`plugins.<plugin>.mcp_servers` and are not managed here.
- Claude Desktop file sync supports **stdio only**, on macOS and Windows.
Its directory is `~/Library/Application Support/Claude` on macOS and
`%APPDATA%/Claude` on Windows. Configure remote connectors in the application.
- Cline targets the default VS Code Stable profile, not Cline CLI or other IDEs.
- Copilot CLI entries get `tools`: the exact tool names the
[tool policy](#tool-policy) allows, otherwise `["*"]`. Import reads `tools` back into
the policy. If a project `.mcp.json` exists, sync stops because Copilot reads that
file ahead of `.github/mcp.json`; consolidate the files first.
Selecting Claude Code and Copilot CLI together in project mode is also blocked
before writing either file. Use global mode for one of these clients.
- Gemini uses `httpUrl` for Streamable HTTP. Its `url` field means legacy SSE
and is rejected on import. Cline uses `type: streamableHttp`; Goose uses
`type: streamable_http` and `uri`. Skillshare converts these automatically.
- Goose on Windows uses `%APPDATA%/Block/goose/config/config.yaml`. YAML edits
preserve unrelated settings, comments and built-in extensions, but may change
formatting. Aliases, merges, duplicate keys and multiple documents block edits.
Built-in extensions and keychain `env_keys` cannot be imported as portable MCP
connections.
- Claude Code skips a server named `workspace`, `claude-in-chrome` or `computer-use`,
which it reserves for built-in servers. It also never sends its own credentials to a
remote server: `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, `AWS_BEARER_TOKEN_BEDROCK`,
`HTTPS_PROXY` and `NPM_TOKEN` read as empty in `url` and `headers`. Skillshare refuses
both for Claude. Copy the credential into a variable with a name of your own.
- Claude Code also has a local scope: servers added with `claude mcp add` and no
`--scope`, stored per project in `~/.claude.json`. A local server wins, whole, over
one of the same name in `.mcp.json` or the user scope. In project mode Skillshare
reports such a server next to the entry it hides, without blocking the sync. Remove
it with `claude mcp remove NAME -s local` from the project folder.
- Cline's VS Code extension, CLI and SDK share `~/.cline/data/settings/`. The
extension moves its older VS Code `globalStorage` file there once and then stops
reading it, so Skillshare writes to the old file only while `~/.cline/data` does
not exist yet. `CLINE_MCP_SETTINGS_PATH`, `CLINE_DATA_DIR` and `CLINE_DIR` are
respected, in that order.
- Windsurf support is for the documented Cascade configuration. Windsurf's newer
Devin Local agent reads its own `~/.config/devin/mcp_config.json`, which Skillshare
does not manage. Warp project connections still require approval inside Warp
each session.
- Amp runs a server from a project's `.amp/settings.json` only after
`amp mcp approve <name>`. Global servers need no approval.
- Kiro expands `${VARIABLE}` only for names listed in its "Mcp Approved Env Vars"
setting, and accepts `http://` URLs for localhost only.
- VS Code keeps a separate `mcp.json` for each non-default profile under
`User/profiles/`. Skillshare manages the default profile's file.
Environment references are exported as `${VARIABLE}` for Amp, Copilot CLI,
Factory, Gemini CLI and Kiro, and `${env:VARIABLE}` for Cline and Windsurf.
Claude Desktop, Goose, Junie, LM Studio and Warp currently reject `fromEnv` and
`bearerToken` exports because their native interpolation has not been verified.
Use connections without custom credentials or authenticate in the receiving
client where supported. Skillshare never resolves references into plaintext.
Antigravity uses the current [official MCP configuration](https://antigravity.google/docs/mcp),
including `serverUrl` for remote connections. Skillshare converts portable `url`
automatically. Older `.gemini/antigravity/` and `.gemini/antigravity-cli/` config
locations are not managed. Antigravity `fromEnv` and `bearerToken` exports are
blocked because its documented configuration does not specify environment
interpolation. Use connections that need no custom secret headers, and complete
supported OAuth login inside Antigravity. Skillshare never expands references
into plaintext credentials.
OpenCode respects `XDG_CONFIG_HOME` for its global directory. An existing
`opencode.jsonc` is used instead of creating `opencode.json`. In a project,
OpenCode also reads both names from `.opencode/`, so a file kept there is the one
Skillshare writes to; a new file is created at the project root. If more than one
exists, consolidate them before syncing. Custom OpenCode config
paths, directory overrides, inline config and inherited ancestor files are not
managed. They may override the selected destination in OpenCode.
Kilo Code uses the same format as OpenCode. It reads `kilo.jsonc` and `kilo.json`
from the project root and from `.kilo/`, and merges them, so Skillshare writes to
whichever one already exists and creates `kilo.jsonc` only when there is none. If
more than one exists, consolidate them before syncing. `KILO_CONFIG`,
`KILO_CONFIG_DIR` and the `mcp_settings.json` of the older VS Code extension are
not managed.
Kilo Code treats project config as untrusted. It does not allow `{env:VARIABLE}`
references there, and it ignores the whole project file when it finds one. In project
mode Skillshare therefore refuses a Kilo Code server that uses `fromEnv` or
`bearerToken`. Define that server in global mode, where references are allowed.
OpenCode and Kilo Code use `local`/`remote` types and `{env:VARIABLE}` references; Grok uses
`${VARIABLE}` references. Skillshare converts these automatically. Claude's
`"type": "streamable-http"` imports as HTTP. Disabled connections block import.
Other native options without a portable equivalent, such as Codex
`startup_timeout_sec` or `envFile`, are left out of the import with a warning;
sync keeps them in the Agent's existing entry. Pi uses its built-in MCP; see
[below](#pi).
VS Code Stable's default user file is:
- macOS: `~/Library/Application Support/Code/User/mcp.json`
- Linux: `${XDG_CONFIG_HOME:-~/.config}/Code/User/mcp.json`
- Windows: `%APPDATA%/Code/User/mcp.json`
Global Claude, Codex, Grok, Copilot and OpenCode paths respect `CLAUDE_CONFIG_DIR`, `CODEX_HOME`,
`GROK_HOME`, `COPILOT_HOME` and `OPENCODE_CONFIG_DIR`. `OPENCODE_CONFIG` is not managed. Amp and Goose honor `XDG_CONFIG_HOME` on the
platforms using their `.config` paths.
Project destinations are relative to the selected project root. Project trust,
server approval and authentication remain the receiving Agent's responsibility.
### Another account of an Agent {#accounts}
A target declared as [another account of an Agent](/docs/reference/targets/configuration#agent-config-dir) is an MCP target too, for `claude` (`CLAUDE_CONFIG_DIR`), `codex` (`CODEX_HOME`), `opencode` (`OPENCODE_CONFIG_DIR`), `pi` and `omp` (both use `PI_CODING_AGENT_DIR`). Its servers are written in that Agent's format, into the account's own file: `<config_dir>/.claude.json` for Claude, `<config_dir>/config.toml` for Codex, `<config_dir>/opencode.json` for OpenCode, or `<config_dir>/mcp.json` for Pi and OMP.
```yaml
targets:
claude-work:
agent: claude
config_dir: ~/.claude-work
mcp:
targets: [claude, claude-work] # both accounts get every server
servers:
docs:
url: https://example.com/mcp
jira:
command: jira-mcp
targets: [claude-work] # the work account only
```
Here `docs` goes to `~/.claude.json` and `~/.claude-work/.claude.json`, and `jira` to the second file only. `--target claude-work` works with `mcp add` and `mcp edit`, and the dashboard lists the account next to the Agents.
When `CLAUDE_CONFIG_DIR`, `CODEX_HOME`, `OPENCODE_CONFIG_DIR` or `PI_CODING_AGENT_DIR` points at a declared account's `config_dir` for that Agent, the plain Agent target uses its default home and sync warns about the shadowed variable. Existing directory aliases, including symlinks and case variants on case-insensitive filesystems, count as the same home. With no matching account, the override is honored as usual.
If a managed MCP entry's file no longer matches its scope's resolved destination, sync leaves that entry and its ownership unchanged and warns about the parked path. This also applies after an account is removed or its `config_dir` changes. Sync from a configuration and shell where that home resolves again to resume managing it. Removed project scopes recorded in ownership and Pi's legacy adapter files remain eligible for cleanup.
Older ownership records lack this scope information. If a removed project's scope cannot be resolved, its entries stay parked. To clean them up, add the project back, sync once to record its scope, then remove it again and sync.
Every account reads the same project files, so inside `mcp.projects` and in project mode use the Agent's own name. Claude Code keeps a project's off list in each account's file: [turning a server off in a project](#turn-off-a-global-server-in-one-project) writes the switch to every account that has the server. `mcp import --from claude-work`, and the dashboard's Import from target, read the account's own file. `mcp import --file <path> --from claude-work` reads a file you exported yourself, in that account's Agent format.
## Turn off a global server in one project {#turn-off-a-global-server-in-one-project}
An Agent reads its own global MCP file and the project's file together. A server
defined in the global file therefore loads in every project. To stop it loading in
one project, add an entry **with the same name the Agent's global file uses** and
mark it `disabled`.
This works with five clients only:
| Client | Supported | What Skillshare writes |
|---|---|---|
| Claude Code | Yes | `~/.claude.json`: the name, in this project's `disabledMcpServers` list |
| OpenCode | Yes | `opencode.json`: `"NAME": {"type": "local", "command": ["EXECUTABLE"], "enabled": false}`, or the URL for a remote server, see below |
| Kilo Code | Yes | `kilo.jsonc`: `"NAME": {"enabled": false}` |
| Pi | Yes, Pi 1.0.1 and later | `.pi/mcp.json`: `"NAME": {"enabled": false}`, see below |
| Oh My Pi | Yes | `.omp/mcp.json`: `"NAME": {"enabled": false}` shadows the same-named user entry |
| Codex | No | See below |
| Every other client | No | Selecting one is an error; nothing is written |
Only the switch is written, except for OpenCode. Kilo Code and Pi keep the command or URL from
the global entry; OMP suppresses the disabled project entry before name deduplication,
so the same-named user entry cannot connect. The other clients are refused because they replace the whole global entry
with the project one, or have no project file, so a lone switch would break the
server instead of turning it off.
Codex is refused for a different reason. It does merge `.codex/config.toml` over the
global file field by field, so `enabled = false` alone would work on a machine whose
global config defines the server. On a machine where it does not, the merged entry has
no `command` or `url`, and Codex then fails to load its whole configuration with
`invalid transport`. `.codex/config.toml` is usually committed, so one teammate's switch
could stop Codex from starting for another. Turn the server off per machine instead,
with `enabled = false` in `~/.codex/config.toml`.
Pi replaces a global entry with the project entry of the same name, but since Pi 1.0.1
an entry without `command`, `url` or `type` is an override instead: it changes only
`enabled`, `exposure` and `toolExposure` of the global server, which keeps its args, env
and credentials. Pi's `/mcp` writes the same entry. Pi before 1.0.1 reports it as invalid.
On a machine whose global Pi config lacks the server, Pi reports at start that there is no
server to override, and loads the rest. The switch needs nothing from the global server,
so it works in project mode too. An entry that earlier releases wrote with the global
server's `command` or `url` is rewritten as the override on the next sync.
### OpenCode and Kilo Code
```bash
cd my-project
skillshare mcp add company-docs --disabled --target opencode --target kilocode
skillshare sync mcp
```
```yaml
# .skillshare/config.yaml
mcp:
servers:
company-docs:
disabled: true
targets: [opencode, kilocode]
```
OpenCode 2 replaces a global server with the project entry of the same name, and drops
an entry without its `type` and `command` or `url`, so a lone switch would leave the
server on. When the global config under `mcp.projects` defines the server, Skillshare
writes its type and executable name, or only its URL's scheme and host, next to
`"enabled": false`. OpenCode 1 reads the same entry. Args, env, headers, the executable's
directory and the URL's path and query stay out of the project file, which may be committed. A switch that already carries
them keeps them if the server later leaves the global config.
- If you turn the server back on in OpenCode, it starts with only the executable name or URL
origin from the project file, because that entry replaces the global one. Remove the
`disabled` entry from the project under `mcp.projects` instead, then sync.
- In project mode, or when the global config does not define the server, Skillshare can
only write `{"enabled": false}`. OpenCode 1 merges it; OpenCode 2 ignores it, and sync
says so. Turn the server off in OpenCode's global config there.
### Claude Code
Claude Code takes a whole server entry from one scope and never merges fields, so a
switch in `.mcp.json` would replace the server instead of turning it off. It keeps
its own per-project off list in `~/.claude.json`, the one the `/mcp` panel edits.
Skillshare adds the name there, under this project's absolute path, and writes
nothing to `.mcp.json`.
```bash
skillshare mcp add company-docs --disabled --target claude
skillshare sync mcp
```
- The list lives on your machine, not in the repository. Each teammate runs
`skillshare sync mcp` once in their own checkout.
- A name you turned off yourself in `/mcp` is never claimed or removed.
- If you turn the server back on in `/mcp`, the next sync reports a conflict.
Remove the entry from `.skillshare/config.yaml`, or replace to turn it off again.
- The list is keyed by the project's path, so moving the project needs a new sync.
### Rules
- **A project must be in scope.** Run it inside a project that has
`.skillshare/config.yaml` (created by `skillshare init -p`), pass `-p`, or put the
entry under a project root in
[`mcp.projects`](#manage-several-projects-from-the-global-config). In the global
`mcp.servers`, where no project is in scope, it is refused.
- **`disabled` stands alone.** The entry takes `targets` only. Adding `command`, `url`,
`env`, `headers`, `options`, `piOptions` or `tools` is an error.
- **`targets` can be left out.** The entry then follows the project's targets: on every
sync it goes to the clients the project uses that have a per-project switch. Under
`mcp.projects`, where Skillshare also knows the global server of that name, it is
narrowed further to the clients that server is written to. Changing the project's targets later needs no edit to the
entry. List `targets` to decide for yourself; an unsupported client in that list is
an error.
- **The name must match.** Skillshare does not read the Agent's global file, so it
cannot check that a server with this name exists there. A name that matches
nothing is harmless: the Agent ignores it.
- **To turn it back on**, remove the entry (`skillshare mcp remove company-docs`)
and sync. The switch is removed from the file it was written to: the project's own
file, or `~/.claude.json` for Claude Code.
- **A server Skillshare itself defines does not need this.** Unselect the Agent on
that server instead, and the next sync removes its entry.
In the dashboard, this is the **Turn off a global server** button. In project mode it
sits beside the **Servers** heading; on a project's MCP tab, beside **Add server**.
## Manage several projects from the global config {#manage-several-projects-from-the-global-config}
Project mode keeps each project's MCP settings in that project's
`.skillshare/config.yaml`, and you sync from inside the folder. If you would rather
keep every project in one place, list the project folders under `mcp.projects` in the
**global** config. One `skillshare sync mcp`, run from anywhere, then writes the global
files and every project's files in a single plan.
```yaml
# ~/.config/skillshare/config.yaml
mcp:
servers:
context7:
command: npx
args: ["-y", "@upstash/context7-mcp@4.4.1"]
targets: [claude, opencode]
projects:
~/work/project01:
targets: [claude, opencode]
servers:
context7: # off in this project only
disabled: true
~/work/project02:
servers:
internal-docs: # exists in this project only
url: https://example.com/mcp
targets: [opencode]
```
A project lists only what differs from the global config. A global server such as
`context7` needs no entry here: the Agent reads its global file and the project's file
together, so it already loads in every project. A `disabled` entry
[turns it off in that folder](#turn-off-a-global-server-in-one-project), for any of the
clients listed there.
Each key is a project folder: an absolute path, or one starting with `~`. Under it go
the same `targets` and `servers` that project's own `config.yaml` would hold under
`mcp`, and they are written to the same [project files](#native-destinations). A
project without `targets` inherits the global `mcp.targets`.
The preview names the file when one server appears in more than one place:
```text
context7 add opencode (~/.config/opencode/opencode.json)
context7 add opencode (~/work/project01/opencode.json)
```
Removing a project from the list removes the entries Skillshare wrote there on the
next sync, the same as removing a server.
To give several projects the same server, define it once with a YAML anchor and
reuse it:
```yaml
mcp:
projects:
~/work/project01:
servers:
internal-docs: &internal-docs
url: https://example.com/mcp
targets: [opencode]
~/work/project02:
servers:
internal-docs: *internal-docs
```
Keep the anchor inside `mcp.projects`. An alias to an anchor on `mcp.servers` also
works, but `skillshare mcp add` and the dashboard rewrite `mcp.servers`; when they
save, they write such an alias out in full so the file stays valid, and it no longer
follows later edits to the global server.
### Projects in the dashboard {#projects-in-the-dashboard}
In global mode the dashboard has a **Projects** page. It lists every folder under
[`projects`](/docs/reference/targets/configuration#projects) and `mcp.projects`, and each
project has an **MCP** tab.
![Project MCP tab: global servers switched per project, plus project-only servers](/img/projects-mcp-tab.png)
- **Add project** takes the folder and its targets. Tick **MCP** to list the folder under
`mcp.projects` as well.
- The **MCP** tab lists every global server with a switch. Turning one off saves a
`disabled` entry without `targets`, so it follows the project's targets as described
[above](#turn-off-a-global-server-in-one-project); turning it back on removes the
entry. Below it are the servers that exist in that project only.
- A server that is off shows the logos of the Agents it is off in. A server that is on shows
the Agents it loads in, and none when a project server of the same name replaces it. When one of the
project's Agents has no per-project switch, the row says that the server still loads
there. An entry that lists its own `targets`, which differ from the project's, gets
**Match the project**: it saves the entry again without `targets`.
- The tab's **Agents** list, on the right, shows the project's Agents, those its own
servers go to, and any other Agent whose file is already in the project, with the file
name and **Copy path**.
**Open folder** and **Open in editor** work as on the MCP page.
- **Sync MCP** in the tab's Sync box writes the whole MCP plan, and says how many of
its changes are outside this project. **Sync project**, at the top of the project
page, writes only this project's skills, agents and MCP.
- **Defaults**, at the bottom of the MCP page, edits `mcp.targets`.
- When the project's own Agent files hold servers Skillshare does not manage, the tab
says so above the lists, with **Import**. See [below](#unmanaged-servers).
Saving rewrites only the project you changed. Other projects keep their YAML as written,
anchors and aliases included, and a folder written as `~/work/app` keeps its `~`. As
everywhere on this page, saving changes `config.yaml` only; Sync writes the files.
Limits:
- `mcp.projects` is read from the global config only. A project config that contains
it is refused.
- No command edits it: `skillshare mcp add` manages `mcp.servers` and leaves
`mcp.projects` as written. Edit it in `config.yaml`, or in the
[dashboard](#projects-in-the-dashboard).
- A `disabled` entry for Claude Code is written to `~/.claude.json`, the same file the
global servers go to, because that is where Claude Code keeps its per-project off
list. The servers themselves are left as they are.
- If a folder also has its own `.skillshare/config.yaml` managing the same entry, the
plan reports a conflict rather than overwriting it.
## Check servers before an Agent starts them {#check-servers-before-an-agent-starts-them}
```bash
skillshare mcp check
skillshare mcp check docs github --json
skillshare mcp check --no-dns
```
`mcp check` answers "will this server work as synced?" for every server in the
source, or only the named ones. In the global config it also checks the servers of
every root under [`mcp.projects`](#manage-several-projects-from-the-global-config),
with each Agent's rules and sync state read for that root. It is read-only: it never starts a server, sends an
HTTP request, runs a command or writes a file, unless you add [`--live`](#probe-servers-live).
| Check | Level |
|---|---|
| A `fromEnv` variable in `env`, `headers` or `bearerToken` is unset or empty | error |
| A local server's `command` is not found on `PATH` (a leading `~/` is expanded) | error |
| A local server runs `npx`, `uvx`, `pipx run`, `docker run` or `podman run` on a package without an exact version (none, `latest`, a dist-tag such as `next`, a range such as `^1.2`, or a `==1.*` wildcard), including each npx `--package` and uvx `--with`, or on an image with no tag or `latest` | warning |
| A local server's image has a tag but no `@sha256:` digest, so the tag can move | info |
| A remote server's host does not resolve through DNS (3-second limit; skip with `--no-dns`) | warning |
| An Agent's rule refuses the server, such as a name Claude Code reserves | error |
| An Agent's entry conflicts with the source, as in `sync mcp --dry-run` | error |
| An Agent's entry is not written or not updated yet | warning |
| The server has `targets: []` and is kept in Skillshare only | info |
| A selected Agent cannot hold part of the server's [tool policy](#tool-policy) | warning |
Variable values are never printed. The command exits with 1 when any error is found
and 0 otherwise; warnings never fail it. An unknown server name is an error that
lists the known names. A name selects every server of that name, globally and in
each project, and the known names include project servers.
In the terminal, a project server's heading names its project:
```text
✓ docs
· claude: in sync
✗ docs (project ~/work/app)
✗ command no-such-mcp-binary was not found on PATH
! claude: not synced yet; run skillshare sync mcp
```
With `--json`, the report has this shape:
```json
{
"servers": [
{
"name": "docs",
"ok": false,
"findings": [
{ "level": "error", "check": "env", "target": "", "message": "bearerToken reads DOCS_TOKEN, which is not set", "subject": "DOCS_TOKEN" },
{ "level": "warning", "check": "sync", "target": "claude", "message": "not synced yet; run skillshare sync mcp" }
]
},
{
"name": "docs",
"project": "/home/me/work/app",
"ok": true,
"findings": [
{ "level": "info", "check": "sync", "target": "claude", "message": "in sync" }
]
}
],
"summary": { "errors": 1, "warnings": 1 }
}
```
`check` is one of `env`, `command`, `pin`, `url`, `dns`, `client-rule`, `sync`, `targets`,
`tools`, `tool-change` or `live`.
`target` names the Agent or account, and is empty when the finding is about the
server itself.
`subject` names the variable, command, package, image or host for `env`, `command`,
`pin` and `dns` findings, the name a server reports for a successful `live` probe, and the resource
metadata URL of a `live` sign-in warning; it is omitted otherwise.
`project` is the server's `mcp.projects` root as an absolute path (a leading `~` is
expanded), and is omitted for a global server. `summary` counts every server in the
report, project servers included.
In the dashboard, the **Check** button in the MCP page's Sync box runs the same check.
It appears once there are servers to check, runs only when clicked, shows a summary
above the server list and each error or warning under its server, and keeps nothing
after the page reloads. The MCP page lists global servers only, so its summary and rows
leave project servers out, even one that shares a global server's name. A project's
MCP tab has its own **Check** in its Sync box, which reports that project's own servers. Variables are read from
the terminal that started `skillshare ui`.
### Probe servers live {#probe-servers-live}
```bash
skillshare mcp check --live
skillshare mcp check docs --live --timeout 30s --json
```
`--live` runs the static checks first, then contacts each selected server that has no
error. A server with an error, or a disabled entry, is not contacted; an `info` finding
says why.
- **Local (stdio) servers.** Skillshare starts `command` with `args` in your current
environment, plus the server's `env` with each `fromEnv` value read from your shell.
A project server starts in its project folder, a global server in the current
directory. This runs the server's code on your machine as an Agent would, so use
`--live` only for servers you trust. Skillshare sends `server/discover`. A server that
answers with an error that is not an MCP protocol error, or does not answer within a
third of the timeout, is treated as older than MCP 2026-07-28 and gets the
`initialize` handshake instead. Skillshare then calls `tools/list` to count the tools
and stops the server: it closes stdin, then sends SIGTERM and then SIGKILL to the
server's process group. On Windows it terminates the process.
- **Remote (Streamable HTTP) servers.** Skillshare POSTs `server/discover` with the
server's `headers` and `bearerToken`, and reads a JSON or an SSE response. A `400`,
`404` or `405` without an MCP error falls back to `initialize`. A `401` is a warning,
"sign-in required", with the resource metadata URL from the `WWW-Authenticate`
header. Skillshare never signs in or starts OAuth.
Each server has one time limit for its whole probe: 10 seconds, or `--timeout` (such as
`30s` or `1m`). Up to four servers are probed at once. `--timeout` without `--live` is
an error.
| Result | Level |
|---|---|
| The server answered: its name and version, protocol version and number of tools | info |
| A remote server needs sign-in (HTTP 401) | warning |
| The command could not start, exited early, or did not answer in time | error |
| A protocol error, an unsupported protocol version, or any other HTTP status | error |
| First successful probe of a server: its tool definitions are pinned | info |
| A tool's description or input schema differs from the pin, or the server lists a tool that was not pinned | warning |
| A pinned tool is no longer listed | info |
When a local server fails, the message ends with up to five lines of its stderr. The
values of `env`, `headers` and `bearerToken` are removed from every message; values
shorter than four characters are left as they are. Values are passed as written:
Skillshare never runs a Pi `!command` value and does not read `piOptions`. The exit
code follows the same rule, 1 when any error is found. `--live` writes no config file
and no operation log entry; it keeps only the [tool pins](#pin-tool-definitions) in the
state directory.
With `--json`, a server that answered also gets a `live` object:
```json
{
"name": "docs",
"ok": true,
"findings": [
{ "level": "info", "check": "live", "target": "", "message": "responds: docs-server 1.4.0, protocol 2026-07-28, 12 tool(s)", "subject": "docs-server" }
],
"live": { "protocolVersion": "2026-07-28", "serverInfo": { "name": "docs-server", "version": "1.4.0" }, "tools": 12 }
}
```
`serverInfo` is what the server says about itself; nothing verifies it. `live` is
omitted when the server was not probed or the probe failed.
The dashboard's **Check** button runs the static check only. The dashboard probes a
server in one place: **Load tools** in the server dialog's
[Tools section](#tool-policy-dashboard), which starts the server once, as the dialog's
fields describe it, to list its tools. With `--json`, `live` also holds `toolNames`, the names `tools/list` returned.
### Pin tool definitions {#pin-tool-definitions}
A server can change what a tool says or accepts after you reviewed it, which an Agent
then follows without asking. `--live` therefore pins each tool the first time a server
answers, and compares every later probe with the pin.
- **What is pinned.** One SHA-256 hash per tool over its `name`, `description` and
`inputSchema`, computed from canonical JSON: key order and whitespace do not matter.
The hashes are stored by scope (global, the `mcp.projects` root, or the project that
`-p` selects) and server name in `mcp/tool-pins.json` in the Skillshare state
directory, next to `state.json`. No description or schema text is stored.
- **First probe.** The baseline is recorded and one `info` finding with check `tool-change`
says so. No warning.
- **Later probes.** A tool whose description or input schema changed, and a tool that is
new since the pin, each get a `warning` named `tool-change` that lists the tool names. A
tool that is no longer listed is an `info`. The baseline stays as it was, so the same
warning appears until you accept it. Warnings do not make the exit code 1.
- **Accept.** Review the tools, then run `skillshare mcp check docs --live --accept-tools`.
Every selected server that was probed records what it listed now as its baseline, and
an `info` finding lists the tools that changed, were added or removed. `--accept-tools`
without `--live` is an error. Each acceptance is recorded in the operations log
(`skillshare log`) with the servers it accepted. A name selects that server globally and in each
`mcp.projects` root, and each of them is accepted, so review every one the report lists.
An unreadable `tool-pins.json` (or one a newer version wrote) is a warning on each probed
server and is never rewritten, not even by `--accept-tools`, since it may hold other
servers' pins: move it away to pin again.
Without `--live` the pins are neither read nor written. A server you edit (another
command, another URL), or remove and add again, keeps its pins under the same name:
accept the new definitions once if its tools legitimately differ.
`GET /api/mcp/check?live=1` (the endpoint behind the dashboard's **Check** button, which
does not send `live`) also pins and compares, but cannot accept.
## Stop managing a server {#stop-managing-a-server}
```bash
skillshare mcp remove docs --keep-files
```
This removes `docs` from the source and forgets which Agent entries Skillshare wrote
for it. No Agent file changes. From then on those entries are yours: sync neither
removes nor updates them. `--keep-files` cannot be combined with `--sync`. The
terminal remove wizard offers it as **Stop managing**, and so does the dashboard's
remove dialog, on the MCP page and in a project's **MCP** tab.
Only the scope you remove it from changes. Stopping a global server leaves a project's
server of the same name managed, and the other way round. To manage an entry again,
import it.
## Servers Skillshare does not manage {#unmanaged-servers}
The dashboard reads the Agent config files of the current scope, and of every folder
under `mcp.projects`, for servers that this source does not define and no Skillshare
configuration manages. When it finds some, a note above the server list says how many
and in which Agents. **Import** opens the import with the first of those Agents
selected. A project's **MCP** tab shows the same note for that project's own files;
its import reads the project's file and saves the servers to that project. Entries
with nothing to connect to, such as Goose's built-in extensions, are not counted.
### Take over an entry an Agent already has
When you add a server under a name an Agent file already uses, sync does not
overwrite that entry. The plan reports a conflict, `existing entry is not managed`,
and writes no files until you choose for that entry:
- Import it from that Agent: `skillshare mcp import NAME --from CLIENT`, or the
conflict's **Import from** button in the dashboard, such as **Import from Cursor**.
An entry that matches the source is adopted as it is. For a conflict in a folder under
`mcp.projects`, the button reads that folder's file and imports into that project.
- Replace it with the source definition: **Replace with source** in the dashboard, or
`--replace` on import.
## Serve skills over MCP {#serve-skills-over-mcp}
```bash
skillshare mcp serve # stdio, every enabled skill
skillshare mcp serve --target claude # only the skills the claude target selects
SKILLSHARE_MCP_TOKEN=change-me skillshare mcp serve --http 0.0.0.0:8765 \
--tls-cert cert.pem --tls-key key.pem # HTTPS for other machines
```
`mcp serve` is an MCP server, read-only unless you [turn on editing](#edit-skills-over-mcp), for an Agent that cannot reach the folder
your skills sync to, such as one on a disposable VM or behind an MCP gateway. It
implements the [Skills extension](https://modelcontextprotocol.io/seps/2640-skills-extension)
(`io.modelcontextprotocol/skills`, SEP-2640): `skills/list`, `skills/get` and
`resources/read`. Each skill is one entry whose URI follows its source path, such as
`skill://_team/tools/pdf/SKILL.md`, with its full frontmatter and every file with a
`sha256` digest and size. Agents on your own machine already receive skills through
`sync`; connecting them to `mcp serve` as well shows each skill twice.
Most Agents do not support the Skills extension yet (see below), so the server also offers
two tools: `list_skills` lists names, descriptions and URIs (`query` narrows them; one
answer lists at most 200), and `read_skill` reads a `SKILL.md` or another file of a skill,
and for a `SKILL.md` lists the skill's other files. Any Agent that uses MCP tools can read
skills this way, including through a gateway that passes tools on. A client that declares
the Skills extension loads skills natively and is not offered these two tools, so it does not
see each skill twice. Both tools are marked `readOnlyHint`, so a client or gateway that
asks before tools that change data calls them without asking. Content read through a tool
is ordinary text to the Agent: its own skill approval does not apply.
- **Selection.** Without `--target`, every enabled skill is served. `--target NAME`
applies that target's `include`/`exclude` filters and frontmatter `targets`, whatever
its sync mode; skills always come from the source. A target with skills turned off is
an error.
- **Skipped skills.** A skill is skipped, with a warning on stderr, when its `SKILL.md`
is a link or does not begin with its frontmatter, when its `name` breaks the Agent Skills naming
rules or differs from its directory name (for example after `install --name`), when
its description is missing or over 1,024 characters or its `compatibility` is empty or over 500,
when it has more than 512 files
or 16 MiB, or when it contains a nested skill that is not served.
`skillshare mcp serve --check` lists those skills and their reasons, with the same
selection flags, and exits without serving.
- **Changes.** The source is read again at most every 5 seconds, so `install`,
`update`, `enable` and `disable` show up without a restart. Results carry
`ttlMs: 5000`.
- **Scope.** Global by default, wherever the server is started. `-p` serves the project
in the current directory.
- **Transport.** stdio by default, for a gateway or Agent that starts the command.
`--http ADDR` serves Streamable HTTP. A non-loopback address requires
`SKILLSHARE_MCP_TOKEN` and, by default, HTTPS through `--tls-cert` and `--tls-key`.
For a trusted private network, `--http-allow-insecure` explicitly allows
plain HTTP and prints a startup warning. The token is still required off loopback.
When the token is set, every request must
send `Authorization: Bearer <token>`. To use a TLS proxy instead, bind a loopback
address such as `127.0.0.1:8765` and let the proxy terminate TLS. Without the token,
that server answers only requests whose `Host` is a loopback address, so set the token
or have the proxy send such a `Host`.
- **Safety.** Only files in a skill's manifest can be read, and reads stay inside the
skill directory. Links and `.git` are neither listed nor served. Nothing is executed,
and nothing is written unless editing is on. With `--http`, cross-origin browser requests to the MCP endpoint are refused; the Executor index answers reads only, which a page on another origin cannot see.
For a server and MCP gateway in separate containers on a trusted private Docker
network, with no TLS terminator between them:
```bash
# Set SKILLSHARE_MCP_TOKEN in the server environment and the gateway's bearer config.
skillshare mcp serve --http 0.0.0.0:8765 --http-allow-insecure
```
This sends the token in plain text. Use it only when the network is trusted;
public or untrusted networks should use TLS. The default still refuses plain HTTP
off loopback. The opt-in does not change loopback or HTTPS behavior.
To connect an Agent, add the server like any other and sync it. On the machine that
runs the Agent:
```bash
skillshare mcp add skillshare --target codex --sync -- skillshare mcp serve --target codex
```
In the dashboard, **Add server** → **Skillshare** builds the same command (with `-p` in
project mode) from a choice of skills; tick the Agent, save and sync. Editing that server
opens the same tab.
For an Agent on another machine, run `mcp serve --http` with a certificate where the
skills are and point a remote server at it. Keep the token in an environment variable:
```yaml
mcp:
servers:
skillshare:
url: https://skills-host:8765/
bearerToken: { fromEnv: SKILLSHARE_MCP_TOKEN }
targets: [codex]
```
Loading skills natively needs the Skills extension. As of October 2026 the common coding
Agents do not have it yet, so they use the tools: Codex, Cursor, VS Code, Goose and Pi have no support, and Claude Code includes
support that is not switched on by default. Only a few clients such as mcpc, fast-agent and
MCP Inspector do, some in part. The SEP's list of prototype hosts, such as a Codex fork,
does not mean the released Agents support it. The
[extension support matrix](https://modelcontextprotocol.io/extensions/client-matrix) lists
the current clients.
To check the server itself, MCP Inspector 2.6.0 or later reads every skill, compares its
frontmatter and checks each file's digest:
```bash
npx @modelcontextprotocol/inspector --cli skillshare mcp serve --method skills/list --verify
```
### Edit skills over MCP {#edit-skills-over-mcp}
An Agent that reads skills through `mcp serve` can also change existing skill files,
for the skills you list in config:
```yaml
mcp:
serve:
edit:
skills: [pdf, _team__*] # flat names, matched like a target's include
preview_ttl: 30m # how long a preview can be applied; default 30m
```
The server then offers two more tools, also to clients that load skills natively:
1. `preview_skill_edit` takes a file's URI, its revision, and the complete new content.
With editing on, `read_skill` ends a file with `Revision: sha256:...`, the same value
as the file's `digest` in `skills/list`; that footer is not part of the content. The
preview writes nothing. It returns the full diff, the audit findings, and a preview id.
2. `apply_skill_edit` takes only that preview id and saves exactly what was previewed,
after checking and auditing the skill again as it will be saved.
It is marked `destructiveHint`, so a client that asks before such tools asks the user.
An edit is refused, and nothing is written, when:
- **`not_writable`**: the skill is not listed, it sits inside a tracked repo, or it was
installed from upstream. `update` would overwrite those changes.
- **`conflict`**: the file changed after it was read or previewed. Read it again.
- **`invalid`**: the skill would fail validation with the new content, or the file is
not UTF-8 text.
- **`audit_blocked`**: with the new content the skill has a finding at or above
`audit.block_threshold`, or the audit could not run. As with `install`, a finding
accepted with `install --force` does not block. Each finding is marked new or existing,
matched by rule and matched line rather than line number, so you can see what the
edit adds.
- **`expired`**: the preview is older than `preview_ttl`, was already applied, or the
server restarted.
Only existing files can change: an edit cannot create, delete, or rename a file. The
write is atomic, keeps the file's mode, and goes through the same link checks as other
writes to the source. Each save is recorded in the operation log as `mcp serve`, with
the file and its old and new revision, and each audit in the audit log (`skillshare log --audit`).
While the source still has a legacy `registry.yaml`, no skill is editable; any other
command migrates it. Targets receive the change on the next `sync`.
`skillshare mcp serve --check` reports how many served skills are editable.
### Load skills into Executor {#executor}
With `--http`, the server also publishes its skills in the index that
[Executor](https://github.com/UsefulSoftwareCo/executor) apps load with
`wellKnownSkills`, at `/.well-known/agent-skills/index.json`, with each file at
`/.well-known/agent-skills/<name>/<path>`. An edit saved through `apply_skill_edit`
reaches Executor on its next check, with no commit or push. The format is the one
Executor's loader reads (`{skills: [{name, version, files}]}`), not version 0.2 of the
agent-skills discovery draft.
```ts
const skillshare = defineProvider({
name: "Skillshare",
hosts: ["skills-host:8765"],
auth: { token: secrets({ label: "Token", fields: object({ token: string() }) }) },
});
export default defineApp({ app: { accounts: { skillshare } } }, async (ctx) => ({
dynamicSkills: dynamicSkills({
list: () =>
wellKnownSkills({
url: "https://skills-host:8765/",
cache: ctx.cache.forAccount(ctx.app.accounts.skillshare),
signal: ctx.signal,
fetch: (input, init) => {
const headers = new Headers(init?.headers);
headers.set("Authorization", `Bearer ${ctx.app.accounts.skillshare.fields.token}`);
return ctx.fetch(input, { ...init, headers });
},
}),
}),
}));
```
- **Skills it leaves out.** One skill Executor rejects fails its whole load, so the index
leaves out a skill whose `metadata` values, `license` or `allowed-tools` are not text,
that has a file over 2 MB, a file that is not UTF-8 text (such as an image), or a file
name Executor cannot decode (such as one with `%` or `\`), or whose name another
served skill also uses (all of them are left out).
- **Limits.** Executor loads at most 1,000 files and 20 MB from one index, and reads at
most 2 MB of `index.json`. Over that, the index answers with an error; serve fewer
skills with `--target`, one server per index.
- **Versions.** Each entry's `version` is a digest of its file paths and digests, so
Executor reloads only after a change. The index is the same byte for byte while
nothing changes.
- **Token.** The same bearer token protects the index and the MCP tools, including the
edit tools when editing is on. To give Executor read-only access, run a separate
`mcp serve` without `mcp.serve.edit`. `cache: ctx.cache.forAccount(...)` keeps one
account's skills out of another's cache.
- **Reaching the server.** By default Executor Cloud and self-hosted Executor refuse
private and loopback addresses, so Cloud needs a public address. A self-hosted
operator allows them with `EXECUTOR_APPS_ALLOW_PRIVATE_FETCH=true`, and the Executor
host still needs a route to the server and must trust its certificate. Executor
refuses redirects, so a proxy in front must not redirect, such as to add a trailing slash.
`skillshare mcp serve --check` lists the skills the index leaves out, and how many skills,
files and bytes it serves. `--http` prints the index URL and warns about the same skills on
stderr when it starts.
## Safety and limitations
- JSONC comments and unrelated settings are preserved. Changed owned entries
are replaced as a unit, so comments inside those entries may change. Only the
fields Skillshare writes are compared and replaced; Agent-specific fields such
as timeouts are kept. Fields set through [`options`](#agent-options) are written
and removed by sync.
Defaults an Agent fills in, such as `"type": "stdio"`, an empty `env` or
header name case, are not changes. Turning a managed server off with
`enabled: false` or `disabled: true` is reported as a conflict.
Pi and OMP are exceptions: changing `enabled` alone on a connection entry does not cause an ownership conflict. A source `piOptions.enabled` still takes precedence on sync.
- A preview stays valid while an Agent rewrites unrelated settings in the same
file, as Claude Code does with `~/.claude.json`. Only a change to that file's
MCP entries requires a new preview.
- Codex and Grok edits support ordinary `[mcp_servers.NAME]` tables and their subtables.
Updated entries stay in place, and CRLF line endings are kept.
Inline/dotted MCP definitions must be converted to tables before writing;
they are rejected without modifying the file.
- Native file symlinks, malformed files and duplicate JSON properties block
writes. A symlinked Skillshare `config.yaml` is written through to its target. In a project, a project config or `sources.mcp` file that resolves outside the project is refused instead. File permissions are preserved; new native
files, ownership records and backups use private permissions.
- An entry that already matches the source is reported as unchanged without a
write, for example after pulling a teammate's change. If this configuration
did not manage it before, such as when you tick an Agent after importing from
it, the plan shows `adopt`: sync records the entry as managed without changing
the file, and from then on removing the server or unticking that Agent removes
it. A server you turned off in the Agent itself stays yours. A different
unmanaged entry requires import or an explicit per-entry replacement; another
Skillshare configuration's ownership cannot be overridden while that
configuration file still exists. If that file is gone it can never release the
entry, so the conflict says the entry is left over, names the file, and takes it
over on an explicit import or replacement, in the terminal and from the conflict
in the dashboard. A file that only cannot be read, such as one on a drive that is
not mounted, still counts as the owner being there.
- The dashboard's MCP settings work only when the browser opens the dashboard by
`localhost`, an IP address or a trusted origin. Any other domain name gets
403, because DNS rebinding attacks always use a domain name; see
[Reverse Proxy](/docs/reference/commands/ui#reverse-proxy).
- Credentials use environment references; no secret store, OAuth session sync,
continuous health monitoring, package installation, gateway, registry or plugin sync.
`mcp check --live` is the only command that starts or calls a configured server;
`mcp serve` runs Skillshare's own skills server, read-only unless `mcp.serve.edit` is set.
- VS Code Insiders, custom profiles, remote workspaces and legacy SSE are not
supported in this version.
- VS Code does not currently substitute `${env:VARIABLE}` inside `headers`
([microsoft/vscode#336232](https://github.com/microsoft/vscode/issues/336232)),
so header and `bearerToken` references synced to VS Code reach the server
unresolved until that is fixed.
- Local operation records live under the Skillshare state directory's `mcp/`:
`state.json`, `pending.json` during a write, `tool-pins.json` (the
[tool pins](#pin-tool-definitions) of `mcp check --live`), and `backups/` (the newest 20
per Agent file). Do not share this
directory as a portable manifest.
## Tool policy {#tool-policy}
`tools` says which of a server's tools reach the model. Write it once on the server;
Skillshare translates it into each Agent's own fields on sync.
```yaml
mcp:
servers:
github:
command: github-mcp
targets: [pi, codex, copilot, opencode]
tools:
allow: [get_*, search_code, list_issues]
deny: [get_secret]
```
```bash
skillshare mcp add github --target pi --target codex --tools-allow 'get_*,search_code' --tools-deny get_secret -- github-mcp
skillshare mcp edit github --tools-allow '' # clear the allow list
skillshare mcp import github --from claude --target pi --tools-deny get_secret
```
| Field | Meaning |
|---|---|
| `allow` | When set, only the matching tools stay |
| `deny` | The matching tools are removed, even when `allow` matches them |
Entries in `allow` and `deny` are tool names, where `*` matches any characters. Other
wildcards (`? [ ] { }`), spaces and commas are refused, and so is a name listed twice.
A `deny` list that removes every tool `allow` keeps is an error. `tools` cannot be set
on a `disabled` entry. The two flags work with `mcp add`, `mcp edit` and
`mcp import`; lists are separated by commas, and an empty value clears that part.
How Pi offers the tools is not part of the policy: it is Pi's `exposure`, set in
[`piOptions`](#pi-options).
### What each Agent receives {#tool-policy-agents}
Not every Agent can hold every part of a policy. Skillshare writes what the Agent's
documented format supports and names the rest; it never drops a part silently.
| Agent | What is written | Not applied |
|---|---|---|
| [Pi](https://github.com/earendil-works/pi/blob/v0.99.0/packages/coding-agent/docs/mcp.md) | `toolExposure` with denied tools `hidden`, then allowed tools, then `"*": "hidden"` when `allow` is set | Nothing |
| [Codex](https://developers.openai.com/codex/config-reference) | `enabled_tools` and `disabled_tools`, exact names only. Codex applies `disabled_tools` after `enabled_tools` | `*` patterns in `allow`; `*` patterns in `deny` that cannot be folded into an exact `allow` list |
| [Copilot CLI](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers) | `tools`: the exact allowed names minus the denied ones, otherwise `["*"]` | `*` patterns in `allow`; `deny` when `allow` does not list exact names, since Copilot has no deny list |
| [OpenCode](https://opencode.ai/docs/permissions/), [Kilo Code](https://kilo.ai/docs/code-with-ai/platforms/cli#permissions) | Nothing | All of it. Both filter tools only in a top-level `permission` map keyed by `<server>_<tool>`, outside the server's entry |
| Every other Agent | Nothing | All of it |
In Pi an exact tool name beats any pattern, so an allowed exact name that a denied
pattern matches is left out of `toolExposure`. Allowed tools get the server's
`piOptions.exposure`, or Pi's default `codemode` when that is unset or `hidden`: `hidden` with
`allow` therefore means only the allowed tools are visible.
The unapplied parts appear in three places:
- The sync plan, as a warning line per Agent that lists the servers:
```text
! tool policy not applied for opencode: allow, deny (github)
```
With `--json` the same text is in the plan's `notices`.
- [`mcp check`](#check-servers-before-an-agent-starts-them), as a `tools` warning for
each Agent.
- The dashboard, in the server dialog's Tools section and in **View what each Agent
gets**. The dashboard shows no page-level notice for these, or for the retired Pi
settings below.
Codex's `enabled_tools` and `disabled_tools` are managed fields: clearing the policy
removes them, and editing them by hand in a Skillshare-owned entry shows up as a
conflict. Import reads Codex's `enabled_tools`/`disabled_tools` and Copilot's `tools`
back into `tools`. Pi's `toolExposure` becomes `tools` only when writing that policy
next to the server's `exposure` gives exactly the same `toolExposure`; otherwise it stays
in `piOptions`, with a warning. `exposure` always stays in `piOptions`.
### Tools in the dashboard {#tool-policy-dashboard}
The server dialog has a **Tools** section after the targets, for every server except a
`disabled` entry, and is always shown. Beside the title, an info
icon explains the section and a summary shows `All tools`, the policy (such as
`Only 1 allowed, 2 excluded`), or `9 of 14 selected` once the tools are loaded.
- The box under the title holds the tool list. Before loading it offers **Load tools**,
which starts the server once with the settings in the dialog, saved or not, using the
same probe as [`mcp check --live`](#probe-servers-live). It runs only when clicked and
saves nothing, so it also works for a new server. A failure is described in plain words,
with the raw error in the info tooltip beside it, and the button becomes **Retry**.
Changing the command, URL, or their settings afterwards clears the loaded list.
- Once loaded, each tool has a checkbox, and a ticked tool reaches the model. Unticking a
tool adds its exact name to `deny`. Ticking it removes that name from `deny`, and adds
it to `allow` when a non-empty `allow` leaves it out. A tool that a `deny` pattern
removes cannot be ticked; its tooltip names the rule. The search box filters the list,
**Select all** and **Select none** act on the rows it shows, and the refresh button loads
the list again.
- The **Exclude rules** row at the bottom of the box takes `*` patterns and names the server
does not list; type one and press Enter. When `allow` has entries, an **Allow only** row
above it does the same for `allow`. Before the tools are loaded, every saved entry is
shown there. A bad name, or a deny list that removes every allowed tool, is shown in the
dialog and blocks **Save**.
- Below that, the dialog says what each selected Agent will get: which ones follow the list
as it is, what an Agent that follows part of it will do (for example, Copilot CLI still
offers unticked tools because it has no deny list), and which ones cannot filter tools.
The server row shows a tag with the policy in words, such as `Tools: 2 tools excluded`,
and **View what each Agent gets** warns per Agent about the parts it does not apply.
## Oh My Pi (OMP) {#omp}
`omp` is a separate client from Pi. Skillshare writes OMP's native `mcpServers`
map, with explicit `type: stdio` or `type: http` and `${VARIABLE}` environment
references. It never writes into `.pi/`, Claude or Codex configuration on OMP's behalf.
Server names must be at most 100 characters.
```bash
skillshare mcp add docs --url https://example.com/mcp --target omp -g --sync --no-tui
skillshare mcp import docs --from omp --target omp -g --replace --dry-run --json
```
Sync preserves `$schema`, `disabledServers`, `enabledServers` and unrelated servers.
It also keeps native per-server fields such as `enabled`, `timeout`, `instructions`,
`requestIdFormat`, `cwd`, `auth` and `oauth` when updating an existing connection.
These fields are not `piOptions`: Pi-only settings are never sent to OMP. Import
warns about native fields that cannot be represented by the portable model; keep
them in OMP's file. The portable model supports stdio and Streamable HTTP, not
OMP's legacy SSE transport; unsupported imports are refused rather than converted.
`disabledServers` wins over `enabledServers` and an entry's `enabled` value.
Sync does not remove a user denylist entry to activate a server. Import refuses
servers hidden by `disabledServers` or `enabled: false`, unless the latter is
force-enabled by `enabledServers`. JSON with OMP's schema or enable/disable lists
is recognized as OMP when pasted into the importer.
OMP can run env/header values beginning with `!` as shell commands. Skillshare
refuses exporting such literals or importing those credentials and never executes
them. Prefer `{fromEnv: VARIABLE}` in the source and `${VARIABLE}` in native JSON.
A same-name bare env reference, such as `"TOKEN": "TOKEN"`, imports as `fromEnv`;
set the variable before connecting, since the portable reference has no literal
fallback. Other client-specific interpolation needs conversion before import.
Global MCP honors `PI_CODING_AGENT_DIR`; project MCP remains `.omp/mcp.json`.
Since Pi uses the same environment variable, syncing both into the same file is
refused. Use separate directories or explicit account targets. Named-profile
and `PI_CONFIG_DIR` automatic path selection are not managed: declare a target
with `agent: omp` and `config_dir: ~/.omp/profiles/work/agent` for that profile.
Account targets are global-only; project definitions use `omp`.
After editing or syncing, run `/mcp reload` in OMP, then `/mcp list` to inspect the
source and connection status. Approval and OAuth login remain OMP's responsibility.
## Pi {#pi}
Pi ≥ 0.99.0 includes [built-in MCP](https://github.com/earendil-works/pi/blob/v0.99.0/packages/coding-agent/docs/mcp.md),
and it is the only way Skillshare writes MCP servers for Pi. The third-party
`pi-mcp-adapter` and `pi-mcp-extension` are no longer supported as sync destinations.
| Scope | File |
|---|---|
| Global | `~/.pi/agent/mcp.json` (`PI_CODING_AGENT_DIR` is honored) |
| Project | `.pi/mcp.json` |
Personal servers and servers with credentials belong in `~/.pi/agent/mcp.json`. Use
`.pi/mcp.json` only for servers the project needs, in trusted projects. Project entries
replace the entire global entry with the same name. Skillshare edits files directly
with preview and backup; it does not trust projects, launch servers, install
extensions, or authorize OAuth.
```bash
skillshare mcp add docs --url https://example.com/mcp --target pi --tools-deny 'delete_*' --pi-options '{"exposure":"deferred","timeout":120}' --no-tui
skillshare sync mcp --dry-run
skillshare sync mcp
```
```yaml
mcp:
servers:
docs:
url: https://example.com/mcp
targets: [pi]
tools:
deny: [delete_*]
piOptions:
exposure: deferred
timeout: 120
```
Native output uses `command`/`args` or `url`, with `${NAME}` environment references.
After a sync, run `/reload` or start a new Pi session, and use `/mcp` to inspect
connections and authorize OAuth. For simple Pi-only setup, `pi mcp add` edits the global
file; add `-l` for a project. `pi mcp list` checks connections by starting every enabled
server; `pi mcp login NAME` requires user approval.
Pi 1.0.4 adds `--no-mcp` to disable MCP for one run; `--tools` filters MCP tools
only when an entry starts with `mcp__`. Check these launch flags if a synced server
is unavailable.
Pi server names allow only letters, digits, `_` and `-`, and Pi reads names that differ
only in `-` and `_` as one server, so sync refuses the second. A Pi project entry replaces the
global entry of the same name; to turn off a global server in one project, see
[Turn off a global server in one project](#turn-off-a-global-server-in-one-project).
Since Pi 1.0.1, `/mcp` in Pi can add a project entry with only `enabled`, `exposure` or
`toolExposure`, which overrides the global server of that name. It is not a server, so
import skips it. A `disabled` entry writes the same override, so one that is exactly
`{"enabled": false}` is no conflict. Once sync has written the switch, Pi settings you add
to it in Pi, such as `exposure`, are kept as on any Pi entry sync manages; turning the
server back on in Pi is a conflict. If the project defines a server with the same name, or
an override sync did not write differs from the `disabled` entry, sync reports a conflict
until you replace the entry or remove the override in Pi.
### Other Pi settings {#pi-options}
`piOptions` holds the other per-server fields of Pi's built-in MCP. Only Pi receives
them.
- `oauth.clientRegistration` accepts `dcr` (Pi default) or `cimd` (Pi 1.0.1+). With
`cimd`, omit `clientId` and `clientName`; a `callbackUrl` must use HTTP on
`localhost` or `127.0.0.1` with path `/callback`. The authorization server must
support CIMD for public clients.
- `exposure` accepts `codemode` (Pi default), `codemode-deferred` (an older name for
`codemode`), `deferred`, `direct` or `hidden`. `toolExposure` maps tool names or wildcard patterns to one of those
values: an exact name wins, then the first matching pattern. Skillshare keeps the
pattern order through import and JSON/YAML conversion. `exposure` also decides how
the tools a [`tools`](#tool-policy) allow list keeps are offered. Prefer `tools` over
`toolExposure`, since it also reaches other Agents; a server cannot set both `tools`
and `toolExposure`.
- `timeout` (positive seconds), `cwd`, `enabled`, `oauth` and `auth` are validated. Unknown
fields, such as `description`, are passed through.
- `auth: {provider: NAME}` sends that provider's `/login` token as the bearer token. It
needs an https `url`, or http on localhost, and only works in global mode, because Pi
reads it only from its global file.
- `oauth.authServerMetadataUrl` (Pi 1.0+) must use https, or http on localhost, because
Pi trusts that document instead of discovery. Pi 1.0 keeps OAuth sign-ins per server
name and URL, so renaming a server or changing its `url` needs a new sign-in in Pi.
- Connection fields belong in the main form. `directTools`, `includeTools`,
`excludeTools` and the other `pi-mcp-adapter` settings are refused, because Pi's
built-in MCP does not read them; use `tools` instead.
- Top-level `settings` and `autoEnableCodemode` are not server options: edit them
directly in Pi; sync preserves them.
- Keep credentials in environment references. Literal `!command` values in portable
env/headers are refused, and so are command values anywhere in `piOptions`,
including non-secret fields such as `oauth.clientId`.
Clearing the JSON, or removing a field from it, removes the field from Pi's file on the
next sync when Skillshare wrote it and it is unchanged. A field you added in Pi yourself
stays. A field Skillshare wrote that was changed in Pi since blocks the sync until you
import it.
```bash
skillshare mcp edit docs --pi-options '{"timeout":60}' --no-tui
skillshare mcp edit docs --pi-options '{}' --no-tui
```
In the dashboard, the Pi block of the server dialog has **Tool exposure** and **Other Pi
settings**. The info icons beside **Pi settings** and **Tool exposure** explain them, and
a link beside **Pi settings** opens Pi's MCP documentation. The dialog flags
`pi-mcp-adapter` fields in **Other Pi settings** before you save. **Tool exposure** stays
editable while the Tools section has a setting; only `toolExposure` in **Other Pi
settings** is refused then, because `tools` writes it. On the server row, the Pi chip
shows the exposure in a few words, such as `through code` for `codemode`.
### Upgrading Pi from 0.22 {#pi-migration}
Before the first sync after upgrading, check two things in Pi:
- **Pi 0.99.0 or later.** Skillshare now writes Pi's servers only to `mcp.json`, which
Pi reads through its built-in MCP, added in 0.99.0. Older Pi does not read it, so the
servers stop loading until Pi is updated. Skillshare does not check Pi's version.
- **Remove `pi-mcp-adapter` or `pi-mcp-extension` from Pi** if either is still
installed. Pi's [MCP documentation](https://github.com/earendil-works/pi/blob/v0.99.0/packages/coding-agent/docs/mcp.md)
says an installed extension that registers `/mcp` replaces the built-in MCP.
`pi-mcp-extension` also reads `mcp.json` itself, and `pi-mcp-adapter` 3.0.0 and later
no longer read it, so the servers Skillshare moved do not load through the adapter.
When a sync moves servers off either extension, `sync mcp --dry-run`, `sync mcp` and
`--json` say so once:
```text
! Pi's built-in MCP needs Pi 0.99.0 or later; on older Pi these servers stop loading until Pi is updated. If pi-mcp-adapter or pi-mcp-extension is still installed in Pi, remove it, because it can take the place of Pi's built-in MCP
```
It appears when the sync removes an entry Skillshare wrote to `mcp-adapter.json`,
rewrites an entry it wrote for `pi-mcp-extension`, or finds settings only the extensions
read (`piExtension: pi-mcp-adapter` or `pi-mcp-extension`, `directTools`, and the
`piOptions` fields listed below). After that sync, it is gone.
0.23.0 removed the Pi mode choice (`piExtension`: `builtin`, `pi-mcp-adapter`,
`pi-mcp-extension`), the `piOptionsPrune` switch and `directTools`. An older config
still loads. `sync mcp --dry-run` and `sync mcp` print a warning for each kind of retired setting they found, naming the servers, for example:
```text
! Pi now uses its built-in MCP; the next sync updates the config: context7, local (shop)
```
A server found only under a project in `mcp.projects` shows the project folder in
parentheses.
What the next sync does:
| Before 0.23.0 | After the sync |
|---|---|
| `piExtension: builtin` | The key is removed; nothing else changes |
| `piExtension: pi-mcp-extension` | The key is removed. The entry already lived in `mcp.json`, so it is rewritten there in the built-in format |
| `piExtension: pi-mcp-adapter` | The key is removed. The server is written to `mcp.json`, and the entry Skillshare wrote in `mcp-adapter.json` is removed. Entries you added to `mcp-adapter.json` yourself are left as they are |
| `piOptionsPrune` | The key is removed. Sync always removes cleared fields that Skillshare wrote and that are unchanged ([above](#pi-options)) |
| `directTools` on a server | `true` → `piOptions.exposure: direct`; `"search"` → `deferred`; a list of names → `piOptions.toolExposure` with those tools `direct` |
| `mcp.directTools`, or a project's `directTools` under `mcp.projects` | The default is written into each server that reaches Pi and has no value of its own, as above. A project's `false` overrides the global value |
| `piOptions.includeTools` / `excludeTools` | `tools.allow` / `tools.deny`; a `directTools` next to them still becomes `piOptions.exposure` |
| Other `pi-mcp-adapter` fields in `piOptions`: `approveTools`, `auth` as a string (Pi's own `auth` object is kept), `bearerToken`, `bearerTokenEnv`, `bearerTokenStore`, `caFile`, `debug`, `exposeResources`, `idleTimeout`, `inheritEnv`, `lifecycle`, `protocolVersion`, `requestHeadersCommand`, `requestTimeoutMs`, `searchKeywords`, `socket`, `tasks`, `toolPrefix`, `trace` | Removed, because Pi's built-in MCP does not read them |
A `directTools`, `includeTools` or `excludeTools` that would overwrite an exposure the
server already sets, or that is not a list of tool names, is dropped with its own
warning.
The first sync that applies these changes also saves the Skillshare config without
the retired settings: `config.yaml`, or the file `sources.mcp` names. Before writing,
it keeps the old file in the [file history](/docs/reference/commands/backup#file-history)
with the reason `migrate`, and prints one line per file:
```text
→ Updated config.yaml for 0.23.0 (backup: <path of the saved version>)
```
This happens on `skillshare sync mcp`, `skillshare sync --all` (even when no Agent file
changes) and the dashboard's sync. `--dry-run` and previews write nothing. If saving the
config fails, the Agent files are already written and the config stays as it was; the
error says so, and the next sync tries again. After a successful save the warnings are
gone.
Removed flags now fail with a message:
| Flag | What to use |
|---|---|
| `--pi-extension` | Drop it. Pi always uses its built-in MCP |
| `--pi-options-prune` | Drop it. Sync always removes unchanged fields Skillshare wrote earlier |
| `--direct-tools` | `--pi-options '{"exposure":"direct"}'` for every tool, or `--pi-options '{"toolExposure":{"TOOL":"direct"}}'` for single tools in Pi |
`skillshare mcp import --from pi` still reads `pi-mcp-adapter`'s `mcp-adapter.json`,
next to Pi's `mcp.json`, so you can bring servers across. When both files define a
server, `mcp.json` wins. Sync writes the server to Pi's `mcp.json`; in
`mcp-adapter.json` it only removes entries it wrote there before 0.23.0. Its `directTools`, `includeTools` and
`excludeTools` are converted as above, and other adapter-only fields are left out with
a warning. In the dashboard, **Import from a target** lists the two Pi files as
separate sources.