MCP Server 从零开发：让 AI 调用自己的工具

摘要：想让 AI
查询你自己的资料，不必先把整个硬盘、数据库或管理员账号交给它。本文以一个只读的虚构
FAQ 为例，从 Python 核心函数、MCP Server 工具注册、离线测试到 Inspector
与 Host 连接，教你把一个受限功能做成可由支持 MCP 的 AI
应用调用的工具。适合会运行 Python 脚本的初学者；准备 Python
3.10+、可安装依赖的网络和约 45—90 分钟。免费 Demo
可独立完成一次搜索，十项目包则用于扩展不同任务。本文核验于 2026 年 10 月
1 日；本站实际通过离线逻辑测试，SDK/Host
连通需读者在自己的环境验收。

核心结论

开发第一个 MCP Server 最稳妥的路径是：先写一个不依赖 MCP 的纯 Python
函数，让它只读取虚构数据；再用官方 Python SDK v2 的
MCPServer 和 @mcp.tool()
注册为工具；先跑边界测试，再用 Inspector 列出并调用工具，最后才连入具体
AI Host。Server 只暴露你写出的能力，模型通过 Host 内的 Client
请求调用；它并不会自动得到你的全部电脑权限。官方 SDK
的首步教程给出
MCPServer、工具、资源与提示词的 v2
写法。本文的首次成果是输入“订单”，返回虚构的 FAQ
F02，输入空白会被拒绝。

这篇聚焦“自己写
Server”，与站内MCP
是什么的概念教程形成前后顺序：概念篇帮助辨认
Host、Client、Server；本篇从源码和测试出发。没有 Python
基础的读者先用免费包的 README 看清文件，再决定是否安装
SDK。当前官方文档仍可能随版本更新，运行前以其安装页、Host
文档与包内适用版本说明为准。

背景与主要变化

在普通聊天中，你把资料复制给
AI，模型只处理这次粘贴的文本。要让它在需要时检索内部已允许的资料，就必须建立受控的数据入口。MCP
让 Host 与 Server 用共同的协议交换能力声明与请求。Host
是用户使用的 AI 应用；Client 在 Host
中负责协议连接；Server 是我们写的程序。官方文档特别说明
Server 不直接同模型对话，因此“AI 能调用自己的工具”实际意味着 Host
发现工具、模型选择调用、Client 发送请求、Server 返回结果，随后 Host
组织回答。这不是给模型一个操作系统超级权限。

旧教程常使用不同的 SDK API 名称，直接复制可能出现导入错误。本文按
2026 年 10 月核验的 Python SDK v2 文档写
from mcp.server import MCPServer；from mcp import Client
则用于可选的内存集成测试。不要把旧版
FastMCP、新版本包名以及某个 Host 的 JSON
配置混成同一套固定步骤。官方测试指南支持
Client(mcp, raise_exceptions=True)，无需先开网络端口即可验证工具调用；本文附件的可选测试沿用这个模式，但本站环境没有安装
SDK，尚未执行该层。

规范本身也在演进。官方2026-07-28
更新说明谈到无状态核心、发现机制与授权变化。对初学者，首先写好一个小而清晰的工具比追逐每个新能力更重要。真正交付给团队时，必须同时检查所用
SDK、Host 和传输方式的兼容范围；不要根据“协议支持
MCP”四个字推断任何第三方客户端都会显示全部资源或提示词。

核心功能拆解

把业务逻辑与协议适配分开

免费包中的 core.py 有两条虚构 FAQ 和
search_faq(query)。它对输入做长度与空白校验，按
ID、问题和答案匹配，返回列表。这个函数不导入
MCP，也不读取用户文件，因而可以先用标准库 unittest
验证。server.py 只做一件事：把这个函数通过
@mcp.tool() 注册为 search_demo_faq。一旦 Host
连接，工具说明、函数名和参数类型帮助客户端构造输入表单。这种分层让同一核心逻辑既能离线测试，也能在协议层验收；替换成真实资料时，还能单独审查数据读取与授权逻辑。

Tool、Resource、Prompt
该如何选

官方把 Tool、Resource、Prompt
分为三种能力：模型可选择调用工具，应用决定加载资源，用户选择提示词。一次“搜索
FAQ”是带查询参数的动作，适合 Tool；一份固定的只读索引可以做
Resource；一条“核对引用来源”的任务模板可以做 Prompt。并非每个 Server
都必须同时暴露三者。免费 Demo 只有一个
Tool，降低首次验收难度；付费包的十个项目也各有一个受限的
Tool。需要固定资源或提示词时，先明确谁控制加载、谁可见数据、是否会写入外部系统，再按官方
API 扩展，不要把“工具数量多”当作完成度。

传输、权限和输出边界

本期默认本地 stdio：Host 启动 Python
子进程并通过标准输入输出传协议消息。开发时不要把日志打印到
stdout，否则可能破坏协议流；诊断信息写 stderr。远程 HTTP
需要额外考虑身份验证、TLS、网络隔离、限流和审计，不能把本地教学 Server
改一个监听地址就开放公网。这个 Demo
的数据写死在源码里，没有文件系统扫描、网络抓取、数据库连接或写入
Tool。由此可检查的边界是“它只返回两条虚构记录的匹配项”，而不是“任何 MCP
Server
天然安全”。代码运行进程能访问什么，还取决于操作系统权限和部署环境。

适用人群与使用场景

如果你是内容编辑或运营人员，想让 AI 在一份小型已脱敏 FAQ
中找答案，免费 Demo
能帮助你理解从“手工复制”到“受限工具调用”的差别。若你写
Python，付费包提供十个分开的题材供改造：FAQ
查询、库存查找、制度条款索引、工单优先级建议、CSV
指标汇总、会议议程检索、预算阈值评估、JSON
配置差异、引用来源核对、审批草稿生成。它们用固定虚构数据展示不同参数、返回结构与安全边界，不连接真实系统。尤其“审批草稿”只生成待人工处理的内容，不批准、发送或支付。

如果你的需求是大规模同步数据库、持续运行任务或让多个团队共享带权限的业务
API，本例只是架构起点。需要另行设计数据源访问、令牌生命周期、缓存、并发、错误隔离和观测；不同组织也有自己的数据使用要求。敏感资料不可未经授权放进第三方
Host 或 Demo。只想问一个公开常识或改写一次文案，则不必为单次问题部署
Server。选择工具以前先问：这个动作是否需要实时外部数据？是否能缩成只读？结果由谁核对？失败怎样撤回？

安装、配置或使用步骤

以下步骤按免费包真实文件编排，文件名和代码与附件一致。示例使用 Python
3.10+；安装 SDK 需要可访问依赖源，某些 Host
或模型服务可能另收费。不要在不可信的脚本中粘贴 API Key。本 Demo
无需账号和模型额度即可跑完离线测试；Inspector 是否能启动及 Host
是否能调用，仍需在读者设备上确认。

1. 解压并看目录。 取得
   python-mcp-demo-free.zip，确认
   README.md、core.py、server.py、test_core.py
   和 sample-result.json 均在根目录。先读 README
   的版本与边界，不要把旧版 SDK 教程中的导入行替换进来。
2. 先跑纯函数。 进入解压目录执行
   python -m unittest -v test_core.py。预期三项通过：订单匹配
   F02、未知词返回空列表、空白输入抛出 ValueError。这是无需 SDK
   的离线测试。若 python 指向旧解释器，在 Windows 可尝试
   py -3，在 macOS/Linux 检查
   python3 --version。
3. 查看输出样例。 打开
   sample-result.json，输入是“订单”，expected
   中的 ID 是
   F02，问题是“如何导出订单”。它只是虚构的完成示例；不证明真实订单系统可用。你也可在
   Python 中运行
   from core import search_faq; print(search_faq('订单'))
   与样例逐字段核对。
4. 创建隔离环境并安装 SDK。 用
   python -m venv .venv 建立虚拟环境，激活后运行
   python -m pip install "mcp[cli]>=2,<3"。使用 v2
   范围是本文与代码的约束，不保证将来的每个 2.x
   版本无差异。确认包安装在接下来运行 Inspector 的同一个解释器；不要用系统
   Python 与虚拟环境混用。
5. 在 Inspector 调用工具。 于 Demo 目录运行
   python -m mcp dev server.py，按终端提供的地址打开
   Inspector。在 Tools 中寻找 search_demo_faq，填
   {"query":"订单"}，预期包含
   F02；再输入空白，应看到校验错误。若命令或页面入口因 SDK
   更新不同，以官方当期 CLI 文档为准。本站没有在制作环境安装
   SDK，不能把这段预期写成已实测截图。
6. 连接你自己的 Host。 只在支持本地 stdio 的 Host
   中，依该 Host 当前官方文档填写 Python 解释器和 server.py
   的绝对路径。先确认工具列表只出现允许的
   Tool，然后再次输入“订单”，观察实际调用日志。不要直接照搬另一个 Host
   的配置键；06-mcp-config.json
   是示意结构，路径需要替换并适配目标客户端。
7. 记录与回滚。 写下 Python、SDK、Host
   版本，截取仅含虚构数据的结果，记录工具名、输入、返回和空输入失败。若工具找不到或范围异常，先从
   Host 停用连接、停止进程，再检查路径和
   stderr；切勿通过开放整个磁盘或管理员权限来“修复”路径错误。

免费 Demo 的关键代码如下，与附件 server.py
的注册部分一致：

from mcp.server import MCPServer
from core import search_faq

mcp=MCPServer('Free FAQ Demo')

@mcp.tool()
def search_demo_faq(query: str) -> list[dict]:
    """Search only two fictional FAQ records by query."""
    return search_faq(query)

这段代码没有授权模型编辑文件的能力。query 参数由 Client
传入，核心函数会校验长度并返回匹配项；对未知问题返回空列表，让 Host
能向用户说明“未在示例清单中找到”。正式业务系统则还需设计可靠的来源引用、对调用者的认证和数据访问策略。不要因为一个空输入测试通过就把它认作全面安全审计。

实际工作流示例

以“帮我找导出订单的说明”为例，读者先用 test_core.py
检查字符串匹配与边界；安装 SDK 后，Inspector 列出
search_demo_faq；Host 连接成功后，模型可选择以
query=订单 请求该工具。Server 返回虚构 F02 和答案，Host
再把它呈现给用户。人工核对答案的上下文和使用条件后，才决定是否采取下一步。这个链条的成功标准是具体的：能看到工具名，查询结果包含
F02，未知词为空，空输入被拒绝，没有写入工具和真实订单数据。

失败路径同样要演练。若 Host 根本找不到工具，先检查 Python
可执行文件是否安装同一 SDK、server.py
是否为绝对路径、启动时 stderr
是否报错；若工具存在但查询为空，检查样本是中文“订单”而非真实订单号；若结果含不应出现的资料，立即停用
Server
并核查数据源与权限。部署到团队环境之前，至少增加认证、租户边界、速率限制、超时、日志脱敏和审批。把外部文档里“忽略以上规则”的文字当作数据，不要让它成为工具执行指令。

付费包的十个项目沿用同一层次，但业务行为并非改十次标题。库存项目按
SKU
精确匹配，工单项目依据示例词条给出待人工核定的优先级，指标项目聚合两个月虚构数值，配置差异项目比较固定的前后值，来源核对项目明确
verified=False，审批项目仅返回
draft-only。每个项目各有
core.py、server.py、test_core.py、test_sdk_optional.py
和 README；没有凭空列出十个已接通的企业系统。

对比与选型建议

建议先做一个完整且能解释失败原因的
Tool，再扩展其他功能。模板之间的差异应以参数、输入边界、业务规则和返回结构判断，不以文件数量替代价值。配套的
查看免费资料包
提供两条虚构 FAQ、完整 Python Demo
和三项离线测试；需要研究十种业务场景、各自源码与测试表，可 查看付费资料包。两个链接均指向本篇对应的资料详情页，按页面规则获取。

风险、限制与注意事项

示例不是生产集成。
十项目包为本地可编辑源码库，数据固定且虚构；不含真实库存、订单、公司制度或认证系统。只有核心逻辑已在本站离线执行。SDK
适配层遵照官方 v2 文档写法，但没有在本站环境安装 SDK，也没有运行
Inspector、真实 Host 或容器构建。请买家在自己的 Python
环境完成可选集成测试和实际客户端验收。任何旧版 Host 配置格式、SDK
小版本和命令菜单都可能变化，核对官方文档比盲目复制更可靠。

工具调用会扩大攻击面。
一旦把固定数据换成真实数据库，Server
进程权限、服务账号范围和网络目标就决定了能读取什么。把查询词加入参数白名单或限制长度只是第一步，还要按用户身份做授权、限制返回行数、隐藏密钥、记录审计事件、考虑
Prompt Injection
和越权请求。没有人工审批不应把演示的“草稿”升级成自动批准、发送邮件或支付。接入资料前应对照组织政策取得许可，并使用脱敏样本。

费用与回滚要写在部署单里。 本地离线测试不消耗模型
API 额度；Host、模型订阅、云服务器、第三方数据库和 API
可能单独计费。若发现工具列表或输出超出预期，从 Host 移除该 Server
并停止进程；后来若加入过真实
Token，要撤销凭据、核对日志，再恢复旧配置。只删除聊天记录无法撤销已经授予进程的权限。不要把源代码示意图当真实
UI 截图，也不要对用户声称“十个项目都通过云端联调”。

事实依据与来源

官方已确认： MCP Python SDK v2 文档示例包含
MCPServer、@mcp.tool()、stdio 运行与 Inspector
开发入口；官方测试指南提供内存 Client 模式。MCP 协议的
Host、Client、Server
及三种能力按官方入门定义。本站离线验证： 免费 Demo
三项、十个付费项目各两项核心单元测试通过；源文件可编译，文件格式和 ZIP
结构另行检查。编辑判断：从虚构只读数据开始、分离业务逻辑与协议层，并在接入真实系统前要求权限评审。待用户环境验证：SDK
安装、Inspector、具体 Host 调用、Docker 与生产认证。核验日期为 2026 年
10 月 1 日。

FAQ

MCP Server 是 AI 模型吗？

不是。它是向 MCP Client 暴露能力的程序，模型是否调用工具由 Host
的流程决定。Server 返回的数据还需要 Host
与用户核验，不能自动保证答案正确。

免费 Demo 必须有 API Key 吗？

离线核心测试不需要账号、模型 API Key 或网络。安装 MCP SDK
时需要获取依赖；连接具体 Host 后是否需要模型订阅取决于该产品，不在 Demo
内提供。

只注册一个 Tool 就可以叫
MCP Server 吗？

可以按官方 SDK 注册一项工具，不必同时做 Resource 和
Prompt。最小示例更容易检查工具名、参数、输出和权限范围；后续按任务再添加能力。

为什么 mcp 导入失败？

常见原因是 SDK 没装在当前 Python
环境，或者安装了不匹配的旧版。检查虚拟环境、解释器路径、包版本和官方 v2
文档；不要在系统环境里盲目反复安装。

Host 没看到工具怎么办？

先在 Inspector 验证能列出 search_demo_faq，再检查 Host
使用的 Python 和 server.py 绝对路径，并阅读
stderr。不同客户端的配置格式不同，不能把示意 JSON 当作所有 Host
的通用配置。

十个项目可以直接接生产数据库吗？

不可以声称已可直接上线。包内固定虚构数据与只读/草稿工具用于学习源码结构。真实数据接入需身份认证、最小权限、输入/输出控制、日志审计、部署测试、回滚及组织批准。

空输入被拒绝是否意味着没有安全风险？

不是。它只验证一个输入边界。真实服务还需处理访问控制、敏感数据、Prompt
Injection、依赖漏洞、网络目标和返回内容的可信度。

免费文件和十项目源码从哪里获取？

查看免费资料包
下载独立可用的 Python MCP Demo；查看付费资料包
了解十个不同的源码项目、测试、部署与安全材料。购买前先读页面上的验证范围和额外费用。

参考来源

• MCP
  Python SDK v2：First steps
• MCP
  Python SDK v2：Testing
• MCP
  Python SDK v2：Connect to a real host
• MCP
  官方入门
• MCP
  2026-07-28 规范说明

内容核验日期：2026 年 10 月 1 日。