summaryrefslogtreecommitdiff
path: root/README.md
blob: 6419a31a6741530d50bc812240137cf63efa0830 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
# 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.<server>.<tool>` tools. Server prompts are commands of the form
`/mcp:<server>:<prompt>`; `/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 <server>`; open the
URL shown, or paste the full callback URL using `/mcp-login <server>
<callback-url>` 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 <server> --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.