Hello World MCP FastAPI Endpoint

# Hello World MCP FastAPI Endpoint This project exposes a minimal [Model Context Protocol](https://modelcontextprotocol.io/) 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 ```bash python -m venv .venv source .venv/bin/activate pip install -r requirements.txt ``` ## Running the server ```bash 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) ```bash 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 ```bash # 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 ```bash # 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