docs: expand MCP binding configuration reference

src/reference/config/bindings/mcp/.partials/client.yaml

@@ -1,4 +1,6 @@
 mcp_client:
   type: mcp
   kind: client
+  options:
+    server: https://upstream.example.com/mcp
   exit: net_client

src/reference/config/bindings/mcp/.partials/options-authorization.md

@@ -0,0 +1,17 @@
+#### options.authorization
+
+> `object` as map of named `object` properties
+
+Authorization by a named guard.
+
+```yaml
+authorization:
+  my_jwt_guard:
+    credentials: scope
+```
+
+#### authorization.credentials
+
+> `string`
+
+Credentials used by the named guard to authorize the MCP session.

src/reference/config/bindings/mcp/.partials/options-client.md

@@ -0,0 +1,16 @@
+### options
+
+> `object`
+
+The `client` kind `mcp` specific options.
+
+```yaml
+options:
+  server: https://upstream.example.com/mcp
+```
+
+#### options.server\*
+
+> `string`
+
+URL of the upstream MCP server to forward requests to. Must match `^https?://`.

src/reference/config/bindings/mcp/.partials/options-proxy.md

@@ -0,0 +1,48 @@
+### options
+
+> `object`
+
+The `proxy` kind `mcp` specific options.
+
+```yaml
+options:
+  cache:
+    store: my_store
+    ttl: 5m
+```
+
+#### options.cache
+
+> `object`
+
+Cache configuration for upstream MCP responses, backed by a referenced store binding.
+
+#### cache.store\*
+
+> `string`
+
+Name of the store binding used to persist cached entries.
+
+#### cache.ttl
+
+> `string` | Default: `PT5M`
+
+Time-to-live before a cached entry is refreshed.
+
+#### cache.authorization
+
+> `object` as map of named `object` properties
+
+Authorization by a named guard used when refreshing cached entries.
+
+#### authorization.credentials
+
+> `string`
+
+Credentials used by the named guard when refreshing cached entries.
+
+#### options.tools
+
+> `enum` [ `avro`, `boolean`, `double`, `float`, `int32`, `int64`, `json`, `string` ], `object`
+
+Validation model applied to `tools/call` request arguments. Refer to the individual [model](../../../models/) docs for type specific implementation.

src/reference/config/bindings/mcp/.partials/options-server.md

@@ -0,0 +1,30 @@
+### options
+
+> `object`
+
+The `server` kind `mcp` specific options.
+
+```yaml
+options:
+  elicitation:
+    callback: auth/callback
+    timeout: 30s
+```
+
+#### options.elicitation
+
+> `object`
+
+Elicitation configuration for the OAuth authorization flow.
+
+#### elicitation.callback
+
+> `string` | Default: `auth/callback`
+
+Path on which the binding receives the authorization callback during elicitation.
+
+#### elicitation.timeout
+
+> `string` | Default: `PT0S`
+
+Maximum time to wait for the client to complete elicitation before the request fails.

src/reference/config/bindings/mcp/.partials/proxy.yaml

@@ -1,10 +1,18 @@
 mcp_proxy:
   type: mcp
   kind: proxy
+  options:
+    cache:
+      store: my_store
+      ttl: 5m
   routes:
     - exit: app1
       when:
         - toolkit: bluesky
+          capability:
+            - tools
+          tools:
+            - post_*
     - exit: app2
       when:
         - toolkit: quartz

src/reference/config/bindings/mcp/.partials/routes-proxy.md

@@ -0,0 +1,80 @@
+### routes
+
+> `array` of `object`
+
+Conditional `mcp` specific routes.
+
+#### routes[].when
+
+> `array` of `object`
+
+List of conditions (any match) to match this route.
+Read more: [When a route matches](/concepts/protocol/README.md#route-matches)
+
+#### when[].toolkit\*
+
+> `string`
+
+Toolkit name to match.
+
+#### when[].capability
+
+> `array` of `enum` [ `tools`, `prompts`, `resources` ]
+
+MCP capabilities to match.
+
+#### when[].tools
+
+> `array` of `string`
+
+Glob patterns of tool names to expose, where `*` matches any sequence of characters. Only tools whose name matches a pattern are routed. Valid when the `tools` capability is enabled. When omitted, all tools are admitted.
+
+#### when[].prompts
+
+> `array` of `string`
+
+Glob patterns of prompt names to expose, where `*` matches any sequence of characters. Only prompts whose name matches a pattern are routed. Valid when the `prompts` capability is enabled. When omitted, all prompts are admitted.
+
+#### when[].resources
+
+> `array` of `string`
+
+Glob patterns of resource URIs to expose, where `*` matches any sequence of characters. Only resources whose URI matches a pattern are routed. Valid when the `resources` capability is enabled. When omitted, all resources are admitted.
+
+#### routes[].with
+
+> `object`
+
+Route with override configuration.
+
+#### with.cache
+
+> `object`
+
+Cache override configuration for this route.
+
+#### cache.credentials
+
+> `string`
+
+Credentials used by the named guard when populating the cache for this route.
+
+#### routes[].exit
+
+> `string`
+
+Next binding when following this route.
+
+```yaml
+routes:
+  - exit: app1
+    when:
+      - toolkit: bluesky
+        capability:
+          - tools
+        tools:
+          - post_*
+  - exit: app2
+    when:
+      - toolkit: quartz
+```

src/reference/config/bindings/mcp/.partials/server.yaml

@@ -1,4 +1,10 @@
 mcp_server:
   type: mcp
   kind: server
+  options:
+    elicitation:
+      callback: auth/callback
+    authorization:
+      my_jwt_guard:
+        credentials: scope
   exit: mcp_client

src/reference/config/bindings/mcp/README.md

@@ -16,7 +16,7 @@ Defines a binding with [Model Context Protocol (MCP)](https://modelcontextprotoc
 
 > [Full config](./server.md)
 
-The `server` kind `mcp` binding accepts inbound MCP client connections and exposes locally defined prompts alongside any capabilities routed to upstream MCP servers.
+The `server` kind `mcp` binding accepts inbound MCP client connections, handling authorization and elicitation before forwarding to the exit binding.
 
 ```yaml {3}
 <!-- @include: ./.partials/server.yaml -->
@@ -26,7 +26,7 @@ The `server` kind `mcp` binding accepts inbound MCP client connections and expos
 
 > [Full config](./client.md)
 
-The `client` kind `mcp` binding forwards outbound MCP requests to an upstream MCP server.
+The `client` kind `mcp` binding forwards outbound MCP requests to the upstream MCP server configured by its `server` URL.
 
 ```yaml {3}
 <!-- @include: ./.partials/client.yaml -->
@@ -36,7 +36,7 @@ The `client` kind `mcp` binding forwards outbound MCP requests to an upstream MC
 
 > [Full config](./proxy.md)
 
-The `proxy` kind `mcp` binding routes inbound MCP requests to upstream MCP servers based on toolkit or capability conditions, optionally injecting headers.
+The `proxy` kind `mcp` binding routes inbound MCP requests to upstream MCP servers based on toolkit, capability, and per-route tool, prompt, and resource filters.
 
 ```yaml {3}
 <!-- @include: ./.partials/proxy.yaml -->

src/reference/config/bindings/mcp/client.md

@@ -12,7 +12,7 @@ The mcp client binding forwards outbound MCP requests to an upstream MCP server.
 
 ## Configuration (\* required)
 
-<!-- @include: ./.partials/options.md -->
-<!-- @include: ./.partials/routes.md -->
+<!-- @include: ./.partials/options-client.md -->
+<!-- @include: ./.partials/options-authorization.md -->
 <!-- @include: ../.partials/exit.md -->
 <!-- @include: ../.partials/telemetry.md -->

src/reference/config/bindings/mcp/proxy.md

@@ -4,15 +4,15 @@ shortTitle: proxy
 
 # mcp proxy
 
-The mcp proxy binding routes inbound MCP requests to upstream MCP servers based on toolkit or capability conditions, optionally injecting headers.
+The mcp proxy binding routes inbound MCP requests to upstream MCP servers based on toolkit, capability, and per-route tool, prompt, and resource filters.
 
 ```yaml {3}
 <!-- @include: ./.partials/proxy.yaml -->
 ```
 
 ## Configuration (\* required)
 
-<!-- @include: ./.partials/options.md -->
-<!-- @include: ./.partials/routes.md -->
+<!-- @include: ./.partials/options-proxy.md -->
+<!-- @include: ./.partials/routes-proxy.md -->
 <!-- @include: ../.partials/exit.md -->
 <!-- @include: ../.partials/telemetry.md -->

src/reference/config/bindings/mcp/server.md

@@ -4,15 +4,15 @@ shortTitle: server
 
 # mcp server
 
-The mcp server binding accepts inbound MCP client connections and exposes locally defined prompts alongside any capabilities routed to upstream MCP servers.
+The mcp server binding accepts inbound MCP client connections, handling authorization and elicitation before forwarding to the exit binding.
 
 ```yaml {3}
 <!-- @include: ./.partials/server.yaml -->
 ```
 
 ## Configuration (\* required)
 
-<!-- @include: ./.partials/options.md -->
-<!-- @include: ./.partials/routes.md -->
+<!-- @include: ./.partials/options-server.md -->
+<!-- @include: ./.partials/options-authorization.md -->
 <!-- @include: ../.partials/exit.md -->
 <!-- @include: ../.partials/telemetry.md -->