solesonic

Solesonic MCP Server is a Spring Boot HTTP MCP (Model Context Protocol) server that exposes MCP endpoints over JSON-RPC via HTTP. It secures access with OAuth2 JWT validation and maps groups and roles to authorities, enabling granular access control for tools and prompts. Built-in Jira tooling allows creating and managing issues, with an Atlassian Token Broker integration to mint short-lived access tokens for Jira operations. The server also includes web search tools and a set of prompts for guiding structured workflows and elicitation of user input. To use it, deploy the server (e.g., via Docker in production or your preferred runtime), ensure JWT validation is configured using JWK_SET_URI or ISSUER_URI along with Jira and Atlassian token broker settings, and then send MCP requests to the /mcp endpoint. Tools are invoked via MCP RPC calls and require appropriate scopes and/or group-based authorities as defined in your security configuration. See the documentation sections on Endpoints, Tools, Security, and Configuration for details on how to discover available tools and how to address authentication, authorization, and token brokerage.

Prerequisites:

• Java 25+ (for running the application directly) or Docker for containerized deployment
• Maven 3.9+ (for building from source)
• Optional: Docker (recommended for production-like runs)

Basic install (local JVM run):

1. Clone the repository: git clone https://github.com/isaacpeel/solesonic-mcp-server.git cd solesonic-mcp-server

2. Build (using Maven Wrapper): ./mvnw clean verify

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

   Note: To enable production-like HTTPS locally, run with the prod and ssl profiles: ./mvnw spring-boot:run -Dspring-boot.run.profiles=prod,ssl

Containerized deployment (Docker):

1. Build the Docker image (if a Dockerfile is provided): docker build -t solesonic-mcp-server:latest .

2. Run the container (example): docker run -i -p 9443:9443 solesonic-mcp-server:latest

Environment configuration (required values):

• JWK_SET_URI or ISSUER_URI to configure JWT validation
• JIRA_URL_TEMPLATE, ATLASSIAN_TOKEN_BROKER_URL, ATLASSIAN_TOKEN_BROKER_ISSUER_URI, ATLASSIAN_TOKEN_BROKER_CLIENT_ID, ATLASSIAN_TOKEN_BROKER_CLIENT_SECRET for Jira tooling and token broker
• JIRA_CLOUD_ID_PATH for Jira Cloud identification
• Optional TLS configuration via ssl profile when running with prod/ssl

If you’re using Docker, you can set environment variables on container run as needed, and mount configuration files if required by your setup.

Tips and common considerations:

• Ensure your OAuth2/JWT configuration matches your IdP (use either JWK_SET_URI or ISSUER_URI depending on your setup).
• Jira tooling relies on the Atlassian Token Broker to mint short-lived tokens; keep the broker URL, issuer, and client credentials secure and up-to-date.
• When running with SSL (prod, ssl), the server will expect TLS, and the base URL will be https://localhost:9443 by default. Ensure the PKCS12 keystore is configured for TLS in production builds.
• The MCP endpoint is exposed at POST /mcp. Tools and prompts are available via MCP RPC calls; ensure your clients request the correct method names and payloads as documented in the endpoints/tools docs.
• If you encounter certificate or TLS issues locally, you can run with -Dspring-boot.run.profiles=prod,ssl and use a trusted keystore or disable strict TLS for testing only.
• For troubleshooting, consult the Documentation section links in the README (Configuration, Security, Endpoints, Tools, Prompts, Web Search, Deployment, Troubleshooting).