[
https://issues.apache.org/jira/browse/CAMEL-26111?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Federico Mariani updated CAMEL-26111:
-------------------------------------
Description:
h2. Design investigation only - real-world requirement required before
implementation
This issue records a design investigation, not an approved implementation plan.
Do not begin implementation until there is a concrete, real-world requirement:
an actual use case or deployment, identified target MCP clients and catalog
scale, and evidence that existing client-side tool discovery or simpler catalog
filtering does not adequately solve the problem.
First document that requirement and evaluate the alternatives, interoperability
and measurable benefit. It is valid for the investigation to conclude that no
server-side feature is needed. The search_tools/call_tool design below is only
a candidate for evaluation; neither its implementation nor its naming is
decided. Any implementation scope and acceptance criteria below are conditional
on establishing the requirement and agreeing the design. This follow-up does
not add implementation requirements to PR #28354.
_Clarification added by Codex on behalf of @Croway._
h2. Context
CAMEL-24767 and PR https://github.com/apache/camel/pull/28354 introduce a
shared tool-search index and deferred visibility for ai-tool routes consumed by
Camel's langchain4j-agent, spring-ai-chat and openai producers. A route can be
marked searchable=true so a Camel AI producer loads its definition only after
discovery.
The MCP server does not consume this visibility flag. McpServerBridge publishes
every tag-selected AiToolSpec through engine.toolAdded(createTool(spec)), so
external MCP clients still receive all exposed route tools. Server-side
discovery would allow external agents to discover and invoke a large searchable
route catalog through Camel's MCP server.
This issue concerns camel-mcp-server exposing application ai-tool routes. It is
distinct from the tool profiles for the Camel CLI development server in
CAMEL-25537.
h2. Candidate behavior to evaluate if a requirement is established
# Introduce an explicit, opt-in server discovery mode; preserve today's
full-catalog behavior by default. Option and synthetic tool names are
illustrative.
# In discovery mode, when at least one eligible route has searchable=true,
expose a search_tools(query, limit) capability. Keep eligible searchable=false
route tools directly exposed.
# Reuse the shared framework-neutral index/ranking from CAMEL-24767. Search the
server-selected catalog only, respecting tag selection, configuration
restrictions and applicable access controls.
# Return bounded matches with tool name, description, complete input schema,
output schema and annotations where available. Explain the available capability
categories in server instructions or the discovery tool description.
# Provide a reliable invocation path for discovered routes on external clients.
Returning names or schema text alone does not register callable functions with
a host. A stable call_tool(name, arguments) dispatcher alongside search_tools
is one candidate design; the final design must establish how discovery leads to
execution.
# Dispatch through existing route-tool execution and authorization logic,
preserving input validation, trusted caller identity, invocation identifiers,
and error handling. Discovery is a visibility policy, not execution
authorization.
# Reflect route registration, changes, stop/suspend, removal and restart in
search and invocation. Cache embeddings/index data with invalidation; bound any
retained state.
h2. Protocol and interoperability constraints
The MCP 2026-07-28 Tools specification says tools/list must not vary per
connection or as a side effect of other requests on the connection. Do not
assume that searching may reveal extra tools in a session-specific tools/list
response. A stable meta-tool surface is one possible solution; assess supported
protocol versions and engines explicitly.
Specification:
https://modelcontextprotocol.io/specification/2026-07-28/server/tools
Clients that already defer MCP tools may gain less from server-side search and
could incur an additional discovery step. Preserve an opt-out/full-catalog mode
and evaluate the tradeoff rather than assuming universal token savings.
h2. Conditional acceptance criteria for a future implementation
* End-to-end coverage: discover a searchable route, obtain its complete schema,
invoke it, and receive the original route result through an external MCP client.
* Always-visible tools remain available; disabled mode preserves existing
behavior; empty and no-match searches are explicit and bounded.
* Tag/configuration/access restrictions are preserved, and calls retain normal
authorization and argument validation. Search must not make an unavailable
route executable.
* Lifecycle changes invalidate stale catalog entries; concurrent clients do not
share mutable discovery state unexpectedly.
* Verify supported HTTP/stdio engines and representative external clients,
including clients that cache tool lists and clients with native tool search.
Document the compatibility matrix and invocation contract.
* Measure initial schema/token footprint, retrieval quality, latency and
repeated-search cost on a realistic catalog.
* Document server configuration and the distinction between producer-side
search in CAMEL-24767 and server-side discovery here.
h2. References
* CAMEL-24767 and https://github.com/apache/camel/pull/28354
* design/aiTool.adoc for the shared tool abstraction and existing execution
ownership
* PayPal SCOUT (search and execution meta-tools):
https://arxiv.org/abs/2608.23992
_AI-generated issue by Codex on behalf of @Croway (authenticated Jira operator:
fmariani)._
was:
h2. Context
CAMEL-24767 and PR https://github.com/apache/camel/pull/28354 introduce a
shared tool-search index and deferred visibility for ai-tool routes consumed by
Camel's langchain4j-agent, spring-ai-chat and openai producers. A route can be
marked searchable=true so a Camel AI producer loads its definition only after
discovery.
The MCP server does not consume this visibility flag. McpServerBridge publishes
every tag-selected AiToolSpec through engine.toolAdded(createTool(spec)), so
external MCP clients still receive all exposed route tools. Server-side
discovery would allow external agents to discover and invoke a large searchable
route catalog through Camel's MCP server.
This issue concerns camel-mcp-server exposing application ai-tool routes. It is
distinct from the tool profiles for the Camel CLI development server in
CAMEL-25537.
h2. Proposed behavior
# Introduce an explicit, opt-in server discovery mode; preserve today's
full-catalog behavior by default. Option and synthetic tool names are
illustrative.
# In discovery mode, when at least one eligible route has searchable=true,
expose a search_tools(query, limit) capability. Keep eligible searchable=false
route tools directly exposed.
# Reuse the shared framework-neutral index/ranking from CAMEL-24767. Search the
server-selected catalog only, respecting tag selection, configuration
restrictions and applicable access controls.
# Return bounded matches with tool name, description, complete input schema,
output schema and annotations where available. Explain the available capability
categories in server instructions or the discovery tool description.
# Provide a reliable invocation path for discovered routes on external clients.
Returning names or schema text alone does not register callable functions with
a host. A stable call_tool(name, arguments) dispatcher alongside search_tools
is one candidate design; the final design must establish how discovery leads to
execution.
# Dispatch through existing route-tool execution and authorization logic,
preserving input validation, trusted caller identity, invocation identifiers,
and error handling. Discovery is a visibility policy, not execution
authorization.
# Reflect route registration, changes, stop/suspend, removal and restart in
search and invocation. Cache embeddings/index data with invalidation; bound any
retained state.
h2. Protocol and interoperability constraints
The MCP 2026-07-28 Tools specification says tools/list must not vary per
connection or as a side effect of other requests on the connection. Do not
assume that searching may reveal extra tools in a session-specific tools/list
response. A stable meta-tool surface is one possible solution; assess supported
protocol versions and engines explicitly.
Specification:
https://modelcontextprotocol.io/specification/2026-07-28/server/tools
Clients that already defer MCP tools may gain less from server-side search and
could incur an additional discovery step. Preserve an opt-out/full-catalog mode
and evaluate the tradeoff rather than assuming universal token savings.
h2. Acceptance criteria
* End-to-end coverage: discover a searchable route, obtain its complete schema,
invoke it, and receive the original route result through an external MCP client.
* Always-visible tools remain available; disabled mode preserves existing
behavior; empty and no-match searches are explicit and bounded.
* Tag/configuration/access restrictions are preserved, and calls retain normal
authorization and argument validation. Search must not make an unavailable
route executable.
* Lifecycle changes invalidate stale catalog entries; concurrent clients do not
share mutable discovery state unexpectedly.
* Verify supported HTTP/stdio engines and representative external clients,
including clients that cache tool lists and clients with native tool search.
Document the compatibility matrix and invocation contract.
* Measure initial schema/token footprint, retrieval quality, latency and
repeated-search cost on a realistic catalog.
* Document server configuration and the distinction between producer-side
search in CAMEL-24767 and server-side discovery here.
h2. References
* CAMEL-24767 and https://github.com/apache/camel/pull/28354
* design/aiTool.adoc for the shared tool abstraction and existing execution
ownership
* PayPal SCOUT (search and execution meta-tools):
https://arxiv.org/abs/2608.23992
_AI-generated issue by Codex on behalf of @Croway (authenticated Jira operator:
fmariani)._
Summary: camel-mcp-server - investigate progressive discovery and
invocation of searchable ai-tool routes (was: camel-mcp-server - support
progressive discovery and invocation of searchable ai-tool routes)
> camel-mcp-server - investigate progressive discovery and invocation of
> searchable ai-tool routes
> ------------------------------------------------------------------------------------------------
>
> Key: CAMEL-26111
> URL: https://issues.apache.org/jira/browse/CAMEL-26111
> Project: Camel
> Issue Type: Improvement
> Components: camel-ai, camel-mcp-server
> Reporter: Federico Mariani
> Priority: Major
>
> h2. Design investigation only - real-world requirement required before
> implementation
> This issue records a design investigation, not an approved implementation
> plan. Do not begin implementation until there is a concrete, real-world
> requirement: an actual use case or deployment, identified target MCP clients
> and catalog scale, and evidence that existing client-side tool discovery or
> simpler catalog filtering does not adequately solve the problem.
> First document that requirement and evaluate the alternatives,
> interoperability and measurable benefit. It is valid for the investigation to
> conclude that no server-side feature is needed. The search_tools/call_tool
> design below is only a candidate for evaluation; neither its implementation
> nor its naming is decided. Any implementation scope and acceptance criteria
> below are conditional on establishing the requirement and agreeing the
> design. This follow-up does not add implementation requirements to PR #28354.
> _Clarification added by Codex on behalf of @Croway._
> h2. Context
> CAMEL-24767 and PR https://github.com/apache/camel/pull/28354 introduce a
> shared tool-search index and deferred visibility for ai-tool routes consumed
> by Camel's langchain4j-agent, spring-ai-chat and openai producers. A route
> can be marked searchable=true so a Camel AI producer loads its definition
> only after discovery.
> The MCP server does not consume this visibility flag. McpServerBridge
> publishes every tag-selected AiToolSpec through
> engine.toolAdded(createTool(spec)), so external MCP clients still receive all
> exposed route tools. Server-side discovery would allow external agents to
> discover and invoke a large searchable route catalog through Camel's MCP
> server.
> This issue concerns camel-mcp-server exposing application ai-tool routes. It
> is distinct from the tool profiles for the Camel CLI development server in
> CAMEL-25537.
> h2. Candidate behavior to evaluate if a requirement is established
> # Introduce an explicit, opt-in server discovery mode; preserve today's
> full-catalog behavior by default. Option and synthetic tool names are
> illustrative.
> # In discovery mode, when at least one eligible route has searchable=true,
> expose a search_tools(query, limit) capability. Keep eligible
> searchable=false route tools directly exposed.
> # Reuse the shared framework-neutral index/ranking from CAMEL-24767. Search
> the server-selected catalog only, respecting tag selection, configuration
> restrictions and applicable access controls.
> # Return bounded matches with tool name, description, complete input schema,
> output schema and annotations where available. Explain the available
> capability categories in server instructions or the discovery tool
> description.
> # Provide a reliable invocation path for discovered routes on external
> clients. Returning names or schema text alone does not register callable
> functions with a host. A stable call_tool(name, arguments) dispatcher
> alongside search_tools is one candidate design; the final design must
> establish how discovery leads to execution.
> # Dispatch through existing route-tool execution and authorization logic,
> preserving input validation, trusted caller identity, invocation identifiers,
> and error handling. Discovery is a visibility policy, not execution
> authorization.
> # Reflect route registration, changes, stop/suspend, removal and restart in
> search and invocation. Cache embeddings/index data with invalidation; bound
> any retained state.
> h2. Protocol and interoperability constraints
> The MCP 2026-07-28 Tools specification says tools/list must not vary per
> connection or as a side effect of other requests on the connection. Do not
> assume that searching may reveal extra tools in a session-specific tools/list
> response. A stable meta-tool surface is one possible solution; assess
> supported protocol versions and engines explicitly.
> Specification:
> https://modelcontextprotocol.io/specification/2026-07-28/server/tools
> Clients that already defer MCP tools may gain less from server-side search
> and could incur an additional discovery step. Preserve an
> opt-out/full-catalog mode and evaluate the tradeoff rather than assuming
> universal token savings.
> h2. Conditional acceptance criteria for a future implementation
> * End-to-end coverage: discover a searchable route, obtain its complete
> schema, invoke it, and receive the original route result through an external
> MCP client.
> * Always-visible tools remain available; disabled mode preserves existing
> behavior; empty and no-match searches are explicit and bounded.
> * Tag/configuration/access restrictions are preserved, and calls retain
> normal authorization and argument validation. Search must not make an
> unavailable route executable.
> * Lifecycle changes invalidate stale catalog entries; concurrent clients do
> not share mutable discovery state unexpectedly.
> * Verify supported HTTP/stdio engines and representative external clients,
> including clients that cache tool lists and clients with native tool search.
> Document the compatibility matrix and invocation contract.
> * Measure initial schema/token footprint, retrieval quality, latency and
> repeated-search cost on a realistic catalog.
> * Document server configuration and the distinction between producer-side
> search in CAMEL-24767 and server-side discovery here.
> h2. References
> * CAMEL-24767 and https://github.com/apache/camel/pull/28354
> * design/aiTool.adoc for the shared tool abstraction and existing execution
> ownership
> * PayPal SCOUT (search and execution meta-tools):
> https://arxiv.org/abs/2608.23992
> _AI-generated issue by Codex on behalf of @Croway (authenticated Jira
> operator: fmariani)._
--
This message was sent by Atlassian Jira
(v10.3.26#10030026)
