API 연동 자동화를 위한 여정: 토스는 왜 사내 MCP 서버를 개발하였는가? with Spring-AI

PUT /apis/1.0/foreigners/{foreignerId}/passport

Headers:
- user-id (integer, required)

Request body:
{
	"firstName": "string",
	"middleName": "string",
	"lastName": "string",
	"fullName": "string",
	"dateOfBirth": "date",
	"dateOfExpiry": "date",
	"gender": "FEMALE|MALE",
	"passportNumber": "string",
	"nationality": "string"
}

Response:
{
	"resultType": "SUCCESS|HTTP_TIMEOUT|NETWORK_ERROR|...",

implementation("org.springframework.ai:spring-ai-starter-mcp-server-webmvc:1.1.0-M3")

spring.ai.mcp.server.protocol=STATELESS

spring.ai.mcp.server.type=ASYNC

class DateTimeTools {
    @Tool(description = "Get the current date and time from the user's timezone")
    String getCurrentDateTimeWithZone(
        @ToolParam(description = "Zone Id ex) Asia/Seoul") ZoneId zoneId
    ) {
        return LocalDateTime.now()
            .atZone(zoneId)
            .toString()
    }
}

@Configuration
class DateTimeToolsConfig {
    @Bean
    fun dateTimeTools(dateTimeTools: DateTimeTools): ToolCallbackProvider {
        return MethodToolCallbackProvider
            .builder()
            .toolObjects(dateTimeTools)
            .build()
    }
}

[
  {
    "serviceName": "foreigner",
    "apiGroups": ["guest", "foreigner"]
  }
]

{
  "/apis/1.0/foreigners/{foreignerId}/passport": {
    "put": {
      "tags": ["여권 API"],
      "operationId": "addPassport",
      "summary": "여권 등록 API"
    }
  }
}

{
  "parameters": [
    {
      "name": "user-id",
      "in": "header",
      "required": true,
      "schema": {
        "type": "integer",
        "format": null,
        "enum": null
      }
    }
  ],
  "requestBody": {
    "required": [
      "name",
      "dateOfBirth",
      "dateOfExpiry",
      "nationality",
      "gender",
      "passportNumber"
    ],
    "type": "object",
    "properties": {
      "name": {
        "type": "string"
      },
      "fullName": {
        "type": "string"
      },
      "dateOfBirth": {
        "type": "string",
        "format": "date"
      },
      "dateOfExpiry": {
        "type": "string",
        "format": "date"
      },
      "gender": {
        "type": "string",
        "enum": [
          "FEMALE",
          "MALE"
        ]
      },
      "passportNumber": {
        "type": "string"
      },
      "nationality": {
        "type": "string"
      }
    }
  },
  "responses": {
    "type": "object",
    "properties": {
      "resultType": {
        "type": "string",
        "enum": [
          "SUCCESS",
          "TIMEOUT",
          "NETWORK_ERROR",
          "INTERNAL_SERVER_ERROR",
        ]
      },
      "error": {
        "$ref": "#/components/schemas/ErrorMessage"
      },
      "success": {
        "type": "boolean"
      }
    }
  }
}

{
  "#/components/schemas/ErrorMessage": {
    "type": "object",
    "properties": {
      "errorType": {
        "type": "string",
        "format": "int32"
      },
      "errorCode": {
        "type": "integer",
        "format": "int32"
      },
      "message": {
        "type": "object"
      }
    }
  }
}

@Configuration
class SwaggerPrompt {
    @Bean
    fun searchApisPrompt(): List<McpStatelessServerFeatures.AsyncPromptSpecification> {
        val prompt = Prompt(
            "search-toss-servers-apis",
            "Search relevant apis from one of toss-servers",
            listOf(
                PromptArgument("serverName", "The name of toss server", true),
                PromptArgument("apiDesc", "Description of api to search", true),
            )
        )

        val promptSpecification = McpStatelessServerFeatures.AsyncPromptSpecification(prompt) { _, promptRequest ->
            val serverName = promptRequest.arguments()["serverName"] as String
            val apiDesc = promptRequest.arguments()["apiDesc"] as String
            val userMessage = PromptMessage(
                Role.USER,
                TextContent("target server name: ${serverName}, search command: $apiDesc"),
            )
            Mono.just(
                GetPromptResult(
                    "Search result for APIs from $serverName matching '${apiDesc}

springdoc.use-fqn=true

@Bean
fun loginUserOperationCustomizer(): OperationCustomizer {
    return OperationCustomizer { operation: Operation, handlerMethod: HandlerMethod ->
        val hasLoginUser = handlerMethod.methodParameters.any {
            it.hasParameterAnnotation(LoginUser::class.java)
        }

        if (hasLoginUser) {
            operation.parameters?.removeIf { param ->
                param.name == "loginUser" ||
                param.schema?.`$ref`?.contains("User") == true
            }

            val userIdParameter = Parameter()
                .name("user-id")
                .`in`("header")
                .description("User ID")
                .required(true)
                .schema(Schema<String>().type("integer"))

            if (operation.parameters == null) {
                operation.parameters = mutableListOf()
            }
            operation.parameters.add(userIdParameter)
        }

        operation
    }
}