Solesonic MCP Server

A Spring Boot HTTP MCP (Model Context Protocol) server powered by Spring AI. Secured as an OAuth2 Resource Server (JWT) with group- and scope-based authorization, built-in Jira tooling, and an external Atlassian Token Broker integration.

Features

• HTTP MCP Endpoint — JSON-RPC over HTTP at POST /mcp
• Built-in Jira tools — create, get, and delete issues; guided agile board workflow
• Date and Time tools — current date, time, and combined datetime with optional timezone
• Demo utility tool — weather_lookup as a simple example
• OAuth2 Resource Server (JWT) — JWT validation; group claims mapped to authorities
• MCP Authorization & Dynamic Client Registration — see Authorization
• Group & Role Authorization — groups → GROUP_<name> roles → ROLE_<role>
• Atlassian Token Broker — Client-credentials integration for short-lived Atlassian access tokens
• Production SSL Ready — PKCS12 keystore via ssl profile; TLS 1.2/1.3
• Web Search Tools — General, advanced, and news search via Tavily; content extraction
• MCP Prompts — Server-exposed prompts for structured workflows and agent guidance
• Elicitation Prompts — Guided workflows for structured user input and problem refinement

Quick Start

Prerequisites

• Java 25+
• Maven 3.9+
• Docker (optional, for production-like run)

1) Configure Environment

Note: OS environment variables take precedence over .env.

# JWT verification (use one of the following depending on your IdP)
JWK_SET_URI=https://your-issuer/.well-known/jwks.json
# or
ISSUER_URI=https://your-issuer

# Jira tooling
JIRA_URL_TEMPLATE=https://your-domain.atlassian.net/browse/{key}
ATLASSIAN_TOKEN_BROKER_URL=https://your-token-broker.example.com/broker/atlassian/token
ATLASSIAN_TOKEN_BROKER_ISSUER_URI=https://your-authz-server/oauth2/token
ATLASSIAN_TOKEN_BROKER_CLIENT_ID=your-client-id
ATLASSIAN_TOKEN_BROKER_CLIENT_SECRET=your-client-secret
JIRA_CLOUD_ID_PATH=/path/to/your/cloud-id

Note: OS environment variables take precedence over .env.

2) Build and Run (Local)

# Build
./mvnw clean verify

# Run (default profiles)
./mvnw spring-boot:run

• Base URL: https://localhost:9443 (when the ssl profile is active); otherwise http://localhost:9443
• MCP endpoint: POST /mcp

Tip: To enable HTTPS locally, run with profiles prod,ssl: ./mvnw spring-boot:run -Dspring-boot.run.profiles=prod,ssl

JVM Options for JDK 25+

On JDK 25+, Netty requires native access for optimal performance. To suppress warnings about restricted method calls, add the following JVM option:

--enable-native-access=ALL-UNNAMED

Maven tests: Already configured in pom.xml via maven-surefire-plugin.

IntelliJ IDEA: Add to your run configuration under VM options:

• Run > Edit Configurations > Select your configuration > Modify options > Add VM options
• Add: --enable-native-access=ALL-UNNAMED

Command line (spring-boot:run):

./mvnw spring-boot:run -Dspring-boot.run.jvmArguments="--enable-native-access=ALL-UNNAMED"

JAR execution:

java --enable-native-access=ALL-UNNAMED -jar target/solesonic-mcp-server-1.2.0.jar

3) Verify Setup

Send an MCP initialize request (replace placeholders):

curl -k \
  -H "Authorization: Bearer <YOUR_JWT_ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -X POST https://localhost:9443/mcp \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "initialize",
    "params": {"protocolVersion": "2024-11-05", "client": {"name": "curl", "version": "1.0"}}
  }'

For a richer client experience, see Clients for MCP Inspector and Claude Desktop examples.

MCP Server & Token Broker

• The server exposes tools via the MCP protocol. Tool invocation is authorized using JWT scopes and/or group authorities.
• Jira tools are first-class features. They rely on an external Atlassian Token Broker to mint short-lived access tokens from securely stored refresh tokens.

See:

• Endpoints
• Tools
• Security
• Configuration
• Prompts
• Web Search

Documentation

• Start here: Documentation
• Deep dives: Configuration, Security, Endpoints, Tools, Prompts, Web Search, Deployment, Troubleshooting

---

Ready to build with MCP? Jump into the Quickstart.