Unit Converter API + MCP Tutorial

Unit Converter API + MCP Tutorial

• builds the FastAPI app, wraps it with FastMCP, mounts MCP HTTP/SSE endpoints, registers resources and prompts, and starts uvicorn.
• requirements.txt – Python dependencies.

Prerequisites

• Python 3.10+ (tested with 3.12).
• Virtual environment.
• npm inspector below.

⸻

Setup from this folder

python -m venv .venv

# Mac or Gitbash
source .venv/bin/activate

# Windows powershell:
.venv\Scripts\activate
python -m pip install -r requirements.txt

⸻

Run the HTTP + MCP server

# start the server
python converter_streamable_http_server.py

# or
python -m converter_streamable_http_server

You’ll see:

• Swagger UI: http://localhost:8003/docs
• ReDoc: http://localhost:8003/redoc

MCP endpoints served by FastMCP:

• streamable-http: http://localhost:8003/mcp
• SSE: http://localhost:8003/sse

⸻

Try the HTTP endpoints (curl)

curl -X POST "http://localhost:8003/miles-to-kilometers?miles=3.1" \
 -H "Authorization: Bearer 143f4a46d74fee0d7918b2857577868cb3daf9e6e50ee91c2f7975ba26fdb8f7"

# If we use pydantic models
curl -X POST "http://localhost:8003/miles-to-kilometers" \
 -H "Content-Type: application/json" \
 -H "Authorization: Bearer Y658139cf61948208ed76a4b36122b9552ec5c3f6da5e02f7c5d85d995dede17dE" \
 -d "3.1"

# Celsius → Fahrenheit
curl -X POST "http://localhost:8003/celsius-to-fahrenheit" \
 -H "Content-Type: application/json" \
 -d "25"

# Fahrenheit → Celsius
curl -X POST "http://localhost:8003/fahrenheit-to-celsius" \
 -H "Content-Type: application/json" \
 -d "86"

# Kilometers → Miles
curl -X POST "http://localhost:8003/kilometers-to-miles" \
 -H "Content-Type: application/json" \
 -d "5"

# Miles → Kilometers (rejects negative values)
curl -X POST "http://localhost:8003/miles-to-kilometers" \
 -H "Content-Type: application/json" \
 -d "3.1"

Each endpoint returns JSON like:

• { "result": , "operation": "..." } or { "error": "..." } for invalid input.

Headers & Authentication (common to all)

Add JSON content type (and optionally your auth token)

-H "Content-Type: application/json" -H "Authorization: Bearer "

Our server doesn’t require auth yet, we can omit the Authorization header.

Use with MCP (VS Code Example)

1. Start the server as above.
2. Point your MCP client to the process.

// Example VS Code .vscode/mcp.json entry:
{
  "servers": {
    "UnitConverter": {
      "command": "python",
      "args": ["converter_api_tutorial.py"]
    }
  }
}

3. From the MCP client, list artifacts. You should see:
   • Tools: celsius_to_fahrenheit, fahrenheit_to_celsius, kilometers_to_miles, miles_to_kilometers
   • Resources: resource://unit_reference, resource://troubleshooting_guide
   • Prompts: explain_conversion, api_usage

⸻

Inspect with the npm MCP Inspector

• explore everything (tools, resources, prompts) in a browser.
• with the server already running on http://localhost:8003

# If env error appears
npx @modelcontextprotocol/inspector@latest -e DUMMY=1 --url http://localhost:8003/mcp --transport streamable-http

# If you want to test the older HTTP:
npx @modelcontextprotocol/inspector@latest -e DUMMY=1 --url http://localhost:8003/mcp --transport http

# If you want to test the deprecated SSE:
npx @modelcontextprotocol/inspector@latest -e DUMMY=1 --url http://localhost:8003/sse --transport sse

To run the STDIO server only

# If venv is ".venv", change to .\.venv\Scripts\python.exe
npx @modelcontextprotocol/inspector python converter_stdio_server.py

• UI runs on localhost:5173 by default.
• Change UI port if needed: CLIENT_PORT=8080 npx @modelcontextprotocol/inspector --url http://localhost:8003/mcp --transport http
• Add headers if required: --header "Authorization: Bearer TOKEN".

JSON-RPC Examples for Prompts & Resources

1. List all prompts

curl -s -X POST <SERVER_URL> \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"prompts/list","params":{},"id":1}'

⸻

2. Get a specific prompt

curl -s -X POST <SERVER_URL> \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"prompts/get","params":{"name":"summarize"},"id":2}'

⸻

3. Render/execute a prompt with variables

curl -s -X POST <SERVER_URL> \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"prompts/render","params":{"name":"summarize","variables":{"text":"This is the content to summarize","tone":"neutral"}},"id":3}'

4. List available resources

curl -s -X POST <SERVER_URL> \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"resources/list","params":{},"id":4}'

5. Read a resource by URI

curl -s -X POST <SERVER_URL> \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"resources/read","params":{"uri":"file:///data/report.pdf"},"id":5}'

6. Search resources (if supported)

curl -s -X POST <SERVER_URL> \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"resources/search","params":{"query":"error OR exception","limit":50},"id":6}'

⸻

Handling errors

• Parse error (-32700)
• Invalid request (-32600)
• Method not found (-32601)
• Invalid params (-32602)
• Internal error (-32603)

Notes

macOS/Linux (bash/zsh)• The examples above will work as-is.

# Windows PowerShell
curl -Method POST <SERVER_URL> `  -Headers @{ "Content-Type"="application/json" }`
-Body '{"jsonrpc":"2.0","method":"prompts/list","params":{},"id":1}'

Windows CMD

curl -s -X POST <SERVER_URL> -H "Content-Type: application/json" -d "{\"jsonrpc\":\"2.0\",\"method\":\"prompts/list\",\"params\":{},\"id\":1}"