---
site: "zyx.tw"
title: "MCP 用 JSON-RPC 傳訊息：先取得工具定義，再轉送模型選定的操作"
description: "沿著 client 與 server 的訊息往返，分清工具發現、執行與錯誤。"
url: "https://www.zyx.tw/map/harness/mcp-on-the-wire"
---

# MCP 用 JSON-RPC 傳訊息：先取得工具定義，再轉送模型選定的操作

紀錄 047，深讀 L2，761 字，2 分鐘，v2.0.0，更新 2026-11-16

MCP 是連接外部工具的開放標準，訊息以 JSON-RPC 表達。client 先用 tools/list 取得工具定義，再用 tools/call 轉送模型選定的操作。

JSON-RPC 訊息分為請求、回應與通知。讀懂一次往返，要看誰送出請求，以及哪一則回應對應這個請求。

## 先分清誰連線、誰提供工具

host 是使用者操作的程式，例如 Claude Code。client 是 host 裡負責連線的元件，server 則是提供工具的程式。

harness 是模型外圍、負責工具執行的程式。Claude Code 就是一個 harness。

server 能提供工具、可讀取的資源與提示範本，分別稱為 tools、resources 與 prompts。本文追的是 tools，模型負責決定何時使用。

host 替每個 server 各開一個 client。下圖示範這些元件的位置，以及各個 client 與 server 的連線關係。

```text
╭────────────────── HOST (harness) ──────────────────╮
│  ╭──────────╮     ╭──────────╮     ╭──────────╮    │
│  │ CLIENT 1 │     │ CLIENT 2 │     │ CLIENT 3 │    │
│  ╰────┬─────╯     ╰────┬─────╯     ╰────┬─────╯    │
╰───────┼────────────────┼────────────────┼──────────╯
        │ stdio          │ stdio          │ HTTP
   ╭────┴─────╮     ╭────┴─────╮     ╭────┴─────╮
   │ SERVER   │     │ SERVER   │     │ SERVER   │
   │ files    │     │ database │     │ remote   │
   ╰──────────╯     ╰──────────╯     ╰──────────╯
```

Figure: A host holds one client per server. Local servers are reached over stdio and a remote server over HTTP.

1. Host: host 就是 harness。host 決定哪些 server 可以連線。
2. Client: 一個 client 只對一個 server。
3. Server: server 提供工具。server 讀不到完整對話，也看不到其他 server。
4. Transport: 本機的 server 用 stdio，遠端的 server 用 HTTP。

## 取得清單後，才有模型能選的工具

client 先送出 tools/list 請求，詢問 server 有哪些工具。以下是一次 tools/list 往返。

```
{"jsonrpc": "2.0", "id": 1,
 "method": "tools/list"}
```

server 在回應的 result.tools 放入工具定義。名稱、說明與參數格式各自的用途，見 工具呼叫的格式。

```
{"jsonrpc": "2.0", "id": 1,
 "result": {"tools": [{
   "name": "get_weather",
   "description": "Get the weather.",
   "inputSchema": {"type": "object"}}]}}
```

harness 收到清單後，把 server 回傳的內容轉成模型的工具定義。

## 模型選操作，client 負責轉送

工具呼叫 是模型提出工具名稱與參數，再由 harness 執行並送回結果的過程。在 MCP 這一段，client 把模型選定的操作轉成 tools/call 請求，送到 server。

server 執行後回傳結果，回應沿用該次請求的 id。

要觀察這個過程，可以用 MCP Inspector 連上一個 server。先查看 tools/list 的請求與回應，再查看 tools/call 的請求與回應。

下圖依訊息發生的順序，示範 client 列出工具、server 回傳定義、client 送出操作，以及 server 回傳結果的往返。

1. CLIENT: client 先問 server 有哪些工具。

```text
{"jsonrpc": "2.0", "id": 1,
 "method": "tools/list"}
```

2. SERVER: 每個工具有名稱、說明與參數格式。harness 轉成模型的工具定義。

```text
{"jsonrpc": "2.0", "id": 1,
 "result": {"tools": [{
   "name": "get_weather",
   "description": "Get the weather.",
   "inputSchema": {"type": "object"}}]}}
```

3. CLIENT: 模型選定工具後，client 送出 tools/call。

```text
{"jsonrpc": "2.0", "id": 2,
 "method": "tools/call",
 "params": {"name": "get_weather",
   "arguments": {"location": "New York"}}}
```

4. SERVER: 回應用相同的 id 對回請求。內容當成工具結果送回模型。

```text
{"jsonrpc": "2.0", "id": 2,
 "result": {"content": [
   {"type": "text", "text": "Sunny"}],
   "isError": false}}
```

Figure: Four JSON-RPC messages: the client lists the tools, the server answers with their schemas, the client calls one tool, and the server returns the result under the same id.

## 從訊息停在哪一步開始查

工具執行失敗時，server 回傳 isError 為 true 的結果，讓模型讀到。訊息格式錯誤則回傳 JSON-RPC 的 error，兩者要分開判讀。

## 本機訊息通道不能混入紀錄

使用 stdio，也就是標準輸入與輸出傳訊息時，host 會把 server 當成子程序啟動。訊息一行一則，host 寫進 server 的 stdin，再從 server 的 stdout 逐行讀回。

log 是程式執行時留下的紀錄。server 的 log 必須寫到 stderr，因為 stdout 只能出現 MCP 訊息。

## 來源

- [MCP specification 2026-07-28: Architecture](https://modelcontextprotocol.io/specification/2026-07-28/architecture), modelcontextprotocol.io
- [MCP specification 2026-07-28: Tools](https://modelcontextprotocol.io/specification/2026-07-28/server/tools), modelcontextprotocol.io
- [MCP specification 2026-07-28: stdio](https://modelcontextprotocol.io/specification/2026-07-28/basic/transports/stdio), modelcontextprotocol.io
- [MCP specification 2026-07-28: Streamable HTTP](https://modelcontextprotocol.io/specification/2026-07-28/basic/transports/streamable-http), modelcontextprotocol.io
- [MCP specification 2026-07-28: Discovery](https://modelcontextprotocol.io/specification/2026-07-28/server/discover), modelcontextprotocol.io
- [MCP specification 2025-11-25: Lifecycle](https://modelcontextprotocol.io/specification/2025-11-25/basic/lifecycle), modelcontextprotocol.io

## 地圖

- 先讀：[工具以名稱、說明與參數格式約定請求，再用同一個 id 對回結果](https://www.zyx.tw/map/harness/tool-calls.md)
- 先讀：[MCP 把服務操作包成 agent 能呼叫的工具](https://www.zyx.tw/map/basics/mcp-wraps-a-service.md)
- 相關：[先做最小的 harness，遇到問題再加零件](https://www.zyx.tw/map/harness/build-a-small-harness.md)
- 回到：[Harness](https://www.zyx.tw/map.md)
