MCP Demo

A learning project for the Model Context Protocol (MCP). It has one MCP server that exposes a few example tools, and two clients that let a language model discover and call those tools — one driven by a local model via LM Studio (free, offline) and one driven by Claude (Anthropic API).

The point of the project is to show that the server is model-agnostic: the same server.py works with any model — only the client changes.

How it fits together

  You type a question
          │
          ▼
   client (drives the LLM)  ──►  LLM decides to call a tool
          │                              │
          │  spawns over stdio           │
          ▼                              ▼
      server.py  ◄───────────  client executes the tool call
   (add1, multiply2, greet)     and feeds the result back

• server.py — the MCP server (built with FastMCP). Defines the tools.
• client_lmstudio.py — chat loop that drives a local model (LM Studio).
• client_claude.py — same idea, driven by Claude (needs an API key).

The client launches server.py as a subprocess and talks to it over stdio (standard in/out). It lists the server's tools, hands them to the model, and runs the loop: model asks to call a tool → client runs it against the server → result goes back to the model → repeat until the model gives a final answer.

Tools exposed by the server

Tool	What it does
add1(a, b)	Returns a + b + 1 (the extra +1 proves the tool actually ran)
multiply2(a, b)	Returns a * b * 2
greet(name, excited=False)	Returns a greeting; excited=True adds enthusiasm

There's also a config://version resource returning the app version.

These are placeholder tools. To make the project do something real, replace the bodies with actual logic (a DB query, an API call, a computation) — the wiring stays exactly the same.

Setup

Requires Python 3.10+.

python3 -m venv .venv
source .venv/bin/activate

pip install -r requirements.txt

That installs everything: mcp[cli] (the server + Inspector), openai (the LM Studio client), and anthropic[mcp] (the Claude client — only needed if you use that one).

Running with a local model (LM Studio) — free, no API key

This is the recommended way to try it — it runs entirely on your machine.

1. Install and open LM Studio.

2. Download a model that supports tool/function calling. This project uses qwen2.5-7b-instruct-1m, which handles tools well. Other good picks: Qwen2.5 Instruct, Llama 3.1/3.2 Instruct. Small or non-instruct models often call tools poorly.

3. Start the local server: LM Studio → Developer / Local Server tab → load the model → Start Server. It listens on http://localhost:1234/v1 (an OpenAI-compatible endpoint).

4. Check the model id shown in LM Studio matches the MODEL constant near the top of client_lmstudio.py; update it if you loaded a different model.

5. Run the client:

   .venv/bin/python client_lmstudio.py
   

6. Chat. Type a question at the You: prompt, e.g. "Greet Alice excitedly, then add 5 and 7." Type exit or quit to leave.

If the "5 + 7" answer comes back as 13 (not 12), that confirms the model really called your add1 tool instead of doing its own arithmetic.

Notes on local models: they follow instructions less reliably than cloud models — responses may be verbose or occasionally skip a tool. Verbosity is tuned via the system prompt at the top of the client's messages list. Swapping to a stronger model in LM Studio also helps.

Running with Claude (Anthropic API) — costs a small amount

1. Get an API key at console.anthropic.com (Settings → API Keys).

2. Export it:

   export ANTHROPIC_API_KEY=sk-ant-...
   

3. Run:

   .venv/bin/python client_claude.py
   

Same behavior, but Claude follows instructions and calls tools more reliably. Costs are tiny (a fraction of a cent for this demo).

Inspecting the server directly (no LLM)

To poke the tools by hand in a browser UI:

.venv/bin/mcp dev server.py

This opens the MCP Inspector, where you can call each tool manually. (If it errors trying to spawn uv, either install uv, or in the Inspector set Command to your venv's python and Arguments to server.py.)

Things worth remembering

• The client and server transport must match. These clients spawn the server and talk over stdio, so server.py must end with mcp.run(). If you switch it to mcp.run(transport="sse") (an HTTP server), the stdio client breaks — it'll try to parse the web-server's log lines as protocol messages.
• In stdio mode, don't print() inside tools — stdout is the protocol channel. Use print(..., file=sys.stderr) for debugging.
• The server never changes when you switch models. MCP standardizes the tool server; each model provider just needs its own client (or a framework that abstracts them).

Possible next steps

• Replace the placeholder tools with real functionality.
• Add a graphical UI (Streamlit / Gradio / Chainlit for a quick chat box, or FastAPI + a web frontend for a real webapp).
• Serve the tools over HTTP (transport="streamable-http") so they can be reached remotely instead of only as a local subprocess.