nanomcp

This is a minimal MCP demo written from scratch without the MCP Python SDK. It contains the complete link:

1. nanomcp.server acts as the MCP server, sending and receiving JSON-RPC via stdio.

2. nanomcp.cli acts as the MCP client/host, starting the server and performing initialize, tools/list, and tools/call.

3. The chat command calls OpenAI Chat Completions. After the model returns a function/tool call, the CLI converts it into an MCP tools/call, and then sends the tool result back to the model to generate the final answer.

The relationship between MCP and function calling

In a nutshell: function calling is the model API capability where "the model tells your application which function it wants to call"; MCP is the connection protocol for "how your application uses a unified protocol to discover and call external tools/context services."

More specifically:

• Function/tool calling happens between LLM API <-> your application. The model does not actually execute the function; it only returns an intent to call, such as {"name":"get_weather","arguments":{...}}.

• MCP happens between your application <-> MCP server. The MCP server exposes a tool list and execution entry point, such as tools/list and tools/call.

• The host/client is the middleman. It first gets the tool schema from the MCP server and converts these schemas into model API tools; after the model selects a tool, the host/client then calls the MCP server.

The link in this project is:

用户问题
  -> nanomcp.cli
  -> OpenAI Chat Completions tools=function schemas
  <- 模型返回 tool_calls
  -> nanomcp.cli 把 tool_call 映射为 MCP tools/call
  -> nanomcp.server 执行 get_weather 或 find_files
  <- MCP tool result
  -> nanomcp.cli 把结果发回模型
  <- 模型最终回答

So they are not at the same level:

Function call: 模型 API 的工具选择/参数生成机制
MCP: 应用连接工具服务器的标准协议

Related MCP server: MCP Server Demo

File structure

nanomcp/
  nanomcp/
    cli.py       # MCP client + model caller
    server.py    # hand-written MCP server over stdio
  tests/
    test_protocol.py
  pyproject.toml
  README.md

Running MCP directly, without calling the model

Run in the project directory:

cd ~/Desktop/nanomcp
python3 -m nanomcp.cli list-tools

Call the weather tool directly:

python3 -m nanomcp.cli call get_weather '{"location":"Shanghai","unit":"celsius"}'

Call the current date and time tool directly:

python3 -m nanomcp.cli call get_current_datetime '{"timezone":"Asia/Shanghai"}'

Call the file search tool directly:

python3 -m nanomcp.cli call find_files '{"query":"*.pdf","max_results":5}'

By default, it only searches ~/Desktop. You can temporarily expand or shrink the search root directory:

NANOMCP_FILE_ROOT=~/Desktop/nanomcp python3 -m nanomcp.cli call find_files '{"query":"*.py"}'

Running the full model + MCP link

An OpenAI API key is required. This project does not use the OpenAI Python SDK, but uses the standard library urllib to send HTTP requests directly.

It is recommended to write local configuration into .env:

cd ~/Desktop/nanomcp
cp .envtemplate .env

Then edit .env:

OPENAI_API_KEY=你的 key
OPENAI_BASE_URL=https://api.openai.com/v1
NANOMCP_MODEL=gpt-4.1-mini
NANOMCP_TIMEZONE=Asia/Shanghai

.env will be automatically read by the CLI and has already been ignored by .gitignore.

cd ~/Desktop/nanomcp
python3 -m nanomcp.cli chat "上海今天天气怎么样？顺便帮我找桌面上的 PDF 文件"

The default model is gpt-4.1-mini. You can change it:

NANOMCP_MODEL=gpt-5-mini python3 -m nanomcp.cli chat "找一下这个项目里的 py 文件"

If you use an OpenAI-compatible gateway:

OPENAI_BASE_URL=http://localhost:8000/v1 python3 -m nanomcp.cli chat "上海天气怎么样？"

Lightweight check of local configuration and MCP server:

python3 -m nanomcp.cli doctor

Troubleshooting

If chat outputs OpenAI API quota is exhausted (429 insufficient_quota), it means the model API rejected the request: the project associated with the current OPENAI_API_KEY has no available quota or billing is not enabled. This is not an MCP server failure, as the request was rejected before the model returned a tool call.

Troubleshooting order:

python3 -m nanomcp.cli doctor
echo "$OPENAI_API_KEY"
cat .env
python3 -m nanomcp.cli call get_weather '{"location":"Shanghai"}'
OPENAI_BASE_URL=http://localhost:8000/v1 python3 -m nanomcp.cli chat "上海天气怎么样？"

• The first command displays valid configuration with sensitive info masked, whether the shell overrides .env, and whether the MCP server can list tools.

• The second command confirms whether the key is already set in the shell.

• The third command confirms the local configuration in .env.

• The fourth command verifies whether the local MCP link is normal, without relying on the model API.

• The fifth command demonstrates how to switch to an OpenAI-compatible gateway.

• If you still use the official OpenAI API, you need to replace it with a key/project that has quota, or check billing and model permissions.

Optional real weather

The default weather is deterministic demo data, which is convenient for learning the protocol link without a network or third-party keys. To try a real query:

NANOMCP_LIVE_WEATHER=1 python3 -m nanomcp.cli call get_weather '{"location":"Shanghai"}'

Real weather uses https://wttr.in, and will automatically fall back to demo data if it fails.

Testing

cd ~/Desktop/nanomcp
python3 -m unittest discover -s tests

Test coverage:

• MCP initialize

• MCP tools/list

• MCP tools/call get_weather

• MCP tools/call find_files

• MCP tools/call get_current_datetime

Key observations

See openai_tools_from_mcp() in nanomcp/cli.py: it converts the MCP tool schema into the OpenAI function tool schema.

See run_chat(): it calls mcp.call_tool() after receiving tool_calls from the model. This is the connection point between MCP and function calling.

See main() in nanomcp/server.py: it only reads from stdin and writes to stdout, with each line being JSON-RPC. The server does not know about OpenAI, nor does it directly touch the model.