Skip to content

CAMEL-24331: camel-mcp-server-starter - Spring AI engine for the MCP server bridge #1871

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Croway merged 4 commits into from
Aug 5, 2026
Merged

CAMEL-24331: camel-mcp-server-starter - Spring AI engine for the MCP server bridge #1871

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
a69ff5f
CAMEL-24331: camel-mcp-server-starter - Spring AI engine for the MCP …
Croway Aug 3, 2026
edfd86d
CAMEL-24331: camel-mcp-server-starter - richer usage docs and @McpToo…
Croway Aug 3, 2026
2f2066d
CAMEL-24331: camel-mcp-server-starter - document serving over stdio
Croway Aug 4, 2026
653ec31
CAMEL-24331: camel-mcp-server-starter - add a stdio transport test
Croway Aug 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
92 changes: 92 additions & 0 deletions components-starter/camel-mcp-server-starter/pom.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,92 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--

Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

-->
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>org.apache.camel.springboot</groupId>
<artifactId>components-starter</artifactId>
<version>4.22.0-SNAPSHOT</version>
</parent>
<artifactId>camel-mcp-server-starter</artifactId>
<packaging>jar</packaging>
<name>Camel SB Starters :: MCP Server</name>
<description>Spring Boot Starter to expose ai-tool routes as MCP tools through the Spring AI MCP server</description>
<properties>
<!-- the Spring AI MCP server support requires Spring AI 2.x (Spring Boot 4.1 baseline);
it pins the same MCP Java SDK version (2.0.0) that Apache Camel manages -->
<spring-ai-mcp-version>2.0.0</spring-ai-mcp-version>
</properties>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter</artifactId>
<version>${spring-boot-version}</version>
</dependency>
<!-- the runtime-agnostic MCP bridge and engine SPI; the serving engine is provided
by Spring AI below (NOT the camel-mcp-server Vert.x engine) -->
<dependency>
<groupId>org.apache.camel</groupId>
<artifactId>camel-mcp-server-api</artifactId>
<version>${camel-version}</version>
</dependency>
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-mcp-server-webmvc</artifactId>
<version>${spring-ai-mcp-version}</version>
</dependency>
<!-- test dependencies -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
<version>${spring-boot-version}</version>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.apache.camel</groupId>
<artifactId>camel-ai-tool</artifactId>
<version>${camel-version}</version>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.awaitility</groupId>
<artifactId>awaitility</artifactId>
<scope>test</scope>
</dependency>
<!--START OF GENERATED CODE-->
<dependency>
<groupId>org.apache.camel.springboot</groupId>
<artifactId>camel-core-starter</artifactId>
</dependency>
<!--END OF GENERATED CODE-->
</dependencies>
<build>
<plugins>
<!-- parameter names are needed by the Spring AI annotation scanner to derive @McpTool
input schemas in the tests (Spring Boot applications get this from the boot parent) -->
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<configuration>
<parameters>true</parameters>
</configuration>
</plugin>
</plugins>
</build>
</project>
14 changes: 14 additions & 0 deletions components-starter/camel-mcp-server-starter/src/main/doc/intro.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
The MCP Server starter exposes Camel routes registered via the `ai-tool`
component as tools of a Model Context Protocol (MCP) server, served through
the Spring AI MCP server over streamable HTTP. No route is needed for the
server itself: add the starter, tag the `ai-tool` routes to expose, and any
MCP client (another Camel application, an IDE, a coding agent) can discover
and call them.

Tool semantics — tag-based opt-in (the untagged default pool is never
exposed), flat-namespace collision refusal, per-call timeout and error
sanitization — are owned by the runtime-agnostic `camel-mcp-server-api`
bridge and are identical on every Camel runtime. Serving concerns (endpoint
path, protocol, server identity, authentication) are owned by the Spring AI
MCP server and configured via `spring.ai.mcp.server.*`; use
`spring.ai.mcp.server.protocol=STREAMABLE` for the streamable HTTP transport.
210 changes: 210 additions & 0 deletions components-starter/camel-mcp-server-starter/src/main/doc/usage.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,210 @@
Define tools as regular `ai-tool` routes and give them tags:

[source,java]
----
from("ai-tool:query_db?tags=crm&description=Query customer database"
+ "&parameter.customerId=string&parameter.customerId.required=true")
.to("jdbc:dataSource");
----

or in YAML DSL:

[source,yaml]
----
- route:
from:
uri: "ai-tool:send_email"
parameters:
description: "Send email notification"
tags: "notify"
parameter.to: string
parameter.to.description: "Recipient address"
parameter.to.required: "true"
parameter.subject: string
parameter.priority: string
parameter.priority.enum: "low,normal,high"
steps:
- to: "smtp://mail.example.com"
----

Tool parameters are declared with the `parameter.NAME` options: the value is
the JSON type (`string`, `integer`, `number`, `boolean`), and the
`parameter.NAME.description`, `parameter.NAME.required` and
`parameter.NAME.enum` options refine the generated JSON Schema. Arguments
arrive as message headers in the route (`${header.customerId}`).

Select the tags to expose in `application.properties`:

[source,properties]
----
camel.mcp-server.tags = crm,notify

# per-call execution timeout (milliseconds, default 20000)
camel.mcp-server.tool-timeout = 10000
----

The streamable HTTP transport has to be selected explicitly with
`spring.ai.mcp.server.protocol=STREAMABLE`; when the property is not set,
Spring AI serves the deprecated SSE transport instead and there is no
endpoint at `/mcp`.

Serving concerns are configured on the Spring AI MCP server — see the
https://docs.spring.io/spring-ai/reference/api/mcp/mcp-streamable-http-server-boot-starter-docs.html[Spring AI MCP server documentation]
for the full list of `spring.ai.mcp.server.*` options. For example:

[source,properties]
----
spring.ai.mcp.server.protocol = STREAMABLE
spring.ai.mcp.server.name = my-integration-app
spring.ai.mcp.server.version = 1.0.0
spring.ai.mcp.server.streamable-http.mcp-endpoint = /mcp
----

=== Connecting MCP clients

Any MCP client can connect over streamable HTTP. Another Camel integration
can consume the tools with the camel-openai MCP client and automatic tool
execution:

[source,java]
----
from("direct:agent")
.to("openai:chat-completion"
+ "?model={{llm.model}}"
+ "&autoToolExecution=true"
+ "&mcpServer.myCamelTools.transportType=streamableHttp"
+ "&mcpServer.myCamelTools.url=http://localhost:8080/mcp");
----

A coding agent or IDE is configured with the same URL, e.g. in an
`mcp.json`-style client configuration:

[source,json]
----
{
"mcpServers": {
"my-integration-app": {
"type": "http",
"url": "http://localhost:8080/mcp"
}
}
}
----

=== Serving over stdio

Out of the box the tools are served over streamable HTTP: the starter brings
in `spring-ai-starter-mcp-server-webmvc`. MCP clients that launch the server
as a subprocess speak over stdin/stdout instead, which Spring AI serves with
the plain `spring-ai-starter-mcp-server`. Swap the transport starter:

[source,xml]
----
<dependency>
<groupId>org.apache.camel.springboot</groupId>
<artifactId>camel-mcp-server-starter</artifactId>
<exclusions>
<exclusion>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-mcp-server-webmvc</artifactId>
</exclusion>
</exclusions>
</dependency>
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-mcp-server</artifactId>
<version>2.0.0</version>
</dependency>
----

and enable the stdio transport:

[source,properties]
----
spring.ai.mcp.server.stdio = true
spring.main.web-application-type = none
spring.main.banner-mode = off

# stdout carries the MCP protocol, so nothing else may be written to it
logging.threshold.console = OFF
logging.file.name = my-integration-app.log
----

Because stdout carries the MCP protocol, the application must not run as a
web application, the banner has to be switched off and console logging has
to be turned off — writing the log to a file instead. Leaving console
logging on corrupts the protocol stream, as the Spring Boot startup log is
then interleaved with the JSON-RPC messages.

A stdio server is launched by the client instead of being connected to over
a URL:

[source,json]
----
{
"mcpServers": {
"my-integration-app": {
"command": "java",
"args": ["-jar", "/path/to/my-integration-app-1.0.0.jar"]
}
}
}
----

See the
https://docs.spring.io/spring-ai/reference/api/mcp/mcp-server-boot-starter-docs.html[Spring AI MCP Server Boot Starter documentation]
for the transport options and the full list of `spring.ai.mcp.server.*`
properties. On Quarkus the equivalent setup is described in the
https://docs.quarkiverse.io/quarkus-mcp-server/dev/getting-started-stdio.html[quarkus-mcp-server stdio guide].

=== Mixing with Spring-defined tools

Camel tools coexist with tools defined natively in Spring AI — both are
served by the same MCP server and appear in the same `tools/list`. For
example, a `@McpTool`-annotated bean:

[source,java]
----
@Component
public class CalculatorTools {

@McpTool(name = "add_numbers", description = "Add two numbers")
public String add(
@McpToolParam(description = "First addend", required = true) int a,
@McpToolParam(description = "Second addend", required = true) int b) {
return String.valueOf(a + b);
}
}
----

is exposed alongside the `ai-tool` routes. Spring-defined tools are
registered when the server is created; Camel tools are added and removed
dynamically with the route lifecycle. Choose distinct tool names — MCP has a
flat tool namespace.

=== Dynamic tools

The exposed tool list follows the route lifecycle: stopping or suspending an
`ai-tool` route removes its tool, starting or resuming it publishes the tool
again, and connected clients are notified via
`notifications/tools/list_changed`:

[source,java]
----
camelContext.getRouteController().stopRoute("query-db-route"); // tool disappears
camelContext.getRouteController().startRoute("query-db-route"); // tool is back
----

=== Error handling

Results returned to MCP clients are sanitized by the bridge: a route
exception produces an `isError` result with the generic message
`Tool execution failed` (the cause is logged server-side and never sent to
the client), a missing or invalid argument returns the validation message,
and a call exceeding `camel.mcp-server.tool-timeout` returns
`Tool execution timed out` while the route keeps running until it completes
on its own.

On Camel Main and Camel JBang the equivalent setup is the `camel-mcp-server`
module with the `camel.server.mcp-*` options; on Quarkus it is the
`camel-quarkus-mcp-server` extension.
35 changes: 35 additions & 0 deletions components-starter/camel-mcp-server-starter/src/main/docs/mcp-server.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
{
"groups": [
{
"name": "camel.mcp-server",
"type": "org.apache.camel.springboot.mcp.server.McpServerConfigurationProperties",
"sourceType": "org.apache.camel.springboot.mcp.server.McpServerConfigurationProperties"
}
],
"properties": [
{
"name": "camel.mcp-server.enabled",
"type": "java.lang.Boolean",
"description": "Whether to expose ai-tool routes as MCP tools through the Spring AI MCP server. Enabled by default when the starter is on the classpath.",
"sourceType": "org.apache.camel.springboot.mcp.server.McpServerConfigurationProperties",
"defaultValue": true
},
{
"name": "camel.mcp-server.tags",
"type": "java.lang.String",
"description": "Comma-separated list of ai-tool tags to expose as MCP tools. Only tools registered under one of these tags are exposed; the untagged default pool is never exposed. When not set, no tools are exposed.",
"sourceType": "org.apache.camel.springboot.mcp.server.McpServerConfigurationProperties"
},
{
"name": "camel.mcp-server.tool-timeout",
"type": "java.lang.Long",
"description": "Per-call tool execution timeout in milliseconds. A call exceeding the timeout returns an error result to the MCP client; the underlying route keeps running until it completes on its own.",
"sourceType": "org.apache.camel.springboot.mcp.server.McpServerConfigurationProperties",
"defaultValue": 20000
}
],
"hints": [],
"ignored": {
"properties": []
}
}

@davsclaus davsclaus Aug 4, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Non-blocking: missing trailing newline at end of file.

Loading
Loading