Cover the empty targets list, --target none, how it differs from leaving targets out, and what the terminal and the dashboard show for it. Refs #289
36 KiB
sidebar_position
| sidebar_position |
|---|
| 3 |
mcp
Manage portable MCP connection definitions and synchronize native Agent settings. Start with Set up MCP once.
Commands
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 remove docs --sync
skillshare mcp restore BACKUP_ID --dry-run
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 |
--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 |
--pi-extension PACKAGE |
Required when Pi is a target, with add, edit or import: pi-mcp-adapter or pi-mcp-extension, the one installed in Pi. See below |
--direct-tools VALUE |
Pi with pi-mcp-adapter, with add or edit: true, false, search, or tool names separated by commas. See below |
--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 |
--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-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.
sync mcp accepts scope flags, --dry-run, --json, --no-tui, and --revision.
sync --all includes skills, agents, extras and MCP; 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. Like the skills list, the manager
supports / to search and Enter for details. Connection lists hide argument,
header and environment values, and omit URL queries.
| Key | Action |
|---|---|
a |
Add a connection |
i |
Import one or more connections |
e |
Edit the selected connection |
x |
Remove the selected connection |
s |
Preview and confirm synchronization |
b |
Browse backups by client, then newest first |
r |
Refresh status |
q |
Quit |
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 and receiving
targets. 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. 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 (Space toggles,
a selects all). 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 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 |
directTools |
Pi with pi-mcp-adapter only: true, false, "search" or a list of tool names. See below |
disabled |
true only, no other connection fields, and a project must be in scope: project mode, or a root under mcp.projects. See below |
Client IDs are claude, codex, cursor, vscode, opencode, kilocode,
grok, antigravity, amp, claude-desktop, cline, copilot, factory, gemini,
goose, junie, kiro, lmstudio, warp, windsurf, and pi.
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.
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.
mcp:
targets: [claude, codex]
servers:
docs:
url: https://example.com/mcp
targets: []
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
targetsout is different. The server then inheritsmcp.targets, and it is refused when that list is empty too. nonecannot 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
disabledentry still needs at least one client, since it has to turn the server off somewhere. mcp listshows such a server askept 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
| 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 |
| 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 | ~/.config/amp/settings.json |
.amp/settings.json |
amp.mcpServers (literal key) |
| Claude Desktop | Claude application data directory, claude_desktop_config.json |
Global only | mcpServers |
| Cline | ~/.cline/data/settings/cline_mcp_settings.json |
Global only | mcpServers |
| Copilot CLI | ~/.copilot/mcp-config.json |
.github/mcp.json |
mcpServers |
| Factory Droid | ~/.factory/mcp.json |
.factory/mcp.json |
mcpServers |
| Gemini CLI | ~/.gemini/settings.json |
.gemini/settings.json |
mcpServers |
| Goose | ~/.config/goose/config.yaml |
Global only | extensions (YAML) |
| Junie | ~/.junie/mcp/mcp.json |
.junie/mcp/mcp.json |
mcpServers |
| Kiro | ~/.kiro/settings/mcp.json |
.kiro/settings/mcp.json |
mcpServers |
| LM Studio | ~/.lmstudio/mcp.json |
Global only | mcpServers |
| Warp | ~/.warp/.mcp.json |
.warp/.mcp.json |
mcpServers |
| Windsurf (Cascade) | ~/.codeium/windsurf/mcp_config.json |
Global only | 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; 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, and the files are written after you confirm on the Sync page. 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.
Additional client details:
- The
codexdestination is oneconfig.tomlthat the Codex CLI, the Codex IDE extension and the ChatGPT desktop app share, so a server synced tocodexappears in all three. The ChatGPT desktop app lists them under Settings → MCP servers. Codex reads.codex/config.tomlonly in a project it trusts; in an untrusted project the synced servers do not load, without an error.cwd,http_headers_helper, tool lists and approval modes, timeouts and theoauthtable have no portable form: import leaves them out with a warning and sync keeps them in the existing entry. MCP servers that a Codex plugin bundles are configured underplugins.<plugin>.mcp_serversand are not managed here. - Claude Desktop file sync supports stdio only, on macOS and Windows.
Its directory is
~/Library/Application Support/Claudeon macOS and%APPDATA%/Claudeon Windows. Configure remote connectors in the application. - Cline targets the default VS Code Stable profile, not Cline CLI or other IDEs.
- Copilot CLI exports
tools: ["*"]for new entries and preserves existing tool filters. If a project.mcp.jsonexists, 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
httpUrlfor Streamable HTTP. Itsurlfield means legacy SSE and is rejected on import. Cline usestype: streamableHttp; Goose usestype: streamable_httpanduri. 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 keychainenv_keyscannot be imported as portable MCP connections. - Claude Code skips a server named
workspace,claude-in-chromeorcomputer-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_PROXYandNPM_TOKENread as empty inurlandheaders. 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 addand no--scope, stored per project in~/.claude.json. A local server wins, whole, over one of the same name in.mcp.jsonor the user scope. In project mode Skillshare reports such a server next to the entry it hides, without blocking the sync. Remove it withclaude mcp remove NAME -s localfrom the project folder. - Cline's VS Code extension, CLI and SDK share
~/.cline/data/settings/. The extension moves its older VS CodeglobalStoragefile there once and then stops reading it, so Skillshare writes to the old file only while~/.cline/datadoes not exist yet.CLINE_MCP_SETTINGS_PATH,CLINE_DATA_DIRandCLINE_DIRare 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.jsononly afteramp mcp approve <name>. Global servers need no approval. - Kiro expands
${VARIABLE}only for names listed in its "Mcp Approved Env Vars" setting, and acceptshttp://URLs for localhost only. - VS Code keeps a separate
mcp.jsonfor each non-default profile underUser/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,
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 is supported through an explicitly
selected third-party extension; see below.
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 and Copilot paths respect CLAUDE_CONFIG_DIR, CODEX_HOME,
GROK_HOME and COPILOT_HOME. OPENCODE_CONFIG and OPENCODE_CONFIG_DIR are 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.
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 four 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": {"enabled": false} |
| Kilo Code | Yes | kilo.jsonc: "NAME": {"enabled": false} |
Pi with pi-mcp-adapter |
Yes | .pi/mcp.json: "NAME": {"disabled": true} |
Pi with pi-mcp-extension |
No | It has no disable field |
| Codex | No | See below |
| Every other client | No | Selecting one is an error; nothing is written |
Only the switch is written. The Agent keeps the command or URL from its global entry. 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.
OpenCode and Kilo Code
cd my-project
skillshare mcp add company-docs --disabled --target opencode --target kilocode
skillshare sync mcp
# .skillshare/config.yaml
mcp:
servers:
company-docs:
disabled: true
targets: [opencode, kilocode]
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.
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 mcponce in their own checkout. - A name you turned off yourself in
/mcpis 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.
Pi
Pi needs piExtension, as every Pi entry does, and it must be pi-mcp-adapter.
OpenCode and Kilo Code ignore that field, so one entry can cover all three:
skillshare mcp add company-docs --disabled --target pi --pi-extension pi-mcp-adapter
mcp:
servers:
company-docs:
disabled: true
piExtension: pi-mcp-adapter
targets: [opencode, pi]
Rules
- A project must be in scope. Run it inside a project that has
.skillshare/config.yaml(created byskillshare init -p), pass-p, or put the entry under a project root inmcp.projects. In the globalmcp.servers, where no project is in scope, it is refused. disabledstands alone. The entry takestargetsand, for Pi,piExtension. Addingcommand,url,envorheadersis an error.targetsshould be listed. Without it the entry inheritsmcp.targets, and any 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.jsonfor 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 beside Add server. It appears in project mode and on a project's MCP tab.
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.
# ~/.config/skillshare/config.yaml
mcp:
servers:
context7:
command: npx
args: ["-y", "@upstash/context7-mcp"]
targets: [opencode, pi]
piExtension: pi-mcp-adapter
projects:
~/work/project01:
targets: [opencode, pi]
servers:
context7: # off in this project only
disabled: true
piExtension: pi-mcp-adapter
~/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, 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. A
project without targets inherits the global mcp.targets, and one without
directTools inherits the global mcp.directTools.
The preview names the file when one server appears in more than one place:
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:
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
In global mode the dashboard has a Projects page. It lists every folder under
projects and mcp.projects, and each
project has an MCP tab.
- Add project takes the folder and its targets. Tick MCP to list the folder under
mcp.projectsas well. - The MCP tab lists every global server with a switch. Turning one off saves a
disabledentry for the Agents that have a per-project switch; turning it back on removes the entry. Below it are the servers that exist in that project only. - Defaults, at the bottom of the MCP page, edits
mcp.targetsandmcp.directTools.
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.projectsis read from the global config only. A project config that contains it is refused.- No command edits it:
skillshare mcp addmanagesmcp.serversand leavesmcp.projectsas written. Edit it inconfig.yaml, or in the dashboard. - A
disabledentry 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.yamlmanaging the same entry, the plan reports a conflict rather than overwriting it.
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.
Defaults an Agent fills in, such as
"type": "stdio", an emptyenvor header name case, are not changes. Turning a managed server off withenabled: falseordisabled: trueis reported as a conflict. - 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.yamlis written through to its target. 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 after moving a project, it stays unmanaged: removing the server leaves it in place until you import it. 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
localhostor an IP address. Through a domain name, including a reverse proxy, MCP requests return 403, because DNS rebinding attacks always use a domain name. - Credentials use environment references; no secret store, OAuth session sync, runtime health check, package installation, gateway, registry or plugin sync.
- VS Code Insiders, custom profiles, remote workspaces and legacy SSE are not supported in this version.
- VS Code does not currently substitute
${env:VARIABLE}insideheaders(microsoft/vscode#336232), so header andbearerTokenreferences 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.jsonduring a write, andbackups/(the newest 20 per Agent file). Do not share this directory as a portable manifest.
Pi: choose your MCP extension
Pi can use MCP through either pi-mcp-adapter or pi-mcp-extension. These are third-party packages listed on Pi's website, not built-in Pi features. Install one in Pi:
pi install npm:pi-mcp-adapter
Restart Pi after installation. In Skillshare's MCP form, select Pi, then choose
the package you installed. The import dialog offers the same choice. In the terminal,
mcp add / mcp edit guide the selection; scripts must supply --pi-extension:
skillshare mcp add docs --url https://example.com/mcp --target pi --pi-extension pi-mcp-adapter --no-tui
skillshare sync mcp --dry-run
skillshare sync mcp
The saved server definition is:
mcp:
servers:
docs:
url: https://example.com/mcp
targets: [pi]
piExtension: pi-mcp-adapter
For the other package, use pi-mcp-extension in both the install command and the
selection. Every server targeting Pi within a Skillshare source must choose the
same package, because both packages read the same destination file.
| Package | Native output | What to do after sync |
|---|---|---|
pi-mcp-adapter |
command/args or url; ${VARIABLE} references |
Restart/reload Pi; use /mcp to inspect connections. Tools connect on demand. |
pi-mcp-extension |
Explicit transport: stdio or streamable-http |
Restart Pi; new servers default to manual start with /mcp:start <server>. Existing lifecycle settings are preserved. |
Both use ~/.pi/agent/mcp.json globally and .pi/mcp.json in project mode.
Skillshare uses these Pi-specific files, not the adapter's shared .mcp.json or
~/.config/mcp/mcp.json inputs. Project entries override global entries with the
same name. For the adapter, a global PI_CODING_AGENT_DIR override is honored.
The extension does not honor that override; global sync refuses it rather than
writing a file the extension would ignore.
The adapter supports fromEnv in environment variables and HTTP headers.
The extension does not interpolate environment references: matching stdio
variables (for example TOKEN: {fromEnv: TOKEN}) are inherited from Pi's process
instead; renaming variables and environment-backed HTTP credentials are rejected.
Use the adapter for those cases. Skillshare never reads or copies secret values.
Direct tools
pi-mcp-adapter normally reaches a server's tools through one proxy tool. Its
directTools setting registers them as individual Pi tools instead. Set it on the
server; only Pi receives it, so the same server can still go to other Agents:
mcp:
servers:
context7:
command: npx
args: ["-y", "@upstash/context7-mcp"]
piExtension: pi-mcp-adapter
directTools: true # or [resolve-library-id], or "search"
targets: [opencode, pi]
| Value | What the adapter does |
|---|---|
true |
Registers every tool of this server |
| A list of names | Registers only those tools, by their original MCP names |
"search" |
Registers the tools inactive; a search activates the matches |
false |
Proxy only, written explicitly |
| Omitted | Skillshare leaves the field alone |
Omitted means untouched: a directTools you added to Pi's file yourself stays, and
removing the field from the config does not remove it from the file. Write
directTools: false to turn it off. It needs piExtension: pi-mcp-adapter and
cannot be combined with disabled.
From the command line, pass --direct-tools to mcp add or mcp edit. The dashboard
has the same choice under the Pi extension, once pi-mcp-adapter is selected:
skillshare mcp add context7 --target pi --pi-extension pi-mcp-adapter --direct-tools true -- npx -y @upstash/context7-mcp
skillshare mcp edit context7 --direct-tools resolve-library-id,get-library-docs
To set it once for every server, put directTools directly under mcp. It fills in
each pi-mcp-adapter server that has no directTools of its own; a server's own value
wins. This is a Skillshare default, written into each server's entry. The adapter's own
settings.directTools lives in the same file as the servers and is left to you.
mcp:
directTools: search # every pi-mcp-adapter server below, unless it says otherwise
servers:
context7:
command: npx
args: ["-y", "@upstash/context7-mcp"]
piExtension: pi-mcp-adapter
targets: [pi]
A project under mcp.projects can
hold its own directTools, which replaces the global default for that project. No
command edits the default. Set it in config.yaml, or in the dashboard under
Defaults on the MCP page, where it appears once Pi is one of the default targets.
Import with --from pi reads the Pi-specific file. An entry that has directTools
is imported with it and with pi-mcp-adapter selected, since only the adapter has
that field. Choose --pi-extension when
saving an imported connection; a file alone cannot identify which package is
installed. Unsupported legacy SSE remains blocked. OAuth and package-only options
stay managed in Pi. Sync success means the configuration was written, not that
an extension is installed or a server has connected.