1. 从零跑通智能体原型MCP 与 Agent Skills 到底解决什么问题如果你刚开始接触大模型智能体开发大概率会遇到这样一个尴尬局面模型能聊天但一让它“去查数据库”“去读本地文件”“去调用某个接口”它就只会编。你给它写一堆提示词它还是不知道该先做什么、后做什么。MCP 和 Agent Skills 就是来解决这个问题的。MCPModel Context Protocol是一套标准化协议负责让智能体“够得着”外部工具和数据。你可以把它理解成 USB 接口不管外接的是键盘、鼠标还是硬盘插口形状统一系统就能识别。Agent Skills 则是“操作手册”它告诉模型在什么场景下该用哪个工具、按什么顺序用、注意哪些坑。两者结合才能让智能体从“能聊”变成“能干活”。这篇内容面向刚入门大模型智能体开发的读者目标很明确给你一份可复制的 MCP 服务端配置片段、一套 Agent Skills 目录结构以及本地启动、工具注册、调用验证的完整动作清单。你不需要先成为协议专家跟着步骤走就能在本地跑通一个可用的智能体原型。适合谁适合会一点 Python、想快速看到智能体跑起来效果、不想被概念绕晕的开发者。我试过把 MCP 和 Skills 拆开单独用结果要么工具连上了但模型不会用要么提示词写得很细但模型根本调不到工具。后来把两者按“连接层 知识层”组合起来整个流程才顺畅。下面按实际落地顺序展开。2. TaoToken 前置准备MCP 服务端接入大模型 API 的配置方法在跑通 MCP 之前你需要一个稳定的大模型 API 入口。TaoToken 提供兼容 OpenAI 风格的接口适合用来做智能体原型验证。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基础地址是 https://taotoken.net/api 。先拿到 API Key。进入控制台创建密钥路径是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentmcp_agent_skills_guideutm_campaignrewrite 密钥管理页在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentmcp_agent_skills_guideutm_campaignrewrite 。创建后复制保存后面配置里要用到。模型选择上智能体场景建议用支持工具调用function calling / tool use的模型。你可以在模型对话页先测试模型是否正常响应 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmcp_agent_skills_guideutm_campaignrewrite 。如果只是做长期编码或 Agent 任务可以了解 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentmcp_agent_skills_guideutm_campaignrewrite 。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentmcp_agent_skills_guideutm_campaignrewrite 里面写了 Base URL、鉴权方式和请求示例。Claude Code 相关接入参考 https://taotoken.net/ClaudeCodeAnthropic?utm_sourcetaotoken_aicg_blog_endutm_contentmcp_agent_skills_guideutm_campaignrewrite 。这里要强调一个关键点MCP 服务端本身不负责“思考”它只负责暴露工具。真正决定调用哪个工具的是大模型。所以你的 MCP 客户端需要把工具列表传给模型模型返回工具调用请求客户端再执行。TaoToken 的 API 在这里扮演的就是模型推理入口。配置时三个要素必须齐全Base URL、API Key、Model ID。缺一个都会导致 401 或模型找不到。下面给出可直接复制的配置片段。3. 可复制配置MCP 服务端 JSON 与 Agent Skills 目录结构先看 MCP 客户端配置。以常见的mcp.json或settings.json为例路径通常放在项目根目录或用户配置目录。下面是一份可复制的 JSON 片段把 TaoToken 作为模型提供方同时注册一个本地 MCP 服务端{ mcpServers: { local-tools: { command: python, args: [mcp_server.py], env: { TAOTOKEN_API_KEY: 你的API Key, TAOTOKEN_BASE_URL: https://taotoken.net/api, TAOTOKEN_MODEL: 你的Model ID } } }, llm: { provider: openai-compatible, base_url: https://taotoken.net/api, api_key: 你的API Key, model: 你的Model ID } }如果你用的是 TOML 格式比如某些 CLI 工具等价写法如下[llm] provider openai-compatible base_url https://taotoken.net/api api_key 你的API Key model 你的Model ID [mcp_servers.local-tools] command python args [mcp_server.py] [mcp_servers.local-tools.env] TAOTOKEN_API_KEY 你的API Key TAOTOKEN_BASE_URL https://taotoken.net/api TAOTOKEN_MODEL 你的Model ID再看 Agent Skills 目录结构。一个规范的 Skill 就是一个文件夹核心是SKILL.md附加脚本和参考文档按需放置skills/ └── db-query-assistant/ ├── SKILL.md ├── query_runner.py ├── schema_reference.md └── examples/ └── sample_queries.mdSKILL.md的 Frontmatter 必须包含name和description这是模型选择技能的唯一依据--- name: db-query-assistant description: 将自然语言问题转换为 SQL 查询并执行适用于员工信息、 薪资统计、部门分析等场景。当用户询问数据库相关问题时使用。 version: 1.0.0 allowed_tools: [run_sql, get_schema] --- # 数据库查询助手 ## 工作流程 1. 先调用 get_schema 获取表结构 2. 根据用户问题生成 SQL 3. 调用 run_sql 执行并返回结果 4. 对结果做简要解读 ## 注意事项 - 禁止执行 DELETE、DROP 等破坏性语句 - 查询前必须确认字段名存在MCP 服务端mcp_server.py的最小实现暴露两个工具from mcp.server import Server from mcp.server.stdio import stdio_server from mcp.types import Tool, TextContent app Server(local-tools) app.list_tools() async def list_tools(): return [ Tool( nameget_schema, description获取数据库表结构, inputSchema{type: object, properties: {}} ), Tool( namerun_sql, description执行只读 SQL 查询, inputSchema{ type: object, properties: {sql: {type: string}}, required: [sql] } ) ] app.call_tool() async def call_tool(name, arguments): if name get_schema: return [TextContent(typetext, textemployees(id, name, salary, dept))] if name run_sql: sql arguments[sql] if any(k in sql.upper() for k in [DELETE, DROP, UPDATE]): return [TextContent(typetext, text拒绝执行破坏性语句)] return [TextContent(typetext, textf模拟执行: {sql})] raise ValueError(f未知工具: {name}) async def main(): async with stdio_server() as (read, write): await app.run(read, write, app.create_initialization_options()) if __name__ __main__: import asyncio asyncio.run(main())这份配置里 Base URL、API Key、Model ID 三件套齐全MCP 服务端和 Skills 目录也对应上了。接下来启动验证。4. 本地启动与调用验证确认智能体真的调到了工具先安装依赖pip install mcp openai启动 MCP 服务端单独测试python mcp_server.py如果进程没有立刻退出、也没有报错说明 stdio 服务端在等待客户端连接。接着用客户端脚本发起一次完整调用。下面这段代码模拟“模型决定调用工具”的流程import asyncio from openai import OpenAI client OpenAI( base_urlhttps://taotoken.net/api, api_key你的API Key ) tools [ { type: function, function: { name: get_schema, description: 获取数据库表结构, parameters: {type: object, properties: {}} } }, { type: function, function: { name: run_sql, description: 执行只读 SQL 查询, parameters: { type: object, properties: {sql: {type: string}}, required: [sql] } } } ] response client.chat.completions.create( model你的Model ID, messages[{role: user, content: 帮我查一下 employees 表里薪资最高的前 5 个人}], toolstools, tool_choiceauto ) msg response.choices[0].message if msg.tool_calls: for call in msg.tool_calls: print(模型请求调用:, call.function.name) print(参数:, call.function.arguments) else: print(模型直接回复:, msg.content)实测下来如果配置正确你会看到类似输出模型请求调用: get_schema 参数: {}或者直接请求run_sql并带上 SQL 参数。这说明模型已经根据工具描述做出了选择。接下来把工具执行结果回传给模型让它生成最终回答messages [ {role: user, content: 帮我查一下 employees 表里薪资最高的前 5 个人}, msg ] for call in msg.tool_calls: result 模拟执行: SELECT * FROM employees ORDER BY salary DESC LIMIT 5 messages.append({ role: tool, tool_call_id: call.id, content: result }) final client.chat.completions.create( model你的Model ID, messagesmessages ) print(final.choices[0].message.content)到这一步一个最小可用的智能体原型就跑通了模型负责决策MCP 负责执行Skills 负责告诉模型流程和边界。你可以把SKILL.md的内容作为系统提示词注入观察模型是否按步骤先查 schema 再查数据。5. 常见报错排查401、local proxy failed、reading choices 怎么处理第一个高频报错是 401 Unauthorized。原因通常是 API Key 没填、填错或者 Base URL 写成了带路径的地址。检查base_url是否为https://taotoken.net/api不要多加/v1或斜杠。Key 是否复制完整、有没有多余空格。如果用的是环境变量确认变量名和代码里读取的一致。第二个是local proxy failed或连接被拒绝。这通常出现在 MCP 客户端启动服务端时。检查command和args是否能手动执行成功。比如python mcp_server.py在终端能跑但客户端里跑不起来多半是工作目录不对。把args改成绝对路径或者在配置里加cwd字段指定目录。另外确认 Python 环境里装了mcp包虚拟环境路径要和客户端使用的一致。第三个是reading choices相关报错比如KeyError: choices或返回结构里没有choices。这通常说明请求没有真正到达模型接口或者返回的是错误 JSON。先打印完整响应体print(response.model_dump_json(indent2))如果看到的是错误信息而不是choices多半是 Model ID 写错、账户额度不足或请求格式不对。确认model字段和 TaoToken 控制台里可用的模型名一致。工具调用场景下还要确认模型本身支持 function calling否则返回里不会有tool_calls。第四个是 OAuth 或鉴权头冲突。有些客户端会自动加Authorization头和你手动配置的 Key 冲突。检查配置里是否重复设置了鉴权信息保留一处即可。如果出现invalid api key但 Key 确认没错尝试重新生成一个 Key排除复制污染。第五个是工具注册后模型不调用。先确认tools数组确实传给了请求再确认工具description是否足够清晰。描述太模糊模型会忽略。把“查询数据”改成“执行只读 SQL 查询并返回结果”命中率会明显提升。6. 继续深入把原型扩展成可维护的智能体跑通最小原型后下一步是把 Skills 的渐进式披露用起来。初始只加载SKILL.md的 Frontmatter等模型判断相关再读全文。这样即使你装了十几个技能初始上下文也不会爆炸。具体做法是在系统提示词里只放技能名称和描述列表模型决定用哪个后再动态读取对应SKILL.md正文。MCP 工具列表也按需加载不要一次性把所有 schema 塞进去。如果你要做长期编码或 Agent 任务可以走 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentmcp_agent_skills_guideutm_campaignrewrite 。需要继续拿 Key 或管理额度去 API Keys 页面 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentmcp_agent_skills_guideutm_campaignrewrite 。接入细节查文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentmcp_agent_skills_guideutm_campaignrewrite 。想先验证模型对话效果用模型对话页 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmcp_agent_skills_guideutm_campaignrewrite 。最后给一个实用建议把每次工具调用的输入输出都打日志。智能体出问题时九成能在日志里找到是模型选错工具、参数格式不对还是服务端执行失败。日志比反复改提示词有效得多。