MCP Proxy Connection Guide

Overview

This guide explains how to connect to your Spring Boot MCP Proxy from different clients:

Claude Desktop - Connect AI assistant to your MCP tools
Postman - Test and register tools via REST API

Prerequisites

✅ Spring Boot MCP Proxy running on http://localhost:8081
✅ Target REST API running (e.g., http://localhost:8080)
✅ Node.js and npm installed (for Claude Desktop connection)
✅ Postman installed (for API testing)

Demo Applications

This project includes two example REST APIs that you can use to test the MCP proxy:

Option 1: Store Management API 🏪

Purpose: Demonstrates CRUD operations for store entities

Port: http://localhost:8080

Available Endpoints:

GET /stores - List all stores
GET /stores/{id} - Get store by ID
POST /stores - Create new store
PUT /stores/{id} - Update existing store
DELETE /stores/{id} - Delete store

Example Entity:

{
  "id": 1,
  "name": "Store A",
  "location": "New York City"
}

Use Case: Perfect for demonstrating basic CRUD operations with Claude

Option 2: Temperature Control API 🌡️

Purpose: Demonstrates IoT/sensor control and monitoring

Port: http://localhost:8080 (alternative to Store API)

Available Endpoints:

GET /weather - Get current temperature
POST /weather?temp=<int> - Set target temperature

Example Operations:

Read weather info
Update weather info

Use Case: Great for demonstrating IoT control scenarios with Claude

Choosing Your Demo App

For Store Management API:

cd /path/to/store-api
./mvnw spring-boot:run
# Runs on http://localhost:8080

For Temperature Control API:

cd /path/to/temperature-api
./mvnw spring-boot:run
# Runs on http://localhost:8090

Part 1: Claude Desktop Connection

Step 1: Install NPX (if not already installed)

# Check if npx is available
npx --version

# If not installed, install Node.js from https://nodejs.org/

Step 2: Configure Claude Desktop

Open Claude Desktop Settings
- Launch Claude Desktop application
- Navigate to: Settings → Developer → Local MCP servers
- Click "Edit Config"
Add MCP Server Configuration

Add the following configuration to your Claude Desktop config file:

{
  "mcpServers": {
    "spring-mcp-server": {
      "command": "npx",
      "args": ["mcp-remote", "http://localhost:8081/sse"]
    }
  }
}

Configuration Breakdown:

"spring-mcp-server" - Name of your MCP server (can be customized)
"command": "npx" - Uses npx to run the mcp-remote package
"args" - Arguments passed to npx:
- "mcp-remote" - Package that enables remote MCP connections
- "http://localhost:8081/sse" - Your MCP proxy SSE endpoint

Step 3: Save and Restart Claude Desktop

Save the configuration file
Restart Claude Desktop completely (close and reopen)
Verify connection:
- Look for "spring-mcp-server" with status "running" (blue badge)
- Check that tools are available in Claude

Step 4: Register Tools Before Using

Before Claude can use any tools, you must register them via the REST API:

Option A: Register from Swagger/OpenAPI

curl -X POST "http://localhost:8081/tools/register?baseUrl=http://localhost:8080"

Option B: Register Manual Tools

curl -X POST "http://localhost:8081/tools/register/manual" \
  -H "Content-Type: application/json" \
  -d '[{
    "name": "getStoreById",
    "description": "Fetch a store by its ID",
    "httpMethod": "GET",
    "endpoint": "/stores/{id}",
    "baseUrl": "http://localhost:8080",
    "pathParams": {"id": "integer"}
  }]'

Step 5: Use Tools in Claude

Once tools are registered, you can interact with Claude naturally:

Example Conversation:

You: Can you fetch store with ID 123?

Claude: I'll use the getStoreById tool to fetch that information.
[Calls: http_localhost_8080_getStoreById with {"id": 123}]

Here's the store information:
- ID: 123
- Name: Store A
- Location: New York City

Part 2: Postman Connection & Tool Registration

Step 1: Import Postman Collection

Open Postman
Import Collection:
- Click Import button
- Select the mcp.postman_collection.json file
- Collection "mcp" will be added to your workspace

Step 2: Available Postman Endpoints

The collection includes these pre-configured requests:

1. Register Tools from Swagger 📥

Request:

POST http://localhost:8081/tools/register?baseUrl=http://localhost:8080

Purpose: Automatically discover and register all endpoints from an OpenAPI-enabled REST API

Response Example:

Registered tools from http://localhost:8080, total tools = 5

When to use:

Quick registration of entire APIs
APIs with OpenAPI/Swagger documentation at /v3/api-docs

2. Register Manual Tools ✍️

Request:

POST http://localhost:8081/tools/register/manual
Content-Type: application/json

[
  {
    "name": "getById",
    "description": "Fetch store by id",
    "httpMethod": "GET",
    "endpoint": "/stores/{id}",
    "baseUrl": "http://localhost:8080",
    "pathParams": {
      "id": "integer"
    },
    "queryParams": null,
    "requestBody": null
  },
  {
    "name": "update_store",
    "description": "Update an existing store by ID",
    "httpMethod": "PUT",
    "endpoint": "/stores/{id}",
    "baseUrl": "http://localhost:8080",
    "pathParams": {
      "id": "integer"
    },
    "queryParams": {},
    "requestBody": {
      "type": "object",
      "properties": {
        "name": { "type": "string" },
        "location": { "type": "string" }
      },
      "required": ["name", "location"]
    }
  }
]

Response Example:

Registered 2 manual tools successfully.

When to use:

Custom tool definitions
APIs without OpenAPI documentation
Fine-grained control over tool parameters
Specific endpoints from larger APIs

3. List Tools by Base URL 📋

Request:

GET http://localhost:8081/tools/list?baseUrl=http://localhost:8080

Purpose: View all registered tools for a specific API base URL

Response Example:

[
  "http_localhost_8080_getById",
  "http_localhost_8080_update_store",
  "http_localhost_8080_createStore",
  "http_localhost_8080_deleteStore",
  "http_localhost_8080_listStores"
]

When to use:

Verify successful registration
Check tool names before deletion
Audit registered tools

4. Delete Tools 🗑️

Request:

DELETE http://localhost:8081/tools/delete
Content-Type: application/json

[
  "http_localhost_8080_getById",
  "http_localhost_8080_update_store"
]

Response Example:

Deleted tools: [http_localhost_8080_getById, http_localhost_8080_update_store]

When to use:

Remove outdated tools
Clean up after testing
Manage tool lifecycle

Step 3: Typical Workflow in Postman

1. Start MCP Proxy Server (port 8081)
   ↓
2. Start Target REST API (port 8080)
   ↓
3. Test target API directly (verify it's working)
   ↓
4. Register tools via Postman:
   - Option A: POST /tools/register?baseUrl=...
   - Option B: POST /tools/register/manual
   ↓
5. Verify registration:
   - GET /tools/list?baseUrl=...
   ↓
6. Test in Claude Desktop (tools now available)
   ↓
7. (Optional) Delete tools when done:
   - DELETE /tools/delete

Part 3: Complete Connection Flow

Visual Connection Architecture

┌─────────────────────────────────────────────────────────────┐
│                     Claude Desktop                          │
│  ┌────────────────────────────────────────────────────┐    │
│  │  MCP Configuration (claude_desktop_config.json)    │    │
│  │  {                                                  │    │
│  │    "mcpServers": {                                  │    │
│  │      "spring-mcp-server": {                         │    │
│  │        "command": "npx",                            │    │
│  │        "args": ["mcp-remote",                       │    │
│  │                 "http://localhost:8081/sse"]        │    │
│  │      }                                               │    │
│  │    }                                                 │    │
│  │  }                                                  │    │
│  └────────────────────┬───────────────────────────────┘    │
└─────────────────────────┼───────────────────────────────────┘
                          │ SSE Connection
                          │ (MCP Protocol)
                          ↓
┌──────────────────────────────────────────────────────────────┐
│            Spring Boot MCP Proxy (Port 8081)                 │
│  ┌──────────────────────────────────────────────────────┐   │
│  │  /sse endpoint - MCP Protocol (for Claude)          │   │
│  └──────────────────────────────────────────────────────┘   │
│  ┌──────────────────────────────────────────────────────┐   │
│  │  REST API Endpoints (for Postman):                   │   │
│  │  • POST /tools/register?baseUrl=...                  │   │
│  │  • POST /tools/register/manual                       │   │
│  │  • GET  /tools/list?baseUrl=...                      │   │
│  │  • DELETE /tools/delete                              │   │
│  └──────────────────────────────────────────────────────┘   │
└────────┬─────────────────────────────────────────────────────┘
         │ HTTP Requests
         │ (Tool Execution)
         ↓
┌──────────────────────────────────────────────────────────────┐
│              Target REST API (Port 8080)                     │
│  • GET    /stores/{id}                                       │
│  • POST   /stores                                            │
│  • PUT    /stores/{id}                                       │
│  • DELETE /stores/{id}                                       │
│  • GET    /stores                                            │
└──────────────────────────────────────────────────────────────┘

                    ┌────────────────┐
                    │    Postman     │
                    │  (Testing &    │
                    │  Registration) │
                    └────────┬───────┘
                             │ REST API Calls
                             ↓
                    (Port 8081 Endpoints)

Part 4: Troubleshooting

Claude Desktop Issues

Problem: "spring-mcp-server" shows as stopped or error

✅ Solutions:

Verify MCP proxy is running: curl http://localhost:8081/actuator/health
Check npx is installed: npx --version
Restart Claude Desktop completely
Check config file syntax (valid JSON)
Look at Claude Desktop logs (Settings → Developer)

Problem: "No tools available" in Claude

✅ Solutions:

Tools must be registered first via Postman
Check registered tools: GET http://localhost:8081/tools/list?baseUrl=...
After registering, wait 5-10 seconds for Claude to refresh
Restart Claude Desktop if needed

Problem: Tool execution fails

✅ Solutions:

Verify target API is running
Check tool parameters match API requirements
Review MCP proxy logs: tail -f mcp.demo.log
Test endpoint directly in Postman first

Postman Issues

Problem: Connection refused to localhost:8081

✅ Solutions:

Verify MCP proxy is running: curl http://localhost:8081/actuator/health
Check port 8081 is not blocked by firewall
Verify application.properties has server.port=8081

Problem: 500 Error when registering from Swagger

✅ Solutions:

Verify target API has OpenAPI docs: curl http://localhost:8080/v3/api-docs
Check target API is actually running
Ensure baseUrl format is correct (no trailing slash)

Problem: Manual tool registration validation error

✅ Solutions:

Check all required fields are provided
Ensure requestBody is an object, not primitive
Verify endpoint starts with /
Validate JSON syntax

Part 5: Example Use Cases - End to End

Use Case 1: Store Management API 🏪

Scenario: Register and Use a Store Management API

Step 1: Start Services

# Terminal 1: Start Store API
cd /path/to/store-api
./mvnw spring-boot:run
# Runs on http://localhost:8080

# Terminal 2: Start MCP proxy
cd /path/to/mcp-proxy
./mvnw spring-boot:run
# Runs on http://localhost:8081

Step 2: Register Tools (Postman)

POST http://localhost:8081/tools/register?baseUrl=http://localhost:8080

Response:

Registered tools from http://localhost:8080, total tools = 5

Step 3: Verify Tools (Postman)

GET http://localhost:8081/tools/list?baseUrl=http://localhost:8080

Response:

[
  "http_localhost_8080_getStoreById",
  "http_localhost_8080_createStore",
  "http_localhost_8080_updateStore",
  "http_localhost_8080_deleteStore",
  "http_localhost_8080_listAllStores"
]

Step 4: Configure Claude Desktop Edit config:

{
  "mcpServers": {
    "spring-mcp-server": {
      "command": "npx",
      "args": ["mcp-remote", "http://localhost:8081/sse"]
    }
  }
}

Restart Claude Desktop.

Step 5: Use in Claude

You: Show me all stores in the system

Claude: [Calls http_localhost_8080_listAllStores]
Here are all the stores currently in the system:
1. Store A - New York City
2. Store B - Los Angeles
3. Store C - Chicago

You: Update store 2 to change its location to San Francisco

Claude: [Calls http_localhost_8080_updateStore with 
        {"id": 2, "name": "Store B", "location": "San Francisco"}]
Successfully updated! Store B's location is now San Francisco.

You: Create a new store called "Store D" in Miami

Claude: [Calls http_localhost_8080_createStore with
        {"name": "Store D", "location": "Miami"}]
Successfully created! Store D has been added in Miami.

Part 6: Configuration Reference

Claude Desktop Config File Locations

macOS:

~/Library/Application Support/Claude/claude_desktop_config.json

Windows:

%APPDATA%\Claude\claude_desktop_config.json

Linux:

~/.config/Claude/claude_desktop_config.json

Full Configuration Example

{
  "mcpServers": {
    "spring-mcp-server": {
      "command": "npx",
      "args": ["mcp-remote", "http://localhost:8081/sse"]
    },
    "another-api": {
      "command": "npx",
      "args": ["mcp-remote", "http://localhost:9000/sse"]
    }
  }
}

Note: You can register multiple MCP servers simultaneously!

Part 7: Best Practices

Registration Best Practices

✅ DO:

Register tools once at startup
Use Swagger registration for full APIs
Use manual registration for specific endpoints
Test tools in Postman before using in Claude
Delete unused tools to keep Claude's tool list clean

❌ DON'T:

Register duplicate tools
Leave test tools in production
Register tools with overly generic names
Forget to restart Claude after config changes

Security Considerations

⚠️ Important:

MCP proxy runs on localhost by default (secure)
Don't expose port 8081 to external networks without authentication
Target APIs should have proper authentication
Consider adding API key validation for production use

Part 8: Quick Reference Commands

Start/Stop Services

# Start MCP Proxy
cd /path/to/mcp-proxy
./mvnw spring-boot:run

# Stop: Ctrl+C

# Check health
curl http://localhost:8081/actuator/health

Register Tools via cURL

# Swagger registration
curl -X POST "http://localhost:8081/tools/register?baseUrl=http://localhost:8080"

# Manual registration
curl -X POST "http://localhost:8081/tools/register/manual" \
  -H "Content-Type: application/json" \
  -d '[{"name":"getStore","httpMethod":"GET","endpoint":"/stores/{id}","baseUrl":"http://localhost:8080","pathParams":{"id":"integer"}}]'

# List tools
curl "http://localhost:8081/tools/list?baseUrl=http://localhost:8080"

# Delete tools
curl -X DELETE "http://localhost:8081/tools/delete" \
  -H "Content-Type: application/json" \
  -d '["http_localhost_8080_getStore"]'

Claude Desktop Commands

# Edit config (macOS)
open ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Restart Claude Desktop
# Close app completely, then reopen

Summary

This guide covered:

✅ Claude Desktop Connection - SSE-based MCP protocol connection
✅ Postman Testing - REST API tool registration and management
✅ Complete Workflow - End-to-end setup and usage
✅ Troubleshooting - Common issues and solutions
✅ Best Practices - Security and usage recommendations

Key Takeaway: Register tools via Postman REST API → Use tools via Claude Desktop MCP connection!

Name		Name	Last commit message	Last commit date
Latest commit History 14 Commits
demo		demo
mcp		mcp
second demo		second demo
README.md		README.md
claude-connection example.png		claude-connection example.png
mcp.postman_collection.json		mcp.postman_collection.json
postman url example.png		postman url example.png

Saivarunt/mcp-data-source-middleware

Folders and files

Latest commit

History

Repository files navigation

MCP Proxy Connection Guide

Overview

Prerequisites

Demo Applications

Option 1: Store Management API 🏪

Option 2: Temperature Control API 🌡️

Choosing Your Demo App

Part 1: Claude Desktop Connection

Step 1: Install NPX (if not already installed)

Step 2: Configure Claude Desktop

Step 3: Save and Restart Claude Desktop

Step 4: Register Tools Before Using

Step 5: Use Tools in Claude

Part 2: Postman Connection & Tool Registration

Step 1: Import Postman Collection

Step 2: Available Postman Endpoints

1. Register Tools from Swagger 📥

2. Register Manual Tools ✍️

3. List Tools by Base URL 📋

4. Delete Tools 🗑️

Step 3: Typical Workflow in Postman

Part 3: Complete Connection Flow

Visual Connection Architecture

Part 4: Troubleshooting

Claude Desktop Issues

Postman Issues

Part 5: Example Use Cases - End to End

Use Case 1: Store Management API 🏪

Scenario: Register and Use a Store Management API

Part 6: Configuration Reference

Claude Desktop Config File Locations

Full Configuration Example

Part 7: Best Practices

Registration Best Practices

Security Considerations

Part 8: Quick Reference Commands

Start/Stop Services

Register Tools via cURL

Claude Desktop Commands

Summary

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages