McpTool Service Integration

This document is intended to help the mcpTool service access the Apache ShenYu gateway. The Apache ShenYu gateway uses the mcpServer plugin to connect with mcpTool services.

Before the connection, start shenyu-admin correctly, start mcpServer plugin and add related dependencies on the gateway and mcpTool application client service side. You can refer to the previous Quick Start with McpServer.

For details about client access configuration, see Application Client Access Config .

For details about data synchronization configurations, see Data Synchronization Config .

Add mcpServer and proxy plugins in gateway

• Add the following dependencies to the gateway’s pom.xml file:

    <!--Mcp Server Plugin Start-->
    <dependency>
        <groupId>org.apache.shenyu</groupId>
        <artifactId>shenyu-spring-boot-starter-plugin-mcp-server</artifactId>
        <version>${project.version}</version>
    </dependency>
    <!--Mcp Server Plugin End-->

Integrate mcpTool with the gateway (for springMvc)

Refer to the example project: shenyu-examples-mcp

• SpringBoot Users

  1. Add the following dependencies to your mcpTool service’s pom.xml file:

  <dependency>
      <groupId>org.apache.shenyu</groupId>
      <artifactId>shenyu-spring-boot-starter-client-mcp</artifactId>
      <version>${shenyu.version}</version>
  </dependency>

  2. Add the following configuration in application.yaml:

  shenyu:
    register:
      registerType: http #zookeeper #etcd #nacos #consul
      serverLists: http://localhost:9095 #localhost:2181 #http://localhost:2379 #localhost:8848
      props:
        username: admin
        password: 123456
    client:
      mcp:
        props:
          contextPath: /mcp
          appName: mcp

• Spring Users

  Add the following dependencies to your HTTP service’s pom.xml file:

  <dependency>
      <groupId>org.apache.shenyu</groupId>
      <artifactId>shenyu-client-mcp</artifactId>
      <version>${shenyu.version}</version>
  </dependency>

  Then add the following bean definitions to your XML configuration file:

  <bean id="clientConfig" class="org.apache.shenyu.register.common.config.PropertiesConfig">
      <property name="props">
        <map>
          <entry key="contextPath" value="/yourContextPath"/>
          <entry key="appName" value="yourAppName"/>
        </map>
      </property>
  </bean>
  
  <bean id="shenyuRegisterCenterConfig" class="org.apache.shenyu.register.common.config.ShenyuRegisterCenterConfig">
     <property name="registerType" value="http"/>
     <property name="serverList" value="http://localhost:9095"/>
  </bean>
  
  <bean id="shenyuClientRegisterRepository" class="org.apache.shenyu.client.core.register.ShenyuClientRegisterRepositoryFactory" factory-method="newInstance">
         <property name="shenyuRegisterCenterConfig" ref="shenyuRegisterCenterConfig"/>
   </bean>
  
  <bean id="McpServiceEventListener" class="org.apache.shenyu.client.mcp.McpServiceEventListener">
     <constructor-arg name="clientConfig" ref="clientConfig"/>
     <constructor-arg name="shenyuClientRegisterRepository" ref="shenyuClientRegisterRepository"/>
     <constructor-arg name="env" ref="environment"/>  
  </bean>

  Add the @ShenyuMcpTool annotations to your controller interfaces.

  You need to add the @ShenyuMcpTool annotation on the Controller class. Only controllers annotated with @ShenyuMcpTool will be recognized as mcpTool.

Example 1

This example demonstrates full McpTool configuration. You can fully customize your configuration by annotations, including parameter information defined in the operation.

@GetMapping("/findById")
@ShenyuMcpTool(
        operation = @Operation(
                method = "GET", description = "find order by id"
        ),
        requestConfig = @ShenyuMcpRequestConfig(
                bodyToJson = "false",
                headers = {
                        @ShenyuMcpHeader(key = "aaa", value = "bbb")
                }
        ),
        enabled = true, toolName = "findOrderById"
)
@ApiDoc(desc = "findById")
public OrderDTO findById(@ShenyuMcpToolParam(
        parameter = @Parameter(
                name = "id",
                in = ParameterIn.PATH,
                description = "the id of order",
                required = true,
                schema = @Schema(
                        type = "string",
                        defaultValue = "1"
                )
        )
) @RequestParam("id") final String id) {
        OrderDTO dto = new OrderDTO();
        dto.setId(id);
        return dto;
}

Example 2

This example shows the configuration for a McpTool function without parameters.

@GetMapping("/findAll")
@ShenyuMcpTool(
        operation = @Operation(
                method = "GET", description = "find all order"
        ),
        requestConfig = @ShenyuMcpRequestConfig(
                bodyToJson = "false",
                headers = {
                        @ShenyuMcpHeader(key = "aaa", value = "bbb")
                }
        ),
        enabled = true, toolName = "findAllOrder"
)
@ApiDoc(desc = "findAll")
public String findAll() {
        return "hello apache shenyu , mcp findAll success";
}

Example 3

This is a simplified usage that requires only a simple annotation to register the McpTool to the gateway.

Special note: Currently only supports @RequestMapping, @GetMapping, @PostMapping, @DeleteMapping, and @PutMapping annotations. Only the first path of the @XXXMapping annotation is effective.

@GetMapping("/findByName")
@ShenyuMcpTool
@ApiDoc(desc = "findName")
public OrderDTO findByName(@ShenyuMcpToolParam final String name) {
        OrderDTO dto = new OrderDTO();
        dto.setName(name);
        return dto;
}

• Start your project. Your service interfaces will be connected to the gateway. In the shenyu-admin backend management system, go to Plugin List -> HTTP process -> mcpServer, and you will see the automatically created endpoints and Tools.

McpTool integration with gateway (Other Languages, Non-SpringMvc)

• First, find the mcpServer plugin in shenyu-admin, then add selectors and rules to filter traffic accordingly.

• If you are unsure how to configure, please refer to Selector and Rule Management.

User requests

After your mcpTool service is connected to the Apache ShenYu gateway, you can use the endPoint configured in the Selector as the request interface for your McpClient.

• Firstly, the domain name of your previous endPoint was your own service; now it should be replaced with the gateway’s domain name.

• Secondly, the Apache ShenYu gateway requires a route prefix configured as the contextPath in your integration project.

  • In the mcpServer plugin, this contextPath corresponds to your endPoint.

  • For example, if you configured contextPath as mcp, then your endPoint should be configured as: http://localhost:9195/mcp/sse.

  • Here, localhost:9195 is the IP and port of your gateway (default port is 9195), and /mcp is the contextPath configured during integration.

• Third, the mcpServer plugin does not include request forwarding functionality. To perform remote tool invocation, please enable the corresponding proxy plugin for proxying. You can refer to Quick Start with McpServer.

Then you can invoke tools via the mcpClient through the gateway easily.