1. 从零写一个 MCP 服务端为什么总卡在“验证”这一步MCP 服务端开发这件事写代码本身其实不难难的是写完以后怎么确认它真的能被客户端正确调用。我见过太多人把 Resource、Prompt、Tool 三类接口都定义好了结果一接客户端就报错回头查半天发现是传输协议选错了或者工具函数的参数类型没对上。这篇是 MCP 系列第三篇聚焦的是服务端从编码到功能验证的完整链路。核心检索词就三个MCP、服务端、功能验证。适合谁看已经了解 MCP 基本概念、想动手写一个能跑通的服务端、并且希望有一套可复制的验证流程的开发者。如果你还没接触过 MCP建议先补一下前两篇的基础概念。整篇的接入点统一走 TaoToken 的 Key/API 通道这样你不需要在多个模型供应商之间来回切换配置一个 Key 就能把服务端调用的模型能力接上。下面我会先讲清楚三类服务原语的定位差异再给出一份完整的服务端代码最后用三步验证动作把功能跑通。每一步都有可复制的配置和命令跟着做就行。2. TaoToken 前置把 Key 和 API 通道准备好在写服务端之前先把模型调用的通道打通。TaoToken 在这里扮演的角色是统一的 Key 管理和 API 入口你不需要为每个模型单独申请账号一个 Key 就能覆盖后续的调用需求。2.1 获取 API Key打开控制台页面进入 API Keys 管理区域创建一个新的 Key。创建时建议给 Key 起一个能区分用途的名字比如mcp-server-dev方便后续排查问题时定位。创建完成后把 Key 复制出来注意这个 Key 只在创建时完整显示一次关掉页面就看不到了。如果你需要更细的权限控制可以在创建时选择对应的权限范围。注意Key 不要直接硬编码在代码里提交到仓库建议用环境变量或者本地配置文件管理。2.2 确认 API 接入地址TaoToken 的 API 接入地址是https://taotoken.net/api这个地址在后续配置settings.json时会用到。它兼容标准的接口调用格式所以你在 Cline 或者其他支持自定义 API 地址的工具里直接把 Base URL 填成这个就行。如果你需要查看完整的接入文档和参数说明可以访问接入文档页面里面有详细的请求格式和返回结构说明。2.3 在 Cline 中配置 settings.json 骨架Cline 的配置核心在settings.json文件里。下面这份骨架你可以直接复制把apiKey替换成你刚才创建的那个 Key{ mcpServers: { taotoken-mcp-server: { command: python, args: [server.py], env: { TAOTOKEN_API_KEY: sk-你的Key, TAOTOKEN_BASE_URL: https://taotoken.net/api } } } }这份配置做了三件事声明了一个名为taotoken-mcp-server的服务端、指定了启动命令和入口文件、通过环境变量把 Key 和 Base URL 传进去。服务端代码里读取这两个环境变量就能完成模型调用通道的初始化。如果你用的是 SSE 传输协议而不是 stdio配置结构会略有不同需要额外指定url字段。这个在后面验证环节会具体说。3. 可复制配置服务端三类原语的完整实现MCP 服务端对外提供三类服务Resource、Prompt、Tool。这三者的定位差异很大写代码之前先搞清楚各自适合什么场景能少走很多弯路。3.1 三类原语的定位对照特性ResourceToolPrompt主要功能提供数据执行操作定义模板操作类型只读读写模板定义状态修改否是否缓存支持是否是典型用途数据获取功能执行交互指导Resource 类似 REST 的 GET只读、可缓存适合暴露数据库查询、文件读取这类操作。Tool 类似 POST/PUT会改变状态或触发计算适合数学运算、API 调用。Prompt 则是可复用的提示模板用来标准化和 LLM 的交互方式。3.2 项目初始化与依赖安装用 uv 来管理项目它比 pip 快很多依赖解析也更可靠。先安装 uv# Windows PowerShell powershell -ExecutionPolicy ByPass -c irm https://astral.sh/uv/install.ps1 | iex # 或者用 pip pip install uv然后创建项目并安装依赖uv init mcp_learning cd mcp_learning uv venv # Windows 激活虚拟环境 .venv\Scripts\activate # macOS/Linux source .venv/bin/activate uv add mcp[cli] httpx uv add psycopg2mcp[cli]提供了服务端开发的核心类和命令行工具psycopg2用来连接 PostgreSQL 数据库。3.3 服务端实例与 Resource 实现创建服务端实例时几个关键参数需要留意from mcp.server.fastmcp import FastMCP import psycopg2 import json from psycopg2.extras import RealDictCursor from mcp.server.fastmcp.prompts import base mcp FastMCP( MCP Test Server, debugTrue, host0.0.0.0, port8002 )debugTrue会输出详细日志调试阶段很有用。host0.0.0.0允许远程连接开发环境方便但生产环境要收紧访问控制。port8002是客户端连接时用的端口。Resource 部分先定义一个测试资源再实现数据库查询DB_CONFIG { dbname: your_db, user: your_user, password: your_password, host: 127.0.0.1, port: 5432 } def get_db_connection(): return psycopg2.connect(**DB_CONFIG) mcp.resource(test://hello) def hello() - str: 简单的测试资源 return Hello, World! mcp.resource(db://tables) def list_tables() - str: 获取所有表名列表 with get_db_connection() as conn: with conn.cursor() as cur: cur.execute( SELECT table_name FROM information_schema.tables WHERE table_schema public ) tables [row[0] for row in cur.fetchall()] return json.dumps(tables)表数据查询资源支持传入表名和 limit 参数用参数化查询防止注入mcp.resource(db://tables/{table_name}/data/{limit}) def get_table_data(table_name: str, limit: int 100) - str: 获取指定表的数据 try: with get_db_connection() as conn: with conn.cursor(cursor_factoryRealDictCursor) as cur: cur.execute( SELECT * FROM %s LIMIT %s, (psycopg2.extensions.AsIs(table_name), limit) ) rows cur.fetchall() return json.dumps(list(rows), defaultstr, ensure_asciiFalse) except Exception as e: return json.dumps({status: error, message: str(e)})3.4 Prompt 与 Tool 实现Prompt 定义了两个模板一个是省份介绍一个是代码调试的多轮对话模板mcp.prompt() def introduce_china_province(province: str) - str: 介绍中国省份 return f 请介绍这个省份{province} 要求介绍以下内容 1. 历史沿革 2. 人文地理、风俗习惯 3. 经济发展状况 4. 旅游建议 mcp.prompt() def debug_code(code: str, error_message: str) - list[base.Message]: 调试代码的对话式提示模板 return [ base.SystemMessage(你是一位专业的代码调试助手。请仔细分析用户提供的代码和错误信息找出问题所在并提供修复方案。), base.UserMessage(我的代码有问题请帮我修复), base.UserMessage(f\n{code}\n), base.UserMessage(f错误信息\n{error_message}), base.AssistantMessage(我会帮你分析这段代码和错误信息。首先让我理解问题所在...), ]Tool 部分实现四个数学运算注意除法的零值检查mcp.tool() def add(a: float, b: float) - float: 加法运算 return a b mcp.tool() def subtract(a: float, b: float) - float: 减法运算 return a - b mcp.tool() def multiply(a: float, b: float) - float: 乘法运算 return a * b mcp.tool() def divide(a: float, b: float) - float: 除法运算 if b 0: raise ValueError(除数不能为零) return a / b最后是入口用 SSE 协议启动if __name__ __main__: mcp.run(sse)stdio 协议适合本地调试SSE 适合需要网络访问的场景。验证阶段用哪个都行但要注意配置里的传输方式要和启动方式一致。4. 三步验证启动服务端、发起调用、核对结果代码写完了接下来是这篇的重点——功能验证。用 MCP Inspector 这个官方调试工具三步就能确认服务端是否正常工作。4.1 第一步启动服务端先确认mcp命令可用mcp --help输出里能看到dev命令它就是用来启动 Inspector 的。运行mcp dev server.py如果服务端依赖数据库连接确保数据库已经启动并且配置正确。命令执行后会输出一个本地访问链接点开就能进入 Inspector 界面。4.2 第二步发起工具调用进入 Inspector 页面后先点左侧的 Connect 按钮建立连接。连接成功后顶部会出现 Resources、Prompts、Tools 三个标签页。验证 Resource点 Resources再点 List Resources能看到test://hello和db://tables等资源。点db://tables后右侧会显示返回的表名列表。如果数据库里有两张表这里应该返回对应的 JSON 数组。验证 Prompt点 Prompts 下的 List Prompts选择introduce_china_province输入参数比如“广东省”点 Get Prompt右侧会按模板生成完整的提示文本。验证 Tool点 Tools 下的 List Tools选择add输入a3、b5点 Run Tools返回结果应该是8。再试一下divide输入b0应该返回除数不能为零的错误信息。4.3 第三步核对返回结果核对结果时重点看三个地方返回的数据结构是否符合预期、参数是否正确传递、错误处理是否生效。Resource 返回的应该是合法的 JSON 字符串中文不乱码。Prompt 返回的应该是完整的模板文本参数被正确替换。Tool 返回的应该是计算结果异常情况返回明确的错误信息。如果某一步返回空或者报错先看服务端终端的日志输出debugTrue模式下会有详细的调用记录。常见的问题是参数类型不匹配比如把字符串传给了期望 float 的参数。5. 本篇常见错排查验证过程中最容易踩的几个坑我整理成对照表现象可能原因排查动作Inspector 连不上传输协议不一致确认mcp.run()的参数和配置里的传输方式一致Resource 返回空数据库连接失败检查 DB_CONFIG 的 host/port/密码确认数据库可访问Tool 调用报参数错误类型不匹配检查函数签名里的类型注解float 参数不要传字符串Prompt 参数没替换参数名写错确认调用时传的参数名和函数定义一致中文返回乱码编码未指定json.dumps 加ensure_asciiFalse端口被占用8002 已被使用换一个端口或关掉占用进程还有一个容易忽略的点host0.0.0.0在开发环境方便但如果你的机器有公网 IP这个设置会让服务端暴露在公网。验证阶段建议改成127.0.0.1确认功能正常后再按需调整。如果排查过程中需要确认模型调用通道是否正常可以到模型对话页面发一条测试消息确认 Key 和 API 地址配置无误。接入相关的细节问题接入文档里有完整的参数说明和示例。6. 把验证流程固化下来服务端开发最怕的不是写代码而是写完不知道对不对。这套三步验证流程——启动、调用、核对——可以固化成你每次改完代码后的标准动作。Resource 验证数据读取、Prompt 验证模板生成、Tool 验证功能执行三类原语各测一遍基本能覆盖大部分问题。如果你后续要把这个服务端接到长期运行的编码任务或者 Agent 流程里可以考虑用 Coding Plan 来管理调用配额和通道避免开发调试阶段把额度用超。验证通过之后把debug关掉、host收紧再部署到实际环境这样从开发到上线的链路就完整了。