MCP servers

The Model Context Protocol over stdio or streamable HTTP. Their tools join yours, permission-gated.

Config

Declared in the mcp map of lugent.json or the global config. The type is inferred from command or url.

{
  "mcp": {
    "local-one":  { "command": ["npx", "-y", "some-mcp@latest"] },
    "remote-one": { "url": "https://host/mcp",
                    "headers": { "X-Tenant": "{env:TENANT}" } }
  }
}

Transports

local: Spawns a child process and speaks newline-delimited JSON-RPC over stdio.
remote: Streamable HTTP: one POST per message, Mcp-Session-Id, SSE responses. http is an alias.

At startup every enabled server connects in parallel and its tools are bridged as <server>_<tool>. A server that fails is reported and never stops lugent.

Signing in

A remote server that refuses the configured headers answers 401. lugent reports it as auth_required instead of failing, because the fix is interactive. Choose authenticate in /mcp and lugent:

discovers the protected-resource and authorization-server metadata (RFC 9728 and 8414), https only
registers itself as a public client, once per server (RFC 7591)
starts a loopback listener on 127.0.0.1:48762/oauth/callback with PKCE S256, and opens your browser
waits up to five minutes, always sending resource so the token is bound to that endpoint
stores the tokens in ~/.local/share/lugent/mcp-oauth.json, mode 0600

Access tokens refresh 60 seconds before expiry, and once more, forcibly, on a mid-session 401. A rejected refresh drops the tokens back to auth_required.

Status and actions

connected: With a tool count. Remote servers can log out or be disabled, local ones disabled.
connecting: A handshake is still in flight.
failed: With the error. Reconnect or disable.
auth_required: Needs a sign-in. Authenticate or disable.
disabled: Out of the session. Enable reconnects.

Enabling and disabling is session-scoped: lugent never rewrites lugent.json, because a turn must not silently edit a file that can hold secrets.

Trust note: a project lugent.json can declare local servers, whose command is spawned at startup with no prompt. That is the same trust channel as a project AGENTS.md, so read a repo's mcp block before running lugent in it.