Hello World MCP FastAPI Endpoint

This project exposes a minimal Model Context Protocol server backed by FastAPI. It registers both a resource and a tool that respond with a “Hello World” message so you can validate your MCP client integration end-to-end.

Setup

python -m venv .venv source .venv/bin/activate pip install -r requirements.txt

Running the server

uvicorn app:app --reload --port 8080

The readiness probe is available at http://127.0.0.1:8080/, the health endpoint at http://127.0.0.1:8080/healthz, and the MCP streamable HTTP endpoint is mounted at http://127.0.0.1:8080/mcp.

Trying it from an MCP client

Point your MCP-compatible LLM or SDK at http://127.0.0.1:8080/mcp. You should see:

resource://hello returning "Hello from the Model Context Protocol!"
say_hello tool returning a greeting.

These serve as a starting point for wiring up richer resources and tools.

Run with Docker (single command)

docker compose up --build

The server will be reachable on http://127.0.0.1:8080/ (and /healthz) after the build completes.

MCP (Streamable HTTP)

Endpoint: https://<service>/mcp
CORS: Exposes Mcp-Session-Id header for browser clients (Agent Builder).

Tools

ping() -> "pong"
server_time(fmt?: string) -> string (UTC)
echo(text: string) -> string

Quick checks

# 1) Handshake (should return Mcp-Session-Id) curl -i https://<service>/mcp # 2) List tools (replace $SID with header from step 1) SID=<paste-session-id> curl -s -H "Content-Type: application/json" -H "Mcp-Session-Id: $SID" \ -X POST --data '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' \ https://<service>/mcp

Agent Builder

MCP node URL: https://<service>/mcp
Auth: None
After connect, tools ping, server_time, echo should be selectable.

MCP (Streamable HTTP)

Endpoint: https://<service>/mcp (no trailing slash required)

Tools

ping() -> "pong"
server_time(fmt?: string) -> string (UTC)
echo(text: string) -> string
date_math(expr: string) -> string (UTC). Examples: "+2h", "-15m", "+1d 30m"

Verify via curl

# 1) Handshake — should return Mcp-Session-Id header curl -i https://<service>/mcp # 2) Save session id and list tools SID=$(curl -sI https://<service>/mcp | awk -F': ' '/^Mcp-Session-Id:/ {print $2}' | tr -d '\r') curl -s -H "Content-Type: application/json" -H "Mcp-Session-Id: $SID" \ -X POST --data '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' \ https://<service>/mcp | jq . # 3) Call a tool curl -s -H "Content-Type: application/json" -H "Mcp-Session-Id: $SID" \ -X POST --data '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"date_math","arguments":{"expr":"+2h"}}}' \ https://<service>/mcp | jq .