JSONPlaceholder MCP Server (practice project)

A minimal MCP server, built with the official Python SDK's FastMCP helper, that wraps the public JSONPlaceholder REST API. It's meant as a template: swap BASE_URL and the tool functions for your own internal API and the shape stays the same.

What it exposes

MCP tool	REST call
list_posts	GET /posts
get_post	GET /posts/{id}
create_post	POST /posts
get_comments_for_post	GET /posts/{id}/comments
get_user	GET /users/{id}
list_users	GET /users

1. Set up

cd jsonplaceholder-mcp
python -m venv .venv
source .venv/bin/activate       # on Windows: .venv\Scripts\activate
pip install -r requirements.txt

2. Sanity-check it runs

python server.py

It should sit there waiting on stdio (no visible output is expected — that's normal, it's waiting for an MCP client to talk to it over stdin/stdout). Ctrl+C to stop.

You can also use the MCP inspector to poke at it interactively without wiring up a full client:

mcp dev server.py

This opens a browser UI where you can call each tool by hand and see the JSON that comes back.

3. Connect it to Claude Desktop

Add an entry to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "jsonplaceholder": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["/absolute/path/to/jsonplaceholder-mcp/server.py"]
    }
  }
}

Restart Claude Desktop, and the jsonplaceholder tools should show up in the tool picker.

4. Where to go from here (adapting to a real API)

To point this at an internal REST service instead:

1. Change BASE_URL.
2. Add auth — most internal APIs need a header or token. Add it once in _get/_post (e.g. headers={"Authorization": f"Bearer {TOKEN}"}), pulling the token from an environment variable rather than hardcoding it.
3. Replace each @mcp.tool() function with one per operation you want to expose. Keep the docstrings precise — the LLM uses them to decide when and how to call each tool, so vague docstrings lead to the tool being picked (or skipped) incorrectly.
4. Keep tools narrow and single-purpose rather than one giant "call any endpoint" tool — that's what makes MCP tools reliable for an LLM to select correctly.