Solesonic MCP Server

🚀 solesonic-mcp-server

A Spring Boot application that exposes an HTTP Model Context Protocol (MCP) server using Spring AI, facilitating easy interaction with the MCP.

This README provides guidance on running the server and setting up an MCP client to establish a connection.

🚀 Quick Start

✨ Features

• Exposes an HTTP MCP server using Spring AI.
• Secured as an OAuth2 Resource Server (JWT).
• Supports a simple tool named message_me for echoing messages.

📦 Installation

Prerequisites

• JDK 24+
• Maven 3.9+
• AWS Cognito (or another OAuth2 provider capable of issuing JWTs with the expected audience and scope)

The application is configured to load environment variables from a local .env file at runtime using spring-dotenv.

Configure environment

Create or edit the .env file at the project root (this file is gitignored):

COGNITO_ISSUER_URI=https://example.auth.<region>.amazoncognito.com
# Optionally override the JWK set URI if needed
# COGNITO_JWK_SET_URI=https://cognito-idp.<region>.amazonaws.com/<userPoolId>/.well-known/jwks.json

Relevant properties from src/main/resources/application.properties:

spring.application.name=solesonic-mcp-server
spring.ai.mcp.server.name=solesonic-mcp-server
spring.ai.mcp.server.version=1.0.0
spring.ai.mcp.server.type=sync
spring.ai.mcp.server.capabilities.tool=true

# OAuth2 Resource Server (AWS Cognito)
spring.security.oauth2.resourceserver.jwt.issuer-uri=${COGNITO_ISSUER_URI}
spring.security.oauth2.resourceserver.jwt.jwk-set-uri=${COGNITO_JWK_SET_URI}
spring.security.oauth2.resourceserver.jwt.audiences=api://solesonic-mcp

Notes:

• OS environment variables override values from .env.
• No extra flags are required; .env is loaded automatically at startup.

Build and run

# Build
mvn package

# Run (adjust the jar name if necessary)
java -jar target/solesonic-mcp-server-0.0.1-SNAPSHOT.jar

Default base URL: http://localhost:8080

💻 Usage Examples

Authentication and authorization

This server is protected as an OAuth2 Resource Server (JWT) and requires a valid bearer token for all requests.

• Expected audience: api://solesonic-mcp (refer to application.properties)
• Required scope: MCP_INVOKE
  • Spring Security maps OAuth scopes to authorities with a SCOPE_ prefix. The code checks for SCOPE_MCP_INVOKE.

⚠️ Important Note

The current SecurityConfig secures all endpoints. If you expect /actuator/health to be public, adjust the security config accordingly. As it stands, you must provide a valid token for all requests.

MCP endpoint

This project utilizes the Spring AI MCP Server (WebMVC) starter, which exposes an HTTP MCP endpoint under /mcp.

• Base MCP HTTP endpoint: POST http://localhost:8080/mcp
• Transport: HTTP (JSON-RPC over HTTP as defined by MCP HTTP transport)
• Tools: This sample registers a simple tool named message_me that echoes a message

Obtaining a token from Cognito (client credentials example)

You need a token that includes the MCP_INVOKE scope and the audience api://solesonic-mcp.

# 1) Get a token using client credentials (values are examples; replace placeholders)
TOKEN=$(curl -s \
  -u <clientId>:<clientSecret> \
  -d "grant_type=client_credentials&scope=MCP_INVOKE" \
  https://<your-domain>.auth.<region>.amazoncognito.com/oauth2/token \
  | jq -r .access_token)

echo "$TOKEN" | head -c 20; echo

# 2) Use the token to call the MCP endpoint (the inspector/client will normally perform the handshake; this is a sanity check)
curl -i \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -X POST \
  http://localhost:8080/mcp \
  --data '{"jsonrpc":"2.0","id":"1","method":"initialize","params":{"capabilities":{}},"meta":{}}'

If you receive 401/403, refer to the Troubleshooting section below.

Set up a client for this MCP server

Option A: MCP Inspector (CLI)

The MCP Inspector is a useful tool for interactive testing.

Requirements: Node.js 18+

# Install and run via npx
npx @modelcontextprotocol/inspector \
  --server http \
  --url http://localhost:8080/mcp \
  --header "Authorization: Bearer $TOKEN"

This will perform the MCP handshake and allow you to introspect tools like message_me.

Option B: Claude Desktop (HTTP MCP server)

Claude Desktop supports MCP servers. You can register an HTTP MCP server with headers.

1. Open the Claude Desktop MCP configuration file (varies by OS). On macOS, for example:

• ~/Library/Application Support/Claude/mcp.json

2. Add an entry for this server. Example snippet:

{
  "mcpServers": {
    "solesonic-mcp-server": {
      "transport": "http",
      "url": "http://localhost:8080/mcp",
      "headers": {
        "Authorization": "Bearer ${SOLESONIC_MCP_TOKEN}"
      }
    }
  }
}

3. Set an environment variable with your token before launching Claude Desktop:

• macOS/Linux: export SOLESONIC_MCP_TOKEN="$TOKEN"
• Windows (PowerShell): $env:SOLESONIC_MCP_TOKEN = "$TOKEN"

4. Restart Claude Desktop. You should see the solesonic-mcp-server MCP provider available, with the message_me tool.

💡 Usage Tip

If Claude Desktop does not yet support HTTP MCP with headers in your version, you can alternatively run a small local proxy that injects the Authorization header, or use the MCP Inspector for testing.

Using the sample tool

Once a client is connected, you can invoke the message_me tool by passing a message argument, and it will echo the message back.

🔧 Technical Details

Troubleshooting

• 401 Unauthorized
  • Token is missing, expired, or not issued by the configured Cognito issuer-uri.
  • JWKS URL is unreachable or misconfigured.
• 403 Forbidden
  • Token is valid but lacks the required MCP_INVOKE scope. Ensure your OAuth client is permitted to request that scope and that Cognito includes it in the access token.
• Audience mismatch
  • Ensure the token audience matches api://solesonic-mcp or adjust application.properties accordingly.
• Connectivity
  • Verify that the app is listening on http://localhost:8080 and that /mcp is reachable.

📄 License

No license information provided.

Notes

• .env is intended solely for local development. Real OS environment variables override values from .env.
• The .env file is gitignored to prevent the accidental committed of secrets.

Work in progress

For ongoing enhancements, current status, and the roadmap, refer to the living document:

• IN_PROGRESS.md