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 .

Agent Builder

• Node type: MCP
• URL: https://<service>/mcp
• Transport: Streamable HTTP
• Auth: None
• Click Connect → tools should list: ping, server_time, echo, date_math