Spring AI MCP Intacct Query STDIO Server

A Spring Boot starter project demonstrating how to build a Model Context Protocol (MCP) server that provides Sage Intacct query and model definition tools using the Intacct Core API. This project showcases the Spring AI MCP Server Boot Starter capabilities with STDIO transport implementation.

For more information, see the MCP Server Boot Starter reference documentation.

Prerequisites

- Java 17 or later
- Maven 3.6 or later
- Understanding of Spring Boot and Spring AI concepts
- Sage Intacct account with API access
- OAuth2 credentials for Intacct API
- (Optional) Claude Desktop for AI assistant integration

About Spring AI MCP Server Boot Starter

The spring-ai-mcp-server-spring-boot-starter provides:
- Automatic configuration of MCP server components
- Support for both synchronous and asynchronous operation modes
- STDIO transport layer implementation
- Flexible tool registration through Spring beans
- Change notification capabilities

Project Structure

src/
├── main/
│   ├── java/
│   │   └── org/springframework/ai/mcp/sample/server/
│   │       ├── McpServerApplication.java    # Main application class with tool registration
│   │       ├── QueryService.java           # Intacct query service with MCP tools
│   │       ├── ModelService.java           # Intacct model definition service
│   │       └── AuthService.java            # OAuth2 authentication service
│   └── resources/
│       ├── application.properties          # Server and transport configuration
│       └── common.openapi.yaml            # OpenAPI specification reference
└── test/
    └── java/
        └── org/springframework/ai/mcp/sample/
            ├── client/
            │   └── ClientStdio.java         # Test client implementation
            └── server/
                └── ModelServiceTest.java    # Simple test for ModelService

Building and Running

The server uses STDIO transport mode and is typically started automatically by the client. To build the server jar:

./mvnw clean install -DskipTests

To run standalone for testing:

java -Dspring.ai.mcp.server.transport=STDIO \
     -Dspring.main.web-application-type=none \
     -Dlogging.pattern.console= \
     -Dintacct.client-id=YOUR_CLIENT_ID \
     -Dintacct.client-secret=YOUR_CLIENT_SECRET \
     -Dintacct.username=YOUR_USERNAME \
     -Dintacct.password=YOUR_PASSWORD \
     -jar target/mcp-query-stdio-server-0.1.0.jar

Tool Implementation

The project demonstrates how to implement and register MCP tools using Spring's dependency injection and auto-configuration:

@Service
public class QueryService {
    @Tool(description = "Query data from a Sage Intacct object using filters")
    public List<Map<String, Object>> executeQuery(
        String object,           // Object type (e.g., "accounts-payable/vendor")
        List<String> fields,     // Fields to include
        List<Map<String, Map<String, Object>>> filters, // Filter conditions
        String filterExpression, // Logical operators for filters
        // ... other parameters
    ) {
        // Implementation
    }
}
@Service

public class ModelService {

    @Tool(description = "Get an object model definition")

    public ObjectModel getModelDefinition(

        String name,    // Resource name

        String type,    // Optional resource type

        // ... other parameters

    ) {

        // Implementation

    }
@Tool(description = "List all available Intacct resource model summaries")

    public List<ResourceSummary> listAvailableModels() {

        // Implementation

    }

}
@SpringBootApplication

public class McpServerApplication {

    @Bean

    public ToolCallbackProvider intacctQueryTools(QueryService queryService) {

        return MethodToolCallbackProvider.builder().toolObjects(queryService).build();

    }
@Bean

    public ToolCallbackProvider intacctModelTools(ModelService modelService) {

        return MethodToolCallbackProvider.builder().toolObjects(modelService).build();

    }

}

Available Tools

1. Query Tool (executeQuery)

Query data from Sage Intacct objects with flexible filtering, field selection, and pagination.

Parameters:
- object (required): Object type to query (e.g., "accounts-payable/vendor")
- fields (optional): List of fields to include (e.g., ["id", "name", "status"])
- filters (optional): Array of filter conditions using operators like $eq, $gt, $contains, etc.
- filterExpression (optional): Logical combination of filters (e.g., "1 and 2")
- orderBy (optional): Sort order (e.g., [{"id": "asc"}])
- start (optional): Starting record for pagination
- size (optional): Number of records to return

Example usage:

{

  "object": "accounts-payable/vendor",

  "fields": ["id", "name", "status"],

  "filters": [{"$eq": {"status": "active"}}],

  "orderBy": [{"id": "asc"}],

  "size": 10

}

Supported Filter Operators:
- $eq: Equal to
- $ne: Not equal to
- $lt, $lte: Less than (or equal)
- $gt, $gte: Greater than (or equal)
- $in, $notIn: In/not in list of values
- $between, $notBetween: Between two values
- $contains, $notContains: Contains substring
- $startsWith, $endsWith: String pattern matching

2. Model Definition Tool (getModelDefinition)

Retrieve detailed model definitions for Intacct objects, including field types, relationships, and constraints.

Parameters:
- name (required): Resource name (e.g., "accounts-payable/vendor")
- type (optional): Resource type filter ("object", "service")
- version (optional): API version ("v1", "ALL")
- schema (optional): Include full schema ("true"/"false")
- tags (optional): Schema formatting ("true"/"false")

3. List Models Tool (listAvailableModels)

Get a summary of all available Intacct resource models.

Returns: List of resource summaries with API object names and types.

Authentication Configuration

The server requires OAuth2 credentials for Intacct API access. Configure through:

System Properties:

-Dintacct.client-id=your_client_id
-Dintacct.client-secret=your_client_secret
-Dintacct.username=your_username
-Dintacct.password=your_password
-Dintacct.base-url=https://partner.intacct.com/ia3/api/v1-beta2

Application Properties:

intacct.client-id=your_client_id
intacct.client-secret=your_client_secret
intacct.username=your_username
intacct.password=your_password
intacct.base-url=https://partner.intacct.com/ia3/api/v1-beta2

Environment Variables:

Client Integration

Java Client Example

// Create server parameters
ServerParameters stdioParams = ServerParameters.builder("java")
    .args("-Dspring.ai.mcp.server.transport=STDIO",
          "-Dspring.main.web-application-type=none",
          "-Dlogging.pattern.console=",
          "-Dintacct.client-id=" + clientId,
          "-Dintacct.client-secret=" + clientSecret,
          "-Dintacct.username=" + username,
          "-Dintacct.password=" + password,
          "-jar",
          "target/mcp-query-stdio-server-0.1.0.jar")
    .build();
// Initialize transport and client

var transport = new StdioClientTransport(stdioParams);

var client = McpClient.sync(transport).build();
// Query active vendors

CallToolResult result = client.callTool(

    new CallToolRequest("executeQuery",

        Map.of(

            "object", "accounts-payable/vendor",

            "fields", List.of("id", "name", "status"),

            "filters", List.of(Map.of("$eq", Map.of("status", "active"))),

            "size", 5

        )

    )

);

Claude Desktop Integration

Add to Claude Desktop configuration:

{
  "mcpServers": {
    "intacct-query": {
      "command": "java",
      "args": [
        "-Dspring.ai.mcp.server.transport=STDIO",
        "-Dspring.main.web-application-type=none",
        "-Dlogging.pattern.console=",
        "-Dintacct.client-id=YOUR_CLIENT_ID",
        "-Dintacct.client-secret=YOUR_CLIENT_SECRET",
        "-Dintacct.username=YOUR_USERNAME",
        "-Dintacct.password=YOUR_PASSWORD",
        "-jar",
        "/absolute/path/to/mcp-query-stdio-server-0.1.0.jar"
      ]
    }
  }
}

Configuration

Required STDIO Configuration