MCP (External Tool Servers)

阅读简体中文版：zh_hans/MCP.md

ghosty can load additional tools via MCP (Model Context Protocol). MCP servers can be local stdio processes that the TUI starts, or remote URL-based servers that speak Streamable HTTP with legacy SSE fallback.

Browsing note:

• Web is the canonical, deferred built-in browsing tool; it provides search, fetch, and wait actions when network policy permits.
• web_search, fetch_url, and wait_for_dev_server are hidden replay-only aliases. New prompts and integrations should use Web.

Server mode note:

• ghosty serve --mcp runs the MCP stdio server.
• ghosty serve --http runs the runtime HTTP/SSE API (separate mode).
• ghosty mcp-server is an equivalent stdio entrypoint on the same consolidated runtime.

Setup wizard vs manual MCP setup (#3407)

The /setup hub includes an optional Tools and MCP step. That step is discovery/readiness only:

Wizard can do	Still requires manual / explicit action
Show configured servers as healthy / needs_config / off	Start or connect MCP servers
Report config path presence (global + project)	Write or edit mcp.json contents
Safe static health probe (missing command/url, broken absolute path, missing bearer env)	ghosty mcp validate, live connect, OAuth login
Point at safe on-ramps (/mcp, ghosty mcp init, ghosty doctor)	Install community skills, trust skills, enable plugins
Share Hotbar source counts from the same skill/MCP adapters (#3399)	Bind Hotbar slots (Hotbar step / H)
Record optional/needs_action setup_state without blocking first-run	Anything that spawns processes or installs packages

Empty inventory is not an error: first-run users see “nothing configured yet, that’s fine.” Failing or incomplete configured servers surface as needs_config with an actionable hint and never block setup completion. Enumeration never executes MCP/plugin commands beyond the static probe. Summaries redact commands, args, env, headers, and tokens.

ghosty doctor reports MCP/skills/tools/plugins health with the same optional-surface intent (paths, counts, static checks) so wizard and doctor stay consistent.

Plugin-contributed MCP

A reviewed local plugin bundle may contribute MCP servers without creating a second transport or approval system. The servers use the same MCP manager, tool approval, resource, prompt, timeout, and network-policy paths documented here, and appear under namespaced <plugin>-<server> identities.

The bundle boundary is intentionally stricter than user-authored mcp.json: unknown fields and ambiguous transports fail closed; stdio environment values must be exact environment-source references; remote literal headers and secret-bearing URLs are rejected; declared network hosts must exactly match the normalized endpoint host set; and redirects remain on the reviewed origin. Reviewed plugin remotes also bypass ambient HTTP proxy configuration entirely; proxy credentials and proxy-observed traffic are not part of the v1 review. The plugin review discloses local host-user authority, structural argv, environment provenance, endpoint, auth source names, scopes, and tool filters without reading or printing secret values.

Trust stages reviewed content but does not enable it. Enablement attaches that staged snapshot to the current workspace's MCP pool. Disable, revoke, and other cross-process generation changes remove catalog entries, cancel in-flight operations, and terminate plugin stdio children. Source or staged-tree drift is fully revalidated before each dispatch/catalogue boundary and fails the next boundary closed; v0.9.1 does not continuously hash mutable trees during an already-running call and therefore does not promise drift-triggered mid-call cancellation. MCP subscriptions are not exposed through plugin bundles. See Plugin bundles for the complete lifecycle contract.

Bootstrap MCP Config

Create a starter MCP config at your resolved MCP path:

ghosty mcp init

ghosty setup --mcp performs the same MCP bootstrap alongside skills setup.

Common management commands:

ghosty mcp list
ghosty mcp tools [server]
ghosty mcp add <name> --command "<cmd>" --arg "<arg>"
ghosty mcp add <name> --url "http://localhost:3000/mcp"
ghosty mcp add <name> --url "https://example.com/mcp" --bearer-token-env-var MCP_TOKEN
ghosty mcp login <name>
ghosty mcp logout <name>
ghosty mcp enable <name>
ghosty mcp disable <name>
ghosty mcp remove <name>
ghosty mcp validate

In-TUI Manager

Inside the interactive TUI, /mcp opens a compact manager for the resolved MCP config path. It shows each configured server, whether it is enabled or disabled, its transport, command or URL, timeout values, connection errors, and discovered tools/resources/prompts when discovery has been run.

Supported in-TUI actions:

/mcp init
/mcp init --force
/mcp import
/mcp recommendations
/mcp add recommended <id>
/mcp add stdio <name> <command> [args...]
/mcp add http <name> <url>
/mcp login <name> [--scope scope]
/mcp logout <name>
/mcp enable <name>
/mcp disable <name>
/mcp remove <name>
/mcp validate
/mcp reload

Suggested plugins and companion integrations

/mcp recommendations is Ghosty's native, curated suggestions surface. The entries are described as product plugins, with their component type and provenance, but /mcp add recommended <id> still writes only the named MCP server component. Viewing recommendations never fetches, installs, trusts, or enables anything. Adding one writes configuration; the server is first started only after an explicit /mcp restart.

The v0.9.10 product suggestions use these reviewed, pinned definitions. The Plugins view is the product/install surface; MCP, Skills, and sandbox adapters are transparent component kinds and their own tabs remain operational and diagnostic surfaces:

Plugin	Component	Pinned definition	Provenance and maturity	Installation boundary
Chrome DevTools	MCP server (stdio)	npx -y chrome-devtools-mcp@1.7.0 (npx.cmd on Windows)	Official ChromeDevTools project	npm may download the pinned package when the user restarts MCP.
Playwright	MCP server (stdio)	npx -y @playwright/mcp@0.0.79 --isolated (npx.cmd on Windows)	Official Microsoft project	--isolated starts a fresh browser profile; npm may download the pinned package only after an explicit restart.
Cua Computer Use	MCP server (stdio)	cua-driver mcp; Driver 0.20.0 reviewed for this release	Official Cua project; preview integration	The signed driver and OS permissions are separate, explicit installs. /mcp add recommended cua only writes config and never installs or grants either.
Browser Use	Skill plus separately installed Python runtime	Skill/runtime release 0.13.8	Official browser-use project	Optional companion: not an MCP server. Ghosty does not auto-run the upstream Skill installer or install its browser/runtime dependencies.
Anthropic Sandbox Runtime	Sandbox adapter companion	@anthropic-ai/sandbox-runtime@0.0.73	Official anthropic-experimental project; beta	Documentation-only adapter candidate in v0.9.10: not an MCP server and not an active Ghosty plugin adapter. It does not replace Ghosty's sandbox policy.

Container Use remains an additional experimental suggestion with an MCP server component (container-use stdio). The binary must be installed separately; /mcp add recommended container-use only writes config and Ghosty never downloads it.

This presentation follows the same useful boundary found in the local Grokbuild extensions view (one product plugin may expose MCP or Skill components while component tabs stay inspectable), the Kimi marketplace's explicit display name/tier/source fields, and the Codex marketplace's explicit source and install-policy fields. Ghosty keeps its stricter rule: provenance and foreign policy are display metadata only, never inherited trust or automatic installation. For full bundle and marketplace semantics, see Plugin bundles.

/mcp validate (alias /mcp doctor) reconnects for UI discovery only: it refreshes the manager snapshot you see in the pager, not the catalog the model gets.

/mcp reload (aliases /mcp reconnect, /mcp restart) is the hot-reload path. It re-reads the MCP config sources and reconnects through the engine-owned pool, so the rebuilt catalog is the exact one the next model turn uses — no TUI restart. Config edits made from the TUI are written immediately and the manager marks the snapshot reload-required until you run it; a failed reload leaves the previous live pool intact and says so.

Headless surfaces are the exception: the ConfigReload app-server request does not refresh MCP connections, so a headless runtime still needs a restart after MCP config changes.

Remote HTTP Auth

URL-based MCP servers can use static headers, env-derived headers, bearer-token env vars, or OAuth. Authorization precedence is conservative:

1. headers and env_headers are applied first.
2. bearer_token_env_var adds Authorization: Bearer <env value> when no Authorization header was already set.
3. Stored OAuth credentials are used only when no Authorization header exists.

For bearer-token auth, prefer env-backed config:

{
  "servers": {
    "remote": {
      "url": "https://example.com/mcp",
      "bearer_token_env_var": "EXAMPLE_MCP_TOKEN"
    }
  }
}

For generic remote MCP OAuth, add the URL server and run login:

ghosty mcp add remote --url "https://example.com/mcp"
ghosty mcp login remote

Ghosty discovers the server OAuth metadata, opens the authorization URL in your browser, listens on a local callback, exchanges the code, and stores the token response through the Ghosty secrets backend. Stored OAuth tokens are looked up by server name plus URL and refreshed when possible before requests. During login, the CLI prints the authorization URL and a waiting status while the local callback listener is active. If a URL-based server returns 401 or Unauthorized during connect/discovery, ghosty mcp connect <name> reports that OAuth authentication is required and points to ghosty mcp login <name>. Resource helper listings also surface an authentication_required entry for auth-shaped failures instead of silently looking empty.

Optional OAuth fields:

{
  "servers": {
    "remote": {
      "url": "https://example.com/mcp",
      "scopes": ["tools/read"],
      "oauth": {
        "client_id": "public-client-id"
      },
      "oauth_resource": "https://example.com"
    }
  }
}

User-level config can set callback behavior when the provider requires a fixed redirect:

mcp_oauth_callback_port = 1455
mcp_oauth_callback_url = "http://127.0.0.1:1455/callback"

These callback fields are ignored from project-scope config overlays.

Hugging Face MCP

Hugging Face provides a hosted MCP server for Hub resources, documentation, datasets, Spaces, and community tools. Ghosty does not call Hugging Face's Hub HTTP APIs from /hf; it only helps you inspect and set up the MCP config that the regular MCP manager will load.

The recommended setup path is Hugging Face's settings-generated configuration:

1. Visit https://huggingface.co/settings/mcp while signed in.
2. Choose the MCP client closest to your Ghosty config shape and copy the generated server snippet.
3. Paste the Hugging Face server entry into your resolved MCP config file.
4. Run /mcp reload to rebuild the live model-visible tool pool.

Ghosty reads both servers and mcpServers, so settings-generated snippets can be adapted without changing the rest of the MCP file. A placeholder-only shape looks like this:

{
  "servers": {
    "huggingface": {
      "url": "https://huggingface.co/mcp",
      "headers": {
        "Authorization": "Bearer ${HF_TOKEN}"
      }
    }
  }
}

The placeholder above is not a runnable secret. Use the settings-generated value in your private MCP config and never commit real Hugging Face tokens.

Interactive helpers:

/hf mcp status
/hf mcp setup
/hf concepts

/hf mcp status checks the configured MCP file for common Hugging Face server names or Hugging Face MCP URLs. /hf concepts explains the difference between the Hugging Face provider route, Hugging Face MCP, and explicit Hub workflows.

Official docs: https://huggingface.co/docs/hub/hf-mcp-server

Config File Location

Default path:

• ~/.ghosty/mcp.json (~/.deepseek/mcp.json is still read when the Ghosty file is absent)

Overrides:

• Config: mcp_config_path = "/path/to/mcp.json"
• Env: DEEPSEEK_MCP_CONFIG=/path/to/mcp.json

ghosty mcp init (and ghosty setup --mcp) writes to this resolved path.

The interactive /config editor also exposes mcp_config_path. Changing it in the TUI updates the path used by /mcp and marks the pool reload-required; /mcp reload then switches the live pool to the new config source.

After editing the MCP file or changing mcp_config_path, run /mcp reload. No TUI restart is needed.

Tool Naming

Discovered MCP tools are exposed to the model as:

• mcp_<server>_<tool>

Example: a server named git with a tool named status becomes mcp_git_status.

The command palette includes MCP entries grouped by server. It shows disabled and failed servers instead of hiding them, and uses the same runtime tool names shown to the model.

Resource and Prompt Helpers

The CLI also exposes helper tools when MCP is enabled:

• list_mcp_resources (optional server filter)
• list_mcp_resource_templates (optional server filter)
• mcp_read_resource / read_mcp_resource (aliases)
• mcp_get_prompt

Minimal Example

{
  "timeouts": {
    "connect_timeout": 10,
    "execute_timeout": 60,
    "read_timeout": 120
  },
  "servers": {
    "example": {
      "command": "node",
      "args": ["./path/to/your-mcp-server.js"],
      "env": {},
      "disabled": false
    }
  }
}

You can also use mcpServers instead of servers for compatibility with other clients.

Running Ghosty as an MCP Server

You can register your local Ghosty binary as an MCP server so other Ghosty sessions (or any MCP client) can call its tools.

Quick Setup

ghosty mcp add-self

This resolves the current binary path, generates a config entry that runs ghosty serve --mcp, and writes it to your MCP config file. The default server name is ghosty.

Options:

• --name <NAME> — custom server name (default: ghosty)
• --workspace <PATH> — workspace directory for the server

Manual Config

Equivalent manual entry in ~/.ghosty/mcp.json:

{
  "servers": {
    "ghosty": {
      "command": "/path/to/ghosty",
      "args": ["serve", "--mcp"],
      "env": {}
    }
  }
}

The consolidated ghosty runtime supports serve --mcp directly and also offers the equivalent ghosty mcp-server stdio entrypoint. Release installers expose the same runtime as ghosty-tui; mcp add-self automatically resolves the command that invoked it.

Prerequisites

• The binary referenced in command must exist and be executable.
• The MCP server runs as a child process via stdio — no network ports required.
• Each MCP client session spawns its own server process.

Tool Naming

Tools from an MCP server follow the standard naming convention:

• mcp_<server>_<tool>

For example, the shell tool from the default server (named ghosty) becomes mcp_ghosty_shell.

MCP Server vs HTTP/SSE API vs ACP

	ghosty serve --mcp	ghosty serve --http	ghosty serve --acp	ghosty serve --acp --acp-http
Protocol	MCP stdio	HTTP/SSE JSON-RPC	ACP stdio	ACP over WebSocket + Streamable HTTP
Use case	Tool server for MCP clients	Runtime API for apps	Editor agent for Zed/custom ACP clients	Remote or browser clients that cannot spawn a child process
Config	~/.ghosty/mcp.json entry	Direct URL connection	Editor agent_servers custom command	ws://host:port/acp
Auth	None (the client owns the process)	Runtime token	None (the client owns the process)	Runtime token and origin policy
Clients at once	One per spawn	Many	One	Many, each with its own sessions
Lifecycle	Spawned per client session	Long-running daemon	Spawned per editor agent session	Long-running daemon

Use mcp add-self when you want Ghosty tools available to other MCP clients. Use serve --http when building applications that consume the API directly. Use serve --acp when an editor wants to talk to Ghosty as an ACP agent, and add --acp-http when the client reaches Ghosty over the network instead of launching it. That transport exposes tool execution, so read the origin policy in docs/RUNTIME_API.md before binding it anywhere but loopback.

Verification

After adding, test the connection:

ghosty mcp validate
ghosty mcp tools ghosty

Server Fields

Per-server settings:

• command (string, required)
• args (array of strings, optional)
• env (object, optional)
• connect_timeout, execute_timeout, read_timeout (seconds, optional)
• disabled (bool, optional)
• enabled (bool, optional, default true)
• required (bool, optional): startup/connect validation fails if this server cannot initialize.
• enabled_tools (array, optional): allowlist of tool names for this server.
• disabled_tools (array, optional): denylist applied after enabled_tools.
• url (string, optional): Streamable HTTP endpoint for a remote MCP server.
• transport (string, optional): set to "sse" for legacy SSE endpoints.
• headers (object, optional): literal HTTP headers for URL-based servers.
• env_headers or env_http_headers (object, optional): header names mapped to environment variable names.
• bearer_token_env_var (string, optional): environment variable containing a bearer token.
• scopes (array, optional): default OAuth scopes for mcp login.
• oauth.client_id (string, optional): pre-registered OAuth client ID.
• oauth_resource (string, optional): resource parameter appended to the authorization URL.

Safety Notes

MCP tools flow through the same approval framework as built-in tools. Read-only MCP helpers (resource/prompt listing and reads) can run without prompts in Ask and Auto-Review when policy permits, while side-effectful MCP tools require approval. Full Access does not bypass hard policy holds.

You should still only configure MCP servers you trust, and treat MCP server configuration as equivalent to running code on your machine. Avoid committing literal Authorization headers. Prefer env_headers, bearer_token_env_var, or OAuth login so secrets stay outside the MCP file.

Troubleshooting

• Run ghosty doctor to confirm the MCP config path it resolved and whether it exists.
• In the TUI, run /mcp validate to refresh the visible server/tool snapshot.
• If tools are missing from the model's catalog after a config or credential change, run /mcp reload — /mcp validate only refreshes the UI snapshot.
• If the MCP config is missing, run ghosty mcp init --force to regenerate it.
• If tools don’t appear, verify the server command works from your shell and that the server supports MCP tools/list.