MCP（Model Context Protocol）工具让 LLM 能够调用外部函数、Yao Process 或 API。**无需编写 Hook** —— LLM 会根据用户请求自动决定何时调用工具。
## 第一步：创建 MCP Server 定义
在 Assistant 目录下创建 `mcps/tools.mcp.yao`：
```json
{
"label": "My Tools",
"description": "Tools available to this agent",
"transport": "process",
"tools": {
"get_weather": "scripts.weather.Get",
"search_docs": "scripts.search.Query"
}
}
```
`transport: "process"` 类型将工具名直接映射到 Yao Process。LLM 调用 `get_weather`，Yao 执行 `scripts.weather.Get` 并返回结果。
## 第二步：在 `package.yao` 中注册
```json
{
"name": "My Assistant",
"connector": "$ENV.DEFAULT_CONNECTOR",
"mcp": {
"servers": [
{
"server_id": "agents.my-assistant.tools",
"tools": ["get_weather", "search_docs"]
}
]
}
}
```
`server_id` 格式为 `agents.<assistant-id>.<文件名去扩展名>`。只列出你希望 LLM 看到的工具。如果省略 `tools` 或为空，则该 server 的**所有工具**都会暴露。
## 传输类型
**`process`** —— 直接调用 Yao Process，适合访问内部数据。
```json
{
"transport": "process",
"tools": {
"save_entry": "agents.yao.keeper.store.MCPSave",
"search_entries": "agents.yao.keeper.store.MCPSearch"
}
}
```
**`stdio`** —— 启动本地 MCP Server 进程。
```json
{
"transport": "stdio",
"command": "python",
"arguments": ["mcp_server.py"],
"env": { "API_KEY": "$ENV.API_KEY" }
}
```
**`http`** —— 通过 HTTP 连接远程 MCP Server。
```json
{
"transport": "http",
"url": "https://mcp.example.com/api",
"authorization_token": "$ENV.MCP_TOKEN"
}
```
**`sse`** —— Server-Sent Events 流式传输。
```json
{
"transport": "sse",
"url": "https://mcp.example.com/events",
"authorization_token": "$ENV.MCP_TOKEN"
}
```
## `servers` 语法糖
`servers` 数组支持四种等价格式，按需选用。
**格式 1 —— 字符串**（暴露 Server 的全部工具）：
```json
{ "servers": ["agents.my-assistant.tools"] }
```
**格式 2 —— 标准对象**（明确列出工具，推荐，可读性最高）：
```json
{
"servers": [
{
"server_id": "agents.my-assistant.tools",
"tools": ["get_weather", "search_docs"]
}
]
}
```
**格式 3 —— `{ server_id: [tools] }`**（仅工具的简写）：
```json
{
"servers": [
{ "agents.my-assistant.tools": ["get_weather", "search_docs"] }
]
}
```
**格式 4 —— `{ server_id: { resources, tools } }`**（同时需要 resources 时使用）：
```json
{
"servers": [
{
"agents.my-assistant.tools": {
"tools": ["get_weather"],
"resources": ["data://reports"]
}
}
]
}
```
四种格式由同一个 `UnmarshalJSON` 解析，框架全部支持。真实项目（如 `keeper`、`expense`）普遍使用格式 2，可读性最好。
## 工具参数 Schema
对于 `process` 传输类型，可以添加输入/输出 Schema 帮助 LLM 正确调用工具。在 `mcps/mapping/` 下创建映射文件：
```
mcps/
├── tools.mcp.yao
└── mapping/
└── tools/
└── schemes/
├── search_docs.in.yao ← 输入 Schema
└── search_docs.out.yao ← 输出 Schema
```
输入 Schema（`search_docs.in.yao`）：
```json
{
"type": "object",
"properties": {
"query": { "type": "string", "description": "搜索关键词" },
"limit": { "type": "integer", "description": "最多返回条数", "default": 10 }
},
"required": ["query"]
}
```
## 测试
```bash
# LLM 会根据对话内容自动调用工具
yao agent test -n my-assistant -i "What's the weather in Tokyo?"
```
## 下一步
Agent 已有工具，LLM 会自动调用。下一页介绍 Hook —— 用于在执行前后进行精细控制。
→ **[Pure Hook](./pure-hook)**
