Federico Mariani created CAMEL-26111:
----------------------------------------
Summary: camel-mcp-server - support 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-mcp-server, camel-ai
Reporter: Federico Mariani
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)._
--
This message was sent by Atlassian Jira
(v10.3.26#10030026)
