Menu
简体中文
On this page

MCP Guide

Docs home · Configuration · Privacy · Troubleshooting · 简体中文

Sigil connects local stdio and user-root Streamable HTTP MCP servers. Start with one server, keep approval at ask, run /doctor, and inspect what it can read, change, or transmit.

Minimal Config

CLI Setup

After completing Quick Setup, manage the selected user config without editing TOML by hand:

sigil mcp add filesystem -- node /absolute/path/to/server.js
sigil mcp add my-search --url https://mcp.example.com/mcp
sigil mcp list
sigil mcp get my-search
sigil mcp remove filesystem

Use --inherit-env NAME for each environment variable a stdio server needs, or --bearer-token-env-var NAME for a remote static bearer token. New entries use approval_default = "ask", do not allow secrets, start eagerly, and remain optional unless --required is set. list intentionally omits commands, arguments, and credential sources. get shows the selected command or safe remote destination plus credential source names, but redacts command arguments and credential values. Both read commands support --json. Pass the global --config PATH before mcp to edit an explicit config. CLI and TUI saves share one exclusive config lease and same-directory atomic replacement; a concurrent writer fails closed instead of silently losing either update.

TOML Setup

[[mcp_servers]]
name = "filesystem"
transport = "stdio"
command = "node"
args = ["/absolute/path/to/server.js"]
startup = "eager"
required = true

[mcp_servers.trust]
trust_class = "self_hosted"
approval_default = "ask"
egress_logging = true
allow_secrets = false
pin_version = false

Use an absolute command when possible. Exposed tool names look like mcp__filesystem__read_file; conflicts receive a stable suffix.

Streamable HTTP

Remote MCP is allowed only in the user-root config. Prefer HTTPS; plain HTTP is accepted only without environment-backed headers, bearer credentials, or OAuth, and should be limited to a trusted local setup.

[[mcp_servers]]
name = "my-search"
transport = "streamable_http"
url = "https://mcp.example.com/mcp"
startup = "lazy"
env_http_headers = { "X-API-Key" = "MY_SEARCH_API_KEY" }
client_capabilities = ["roots", "elicitation"]

[mcp_servers.trust]
trust_class = "third_party"
approval_default = "ask"
allow_secrets = false

Use bearer_token_env_var for a static bearer token. Sigil checks every destination, does not follow redirects automatically, bounds response size, and shows safe origin and credential-source names without displaying values.

OAuth Authentication

Use OAuth instead of a static Authorization or bearer credential:

[mcp_servers.oauth]
# client_id = "sigil-public-client" # optional when dynamic registration is supported
scopes = ["mcp:tools"]

OAuth requires HTTPS and an explicit sign in action. Eager or headless startup reports authentication required without opening a browser. In /config, select the server and open Authentication. From the modal you can sign in, open or copy the authorization URL, paste a complete callback URL when the browser callback cannot return automatically, refresh, revoke remotely, or explicitly clear only the local credential. The automatic callback listens only on the IPv4 loopback interface at a random port. Callback text stays transient. Tokens are stored in the native system credential store, not TOML; there is no plaintext fallback.

OAuth can contact separate HTTPS authorization endpoints, all subject to the configured Network controls. Redirects and automatic retries are disabled. A 401 marks authentication stale but does not replay the request.

sigil mcp get NAME and offline /doctor report whether OAuth is configured, but do not open the credential store or probe the server. /config owns the live credential state (authentication required, ready, stale, or failed) after activation.

Remote sign-out tries revocation and never deletes the local credential implicitly. If revocation fails, the modal reports an error and keeps the credential. You may then retry or choose clear local only; that explicit action makes no remote-revocation claim. After a successful revocation—or when the server advertises no revocation endpoint—the modal enters remote handled, local retained and still lets you clear or keep the local credential.

Process Environment And Credentials

Local stdio servers start with a small runtime environment, not Sigil's full parent environment. Grant only required variable names from the user-root config:

inherit_env = ["MY_MCP_API_KEY"]

Every listed variable must exist when the server starts. Provider keys, cloud credentials, proxy settings, and other sensitive variables are not inherited automatically. inherit_env controls process startup; allow_secrets separately controls recognized secret-like data in later MCP calls.

Startup And Refresh

The TUI reports deferred, authentication required, activating, ready, stale, or failed. Use /config → MCP → activate to start or refresh a server after fixing it. OAuth servers open Authentication instead of pretending that an unauthenticated zero-tool connection is ready.

Compatibility And Limits

Stdio servers must use newline-delimited JSON for MCP 2025-06-18; Content-Length framing is not supported. Startup and calls have finite timeouts. Oversized, invalid, or timed-out input closes that connection and is reported as a failure. Tool, resource, and prompt results are redacted and shortened before model use.

Trust And Identity

trust_class records whether a server is official, self-hosted, or third-party. approval_default controls its normal prompt behavior. Keep allow_secrets = false unless a trusted server genuinely needs sensitive data.

pin_version = true can bind the expected command and reported server identity. A stale or missing pin prevents startup. Pinning helps detect unexpected changes but is not protection against another same-user process that can replace an executable during launch.

Roots, Resources, Prompts, And Input

Sigil exposes only the active workspace through roots/list. Resources and prompts are listed or read only through explicit MCP tools; they are not injected automatically. Elicitation forms appear in the TUI with the server, requested fields, and defaults. Headless use reports unsupported when interactive input is required. Progress updates refresh the live panel without flooding the transcript.

Troubleshooting

See Troubleshooting for the symptom path and Configuration Reference for fields.

Next: Use the MCP troubleshooting path.