ModernBank MCP Server

ModernBank MCP Server is a Spring Boot 3.2 application that exposes a Minimal Chat Protocol (MCP) compatible HTTP API for routing end-user banking requests through Google Gemini function-calling workflows and ModernBank backend services. The service interprets chat messages, asks Gemini to decide which downstream capability should be invoked, forwards the call to the appropriate ModernBank service over Feign clients, and maps the response back to MCP-compliant payloads.

Features

• Gemini integration – Uses the com.google.genai SDK (gemini-flash-latest model) with a system prompt that describes the ModernBank capabilities and available tools. Requests are streamed so the service can capture function calls emitted by the model before the stream completes. 【F:src/main/java/com/modernbank/mcp_server/service/impl/MCPHandlerServiceImpl.java†L30-L187】
• Tool orchestration – Declares four Gemini tools (transaction_list, transfer_money, get_user_accounts, get_account_detail) and dynamically maps each emitted function call to a Spring ServiceHandler. Missing parameters (for example, a missing accountId) are resolved through helper flows that fetch accounts and return selectable options to the chat client. 【F:src/main/java/com/modernbank/mcp_server/service/impl/MCPHandlerServiceImpl.java†L187-L338】【F:src/main/java/com/modernbank/mcp_server/config/MissingInputResolver.java†L17-L52】
• Service registry – Central registry that associates function names with concrete handlers (TransactionService, AccountService, PaymentService). Attempting to execute an unknown function fails fast. Note that transfer_money is currently registered to TransactionService, but the handler does not implement a branch for that function name yet, so such calls will raise an IllegalArgumentException. 【F:src/main/java/com/modernbank/mcp_server/config/ServiceRegistry.java†L9-L37】【F:src/main/java/com/modernbank/mcp_server/service/impl/TransactionService.java†L20-L74】
• Header propagation – Feign interceptor copies authentication and user context headers (Authorization, X-User-Id, X-User-Email, X-User-Role) from incoming HTTP requests to outbound Feign calls, ensuring downstream services receive end-user metadata. 【F:src/main/java/com/modernbank/mcp_server/config/FeignHeaderPropagationInterceptor.java†L10-L35】
• Account-aware responses – When Gemini omits required account identifiers, the server enriches the response with an MCP pendingRequest that lists available accounts and prompts the client to choose one. 【F:src/main/java/com/modernbank/mcp_server/config/MissingInputResolver.java†L17-L52】

Project structure

modernbank-mcp-server/
├── pom.xml                     # Maven configuration (Spring Boot 3.2, Spring Cloud OpenFeign, Google Gemini SDK)
├── src/main/java
│   ├── com/modernbank/mcp_server
│   │   ├── McpServerApplication.java              # Spring Boot entry point
│   │   ├── aspect/BeforeControllerAspect.java     # Aspect that copies user headers into BaseRequest arguments when present
│   │   ├── config/                                # Gemini client, Feign interceptors, service registry, missing-input resolver
│   │   ├── controller/MCPController.java          # REST controller implementing the MCP endpoints
│   │   ├── service/                               # Service interfaces and handlers invoked after Gemini function routing
│   │   ├── api/                                   # DTOs, Feign clients, and controller contract
│   │   └── model/                                 # Chat message, pending request, and transaction domain objects
├── src/main/resources/application.yml             # Service ports, Gemini API key placeholder, Feign target URLs
└── src/test/java/com/modernbank/mcp_server        # Spring context smoke test

HTTP API

The controller is mounted at /v1/api/mcp and implements the contract defined in MCPControllerApi.

Method	Path	Description
POST	/v1/api/mcp/process	Primary MCP endpoint. Accepts a SendMessageRequest containing chat history and optional arguments. Delegates to MCPHandlerService which orchestrates Gemini and downstream services. 【F:src/main/java/com/modernbank/mcp_server/controller/MCPController.java†L29-L53】【F:src/main/java/com/modernbank/mcp_server/api/MCPControllerApi.java†L11-L15】
POST	/v1/api/mcp/invoke	Stubbed endpoint for direct function invocation (FunctionInvokeRequest). Currently returns null, so clients should not rely on it. 【F:src/main/java/com/modernbank/mcp_server/controller/MCPController.java†L55-L59】
POST	/v1/api/mcp/process-old	Deprecated/placeholder route kept for backward compatibility. It is currently unimplemented. 【F:src/main/java/com/modernbank/mcp_server/controller/MCPController.java†L21-L43】

Gemini tools and downstream calls

Function name	Handler	Downstream call
transaction_list	TransactionService	Calls TransactionServiceClient#getTransactions with pagination, type, and range parameters. 【F:src/main/java/com/modernbank/mcp_server/service/impl/TransactionService.java†L38-L63】
transaction_create	TransactionService	Builds TransferMoneyBetweenUsersRequest and calls TransactionServiceClient#transferMoneyBetweenAccounts. 【F:src/main/java/com/modernbank/mcp_server/service/impl/TransactionService.java†L65-L102】
ATM_transaction_create	TransactionService	Placeholder branch for ATM operations; currently returns null. 【F:src/main/java/com/modernbank/mcp_server/service/impl/TransactionService.java†L104-L118】
get_user_accounts	AccountService	Calls AccountServiceClient#getAccounts with user headers populated. 【F:src/main/java/com/modernbank/mcp_server/service/impl/AccountService.java†L32-L46】
get_user_account_details	AccountService	Calls AccountServiceClient#getAccountDetails using the supplied accountId. 【F:src/main/java/com/modernbank/mcp_server/service/impl/AccountService.java†L48-L63】
transfer_money	TransactionService (registered)	Not yet implemented – mapped in ServiceRegistry, but no corresponding branch exists. Invocation will raise IllegalArgumentException. 【F:src/main/java/com/modernbank/mcp_server/config/ServiceRegistry.java†L18-L32】【F:src/main/java/com/modernbank/mcp_server/service/impl/TransactionService.java†L20-L29】
get_user_accounts (helper)	MissingInputResolver	When Gemini omits an accountId, the resolver fetches accounts and returns pendingRequest metadata so the client can ask the user to choose an account. 【F:src/main/java/com/modernbank/mcp_server/config/MissingInputResolver.java†L17-L52】

Configuration

All runtime configuration lives in src/main/resources/application.yml.

gemini:
  api:
    key: #YOUR-GEMINI-API-KEY
server:
  port: 8090
feign:
  client:
    account-service:
      url: http://localhost:8084/api/v1
      getAccounts: /account/getv2
    transaction-service:
      url: http://localhost:8083/api/v1
      getTransactions: /transaction/transactionsv2
services:
  transaction:
    url: http://localhost:8083/api/v1/transaction
  payment:
    url: http://localhost:8085/api/v1/payment

Before starting the application, supply a valid Gemini API key (for example through an environment variable or a Spring profile) and adjust the Feign base URLs to match the locations of the downstream ModernBank services.

The GeminiConfig class wires the Google client and a shared Gson instance, while ApplicationConfiguration registers the Feign header propagation interceptor. 【F:src/main/java/com/modernbank/mcp_server/config/GeminiConfig.java†L6-L28】【F:src/main/java/com/modernbank/mcp_server/config/ApplicationConfiguration.java†L8-L14】

Building and running

Prerequisites:

• Java 17
• Maven 3.9+

Run locally

./mvnw spring-boot:run

The service listens on port 8090 by default. Ensure the downstream Account, Transaction, and Payment services (or suitable mocks) are reachable at the URLs defined in application.yml.

Package

./mvnw clean package

Tests

The project currently contains a single Spring context smoke test:

./mvnw test

Running the test suite simply verifies that the application context loads successfully. 【F:src/test/java/com/modernbank/mcp_server/McpServerApplicationTests.java†L5-L13】

Error handling

• Missing or unknown Gemini function calls cause the handler to close the streaming response and throw an IllegalArgumentException, which surfaces as a 500 error payload via the controller. 【F:src/main/java/com/modernbank/mcp_server/service/impl/MCPHandlerServiceImpl.java†L128-L158】【F:src/main/java/com/modernbank/mcp_server/config/ServiceRegistry.java†L24-L31】
• Downstream Feign exceptions are wrapped in runtime exceptions with descriptive messages, so clients receive error responses indicating which ModernBank service failed. 【F:src/main/java/com/modernbank/mcp_server/service/impl/TransactionService.java†L43-L118】【F:src/main/java/com/modernbank/mcp_server/service/impl/AccountService.java†L36-L62】
• The PaymentService converts Feign failures into a structured TransferResponse with success=false. 【F:src/main/java/com/modernbank/mcp_server/service/impl/PaymentService.java†L16-L43】

Known limitations and TODOs

• /v1/api/mcp/invoke and /v1/api/mcp/process-old are stubs that currently return null.
• ServiceRegistry registers transfer_money to TransactionService, but there is no matching branch in TransactionService#execute. Implementing this function is necessary before enabling Gemini to call it.
• ATM_transaction_create in TransactionService returns null because the ATM integration is not yet wired.
• BeforeControllerAspect only operates on controller method parameters that extend BaseRequest; the current MCP endpoints do not expose such parameters, so the aspect has no effect yet. 【F:src/main/java/com/modernbank/mcp_server/aspect/BeforeControllerAspect.java†L9-L32】
• PaymentService still uses an empty fromAccount placeholder until JWT parsing is implemented. 【F:src/main/java/com/modernbank/mcp_server/service/impl/PaymentService.java†L26-L43】