diff --git a/src/reference/config/bindings/mcp/.partials/client.yaml b/src/reference/config/bindings/mcp/.partials/client.yaml index 8420b9c6..cd4da955 100644 --- a/src/reference/config/bindings/mcp/.partials/client.yaml +++ b/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 diff --git a/src/reference/config/bindings/mcp/.partials/options-authorization.md b/src/reference/config/bindings/mcp/.partials/options-authorization.md new file mode 100644 index 00000000..ca75e531 --- /dev/null +++ b/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. diff --git a/src/reference/config/bindings/mcp/.partials/options-client.md b/src/reference/config/bindings/mcp/.partials/options-client.md new file mode 100644 index 00000000..01df3758 --- /dev/null +++ b/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?://`. diff --git a/src/reference/config/bindings/mcp/.partials/options-proxy.md b/src/reference/config/bindings/mcp/.partials/options-proxy.md new file mode 100644 index 00000000..1f9ed273 --- /dev/null +++ b/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. diff --git a/src/reference/config/bindings/mcp/.partials/options-server.md b/src/reference/config/bindings/mcp/.partials/options-server.md new file mode 100644 index 00000000..e1f0fc76 --- /dev/null +++ b/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. diff --git a/src/reference/config/bindings/mcp/.partials/options.md b/src/reference/config/bindings/mcp/.partials/options.md deleted file mode 100644 index 99485656..00000000 --- a/src/reference/config/bindings/mcp/.partials/options.md +++ /dev/null @@ -1,30 +0,0 @@ -### options - -> `object` - -The `mcp` specific options. - -```yaml -options: - prompts: - - name: my_prompt - description: A helpful prompt. -``` - -#### options.prompts - -> `array` of `object` - -List of locally defined MCP prompts served by this binding. - -#### prompts[].name\* - -> `string` - -Prompt name. - -#### prompts[].description - -> `string` - -Prompt description. diff --git a/src/reference/config/bindings/mcp/.partials/proxy.yaml b/src/reference/config/bindings/mcp/.partials/proxy.yaml index e663eb64..699e2cbc 100644 --- a/src/reference/config/bindings/mcp/.partials/proxy.yaml +++ b/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 diff --git a/src/reference/config/bindings/mcp/.partials/routes-proxy.md b/src/reference/config/bindings/mcp/.partials/routes-proxy.md new file mode 100644 index 00000000..ad543d43 --- /dev/null +++ b/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 +``` diff --git a/src/reference/config/bindings/mcp/.partials/routes.md b/src/reference/config/bindings/mcp/.partials/routes.md deleted file mode 100644 index d00dac6f..00000000 --- a/src/reference/config/bindings/mcp/.partials/routes.md +++ /dev/null @@ -1,52 +0,0 @@ -### 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. - -#### routes[].with - -> `object` - -Route with override configuration. - -#### with.headers - -> `object` as map of named `string` properties - -HTTP headers to add or override when forwarding requests. - -#### routes[].exit - -> `string` - -Next binding when following this route. - -```yaml -routes: - - exit: app1 - when: - - toolkit: bluesky - - exit: app2 - when: - - toolkit: quartz -``` diff --git a/src/reference/config/bindings/mcp/.partials/server.yaml b/src/reference/config/bindings/mcp/.partials/server.yaml index b9f329ee..2b8b4bd1 100644 --- a/src/reference/config/bindings/mcp/.partials/server.yaml +++ b/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 diff --git a/src/reference/config/bindings/mcp/README.md b/src/reference/config/bindings/mcp/README.md index b2e37f40..9ff0ec67 100644 --- a/src/reference/config/bindings/mcp/README.md +++ b/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} @@ -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} @@ -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} diff --git a/src/reference/config/bindings/mcp/client.md b/src/reference/config/bindings/mcp/client.md index 792545f5..4e2000fe 100644 --- a/src/reference/config/bindings/mcp/client.md +++ b/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) - - + + diff --git a/src/reference/config/bindings/mcp/proxy.md b/src/reference/config/bindings/mcp/proxy.md index 62312aea..459c43db 100644 --- a/src/reference/config/bindings/mcp/proxy.md +++ b/src/reference/config/bindings/mcp/proxy.md @@ -4,7 +4,7 @@ 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} @@ -12,7 +12,7 @@ The mcp proxy binding routes inbound MCP requests to upstream MCP servers based ## Configuration (\* required) - - + + diff --git a/src/reference/config/bindings/mcp/server.md b/src/reference/config/bindings/mcp/server.md index 96035158..934f6e60 100644 --- a/src/reference/config/bindings/mcp/server.md +++ b/src/reference/config/bindings/mcp/server.md @@ -4,7 +4,7 @@ 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} @@ -12,7 +12,7 @@ The mcp server binding accepts inbound MCP client connections and exposes locall ## Configuration (\* required) - - + +