Files
skillshare/website/docs/reference/commands/mcp.md
T
Willie 3873f1f060 docs(mcp): describe turning a global server off from mcp.projects
The pages still said a disabled entry cannot target Claude Code, and that the
field is project mode only. Both are lifted: the entry is valid under an
mcp.projects root as well, and for Claude Code the switch goes to
~/.claude.json, where Claude Code keeps its per-project off list, leaving the
server definitions in that file alone. Only the global mcp.servers, where no
project is in scope, still refuses it.

The dashboard sentence was stale from an earlier change: the switch is its own
"Turn off a global server" button beside "Add server", shown in project mode
and on a project's MCP tab, not an option inside the add form.

All four locales follow, naming the buttons as the dashboard shows them there.

Refs #286
2026-09-21 11:08:11 +08:00

35 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
--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
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.

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 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, tool lists and 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. 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 exports tools: ["*"] for new entries and preserves existing tool filters. 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, 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; if both exist in the selected directory, 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 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.

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 by skillshare init -p), pass -p, or put the entry under a project root in mcp.projects. In the global mcp.servers, where no project is in scope, it is refused.
  • disabled stands alone. The entry takes targets and, for Pi, piExtension. Adding command, url, env or headers is an error.
  • targets should be listed. Without it the entry inherits mcp.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.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 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.projects as well.
  • The MCP tab lists every global server with a switch. Turning one off saves a disabled entry 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.targets and mcp.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.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.
  • 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.

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 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.
  • 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. 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 it was moved or deleted it can never release the entry, so an explicit import or replacement takes it over. The conflict names the owning file.
  • The dashboard's MCP settings work only when the browser opens the dashboard by localhost or 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} inside headers (microsoft/vscode#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, and backups/ (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.