# panto-mcp An extension for connecting panto to Model Context Protocol (MCP) servers. It supports supervised local stdio servers and remote Streamable HTTP servers, with deferred tool discovery/calls, resource reads, prompts, and a `std.lua` namespace. It adds no Lua dependencies; local server programs must be installed separately. ## Install Install the rock through panto: ```sh panto extensions install rock:panto-mcp ``` Alternatively add it to panto's `config.toml`: ```toml [extensions] rocks = ["panto-mcp"] ``` Configure servers in `config.toml`: ```toml [mcp] startup_timeout_ms = 30000 call_timeout_ms = 300000 idle_timeout_ms = 60000 [mcp.servers.files] command = "npx" args = ["-y", "@modelcontextprotocol/server-filesystem", "${project_root}"] # cwd = "." # env = { "TOKEN" = "${env:FILES_TOKEN}" } # enabled = true # expose = "search" # enabled_tools = [] # disabled_tools = ["delete_*"] [mcp.servers.remote] url = "https://example.com/mcp" # auth = "mcp.remote" # named panto auth session # headers = { "X-Tenant" = "acme" } # ${env:VAR} is expanded # expose = "search" # oauth = { scopes = ["read"] } ``` Global timeout fields are positive integer milliseconds: `startup_timeout_ms` (connect and discovery), `call_timeout_ms` (request), and `idle_timeout_ms` (maximum silent interval for HTTP streams). Each server accepts exactly one of `url` (HTTP(S)) or `command` (stdio), plus `args` (string array), `env` (string-to-string table), `cwd` (string), `enabled` (boolean), `expose` (`"search"` default or `"eager"`), `headers` (string-to-string table), `auth` (named auth session), and `enabled_tools` / `disabled_tools` (glob arrays, filtered in that order). HTTP servers may also set `oauth` with `scopes` (array of strings), `client_id`, `issuer`, and `client_secret`; a client ID requires its exact `issuer`, and a secret requires a client ID. An issuer without a client ID pins public DCR discovery too (the matching advertised issuer is selected). `${env:NAME}` expands from the process environment and `${project_root}` from panto's project root in supported string values. Invalid server entries are skipped with warnings. ## Use The session header lists enabled MCP servers by their configured names, even before they connect. Use `/mcp` to check connection status. Search-mode servers provide `mcp.search`, `mcp.call`, and (when resources are available) `mcp.read_resource`. Set `expose = "eager"` to expose individual `mcp..` tools. Server prompts are commands of the form `/mcp::`; `/mcp` shows status and `/mcp refresh [server]` refreshes metadata. The `std.lua` code-mode API is documented at `require("panto_mcp.docs").discovery` (and related docs fields). For automatic HTTP OAuth, omit `auth` and run `/mcp-login `; open the URL shown, or paste the full callback URL using `/mcp-login ` in a headless session. A configured `auth` uses the named panto auth session instead of automatic OAuth. Public DCR registrations are reused across logins and all failures, including network/refresh errors: a transient error never creates a new client. If the client was deleted or is otherwise stale, explicitly run `/mcp-login --reregister` to discard that registration and definition, rediscover, and register once. It is only for automatic public DCR clients; confidential DCR is refused. Normal login rediscovers only for a missing or failed definition. A changed discovered issuer discards the old registration. Configured client secrets stay out of extension state and catalog caches. Registrations are issuer-wide in panto state; `--reregister` intentionally replaces that shared registration. Automatic session names use a 128-bit SHA-256 prefix of resource, issuer and client ID (within 128 bytes); a name change logs out the old session. Consent login with a usable token keeps working tools usable, even if consent is abandoned. Legacy notification streams retry with exponential backoff up to 60 seconds; a 401 stops retries and shows a `/mcp` warning. Simple eager tool names stay readable; sanitized/truncated or encoded-looking names get stable suffixes. **Core API requirement:** remote HTTP, eager tool registration, prompt commands, and OAuth require a panto build with post-activation register/unregister, `http_request` methods and streaming, and `panto.ext.auth`. On older panto builds stdio plus search mode works; unsupported capabilities degrade with a clear error. ## Limits Catalogs are cached locally and refreshed on connection; search does not start servers. There is no resource subscription, elicitation, task support, legacy HTTP+SSE transport, or persistent server process across panto sessions. Local stdio server executables are not bundled.