1. 为什么要在 VSCode 里折腾 MCP AI Agent如果你最近在 VSCode 里写 Python又想让自己搭的 Agent 真正“动手干活”那 MCP 这个词大概率已经刷到过好几次了。MCP 全称 Model Context Protocol简单说就是给大模型装了一个标准化的“工具插座”模型不再只能聊天而是能通过统一协议去读文件、查文档、调接口。AI Agent 则是那个拿着插座去干活的执行者它负责判断“现在该用哪个工具、传什么参数”。这套组合最适合谁我的判断是三类人一是想从零理解 Agent 工具调用链路的学生和转行者二是需要在 VSCode 里快速验证一个自动化流程的后端或算法同学三是手里有多个模型 Key、被不同平台的 Base URL 和鉴权方式搞得头大的开发者。前两类人卡在“概念懂了但跑不起来”第三类人卡在“每个工具都要配一遍 Key”。这篇就聚焦一个最小可跑闭环在 VSCode 里用 Python 写一个 MCP Server再用 Smolagents 写一个 Agent 去调用它同时把模型调用统一收敛到 TaoToken 的 Key 和 API 通道。你跟着做完能亲眼看到 Agent 自己决定调用工具、拿到结果、再组织成回答。整个过程不需要你有多深的框架经验但需要你愿意动手敲命令。我试过把模型配置散落在 Cline、Smolagents、脚本里各写一份改一次 Key 要翻三个文件后来统一到一个 Base URL 之后清爽很多。下面从环境准备开始一步步来。2. TaoToken 前置准备统一 Key 与 Base URL 配置在写 Agent 之前先把模型通道这件事定下来。Smolagents 里的OpenAIServerModel需要一个 OpenAI 兼容的api_base、api_key和model_id。如果你每个项目都去不同平台申请 Key后面调试报错时很难判断是工具问题还是鉴权问题。TaoToken 在这里的角色就是提供统一的 Key 和 API 通道让 VSCode 里的 Cline、Smolagents 脚本共用同一套配置。先拿到 Key。打开 https://taotoken.net/api-keys 登录后创建一个 API Key复制出来形如sk-开头的一串。这个 Key 只显示一次建议先存到本地的环境变量里别直接硬编码进要提交的代码。接着确认 Base URL。TaoToken 的 API 入口是https://taotoken.net/api在 OpenAI 兼容模式下api_base一般填https://taotoken.net/api/v1。注意这里不要带 UTM 参数保持干净。模型 ID 按你实际要用的填比如gpt-4o-mini、claude-3-5-sonnet这类具体以控制台模型列表为准。我建议在项目根目录建一个.env文件把三个值写进去TAOTOKEN_API_KEYsk-你的Key TAOTOKEN_BASE_URLhttps://taotoken.net/api/v1 TAOTOKEN_MODEL_IDgpt-4o-mini然后在 Python 里用os.getenv读取。这样做的好处是后面 Cline 的 MCP 配置、Smolagents 的模型初始化都能引用同一份来源改 Key 只改一处。如果你还没建 Key先去 https://taotoken.net/api-keys 建一个再回来继续。有一点要提醒不要把 Key 写进settings.json然后提交到 Git。VSCode 的配置文件经常被同步Key 泄露的风险比你想的高。用环境变量或者本地不提交的.env更稳妥。3. 可复制配置MCP Server 与 Smolagents 接入片段这一节给你可以直接复制的配置和代码。先做 MCP Server再做 Agent 调用最后把 VSCode 里的 Cline 也接上方便你肉眼验证工具是否被调用。3.1 初始化项目与依赖在 VSCode 里打开终端切到你放项目的目录执行uv init mcp-agent-demo cd mcp-agent-demo uv venv .venv\Scripts\activate uv add mcp[cli] smolagents[mcp,openai] duckduckgo-search beautifulsoup4 requests python-dotenvWindows 下激活虚拟环境用.venv\Scripts\activatemacOS 或 Linux 用source .venv/bin/activate。装完后uv -v和uvx -v能输出版本号就说明 uv 正常。3.2 写一个最小 MCP Server新建main.py这段代码提供一个get_docs工具能按框架名去搜索对应文档站点from mcp.server.fastmcp import FastMCP from duckduckgo_search import DDGS from bs4 import BeautifulSoup import requests mcp FastMCP(docs) USER_AGENT Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 docs_urls { smolagents: huggingface.co/docs/smolagents/index, llamaindex: docs.llamaindex.ai/en/stable, } async def search_web(query: str): try: ddgs DDGS() return list(ddgs.text(query, max_results3)) except Exception as e: print(fSearch failed: {e}) return None async def fetch_url(url: str): try: resp requests.get(url, headers{User-Agent: USER_AGENT}, timeout30) return BeautifulSoup(resp.text, html.parser).get_text() except Exception as e: print(fFetch failed: {e}) return None mcp.tool() async def get_docs(query: str, framework: str): Search the docs of a specified framework for a given query. if framework not in docs_urls: return fFramework {framework} not supported results await search_web(f{query} site:{docs_urls[framework]}) if not results: return No results found text for r in results: text await fetch_url(r[href]) return text if __name__ __main__: mcp.run(transportstdio)transportstdio表示这个 Server 通过标准输入输出和客户端通信适合本地进程调用。3.3 VSCode 里 Cline 的 MCP 配置在 VSCode 安装 Cline 插件后打开它的 MCP 配置文件加入下面这段 JSON。注意把--directory后面的路径换成你自己的项目绝对路径{ mcpServers: { get-docs: { command: uv, args: [ --directory, D:/projects/mcp-agent-demo, run, main.py ] } } }保存后 Cline 面板里会出现get-docs这个 Server状态变绿说明启动成功。这一步是肉眼验证 MCP Server 能不能被客户端拉起来比直接上 Agent 更容易定位问题。3.4 Smolagents 调用 MCP Server新建my_agent.py把模型通道指向 TaoTokenimport os from dotenv import load_dotenv from smolagents import ToolCollection, CodeAgent, OpenAIServerModel from mcp import StdioServerParameters load_dotenv() model OpenAIServerModel( api_baseos.getenv(TAOTOKEN_BASE_URL), api_keyos.getenv(TAOTOKEN_API_KEY), model_idos.getenv(TAOTOKEN_MODEL_ID), ) server_params StdioServerParameters( commanduv, args[--directory, D:/projects/mcp-agent-demo, run, main.py], ) with ToolCollection.from_mcp(server_params) as tool_collection: agent CodeAgent( modelmodel, tools[*tool_collection.tools], add_base_toolsTrue, ) result agent.run(Search docs for how to implement multi-agents with smolagents) print(result)这里三件套齐了Base URL 是TAOTOKEN_BASE_URLKey 是TAOTOKEN_API_KEYModel ID 是TAOTOKEN_MODEL_ID。路径同样换成你自己的。4. 验证请求从本地工具调用到 Agent 响应配置写完最关键的是确认链路真的通了而不是“看起来没报错”。分两步验证先单独验证 MCP Server再验证 Agent 端到端。4.1 用 MCP Inspector 单独测工具MCP 官方提供了一个可视化调试工具。确保本机有 Node.js 和 npm然后在项目目录执行npx modelcontextprotocol/inspector uv run main.py终端会输出一个本地地址通常是http://localhost:5173。浏览器打开后在工具列表里能看到get_docs填入参数{query: multi agents, framework: smolagents}点执行如果返回一段文档文本说明 MCP Server 本身没问题。这一步把“工具能不能跑”和“模型能不能调工具”解耦了排错时非常有用。4.2 跑 Agent 端到端回到终端运行python my_agent.py正常情况下你会看到 Smolagents 打印出推理步骤它先分析任务决定调用get_docs传入query和framework拿到返回文本后再组织成最终回答。日志里会出现类似Calling tool: get_docs的行。如果模型通道配置正确最终会打印出一段关于 smolagents 多 Agent 实现的说明。到这里从 VSCode 里的 Python 脚本到 MCP Server 的本地工具再到 TaoToken 的模型通道整条链路就跑通了。想更直观地看模型对话效果可以打开 https://taotoken.net/models 对比不同模型在同一任务下的表现再决定生产环境用哪个 Model ID。5. 本篇常见报错排查链路跑不通时报错信息往往指向不同层。下面按真实遇到的错误对照排查。401 Unauthorized最常见。检查TAOTOKEN_API_KEY是否读到了.env是否被load_dotenv()正确加载。如果 Key 前后有空格或引号也会 401。另外确认api_base是https://taotoken.net/api/v1少写/v1有时会走到错误的路由。local proxy failed / connection refused这类通常出现在 MCP Server 启动阶段。检查--directory路径是否存在、main.py文件名是否写对、虚拟环境里是否装了mcp[cli]。路径里有中文或空格时JSON 配置里要用正斜杠或双反斜杠。Error reading choices / choices 字段为空说明请求发出去了但返回结构不符合 OpenAI 兼容格式。先确认 Model ID 在 TaoToken 控制台里是可用状态再确认没有把api_base写成带 UTM 的地址。模型名写错时有些网关会返回空 choices 而不是明确报错。OAuth / authentication 相关提示如果你在 Cline 里同时配了别的模型提供商可能出现鉴权串扰。把 Cline 的模型配置也统一指向 TaoToken 的 Base URL 和 Key避免两套鉴权混用。ToolCollection.from_mcp 卡住不返回多半是 MCP Server 进程没起来。先在终端手动执行uv run main.py看是否有导入错误。duckduckgo-search和beautifulsoup4没装全时Server 会在导入阶段就挂掉。Agent 不调用工具直接编答案检查add_base_toolsTrue是否让模型倾向于用内置工具可以试着设为False强制它走 MCP 工具。另外任务描述里明确写出“search docs”这类动词能提高工具调用命中率。排障时建议按“MCP Server 单独测 → Agent 模型通道单独测 → 端到端”的顺序一次只改一个变量。接入文档在 https://taotoken.net/doc 里面有各语言的调用示例对照着看能省不少时间。6. 把这条链路用起来统一 Key 与后续扩展跑通最小闭环之后真正省心的地方在于 Key 统一。你可以在 Cline 里用 TaoToken 的 Key 做日常问答和 MCP 工具调用在 Smolagents 脚本里用同一个 Key 跑批量任务甚至后面接 Codex 的auth.json时也复用同一套 Base URL 和 Model ID。改一次配置所有入口同步生效不用再逐个平台对账。如果你打算把 Agent 用在长期编码或自动化流程上可以了解下 Coding Planhttps://taotoken.net/coding-plan 它更适合高频、持续的 Agent 调用场景。日常验证模型能力用模型对话页https://taotoken.net/models 快速切换对比就够了。下一步可以尝试的方向把get_docs换成读本地项目文件的工具让 Agent 帮你检索代码库或者再起一个 MCP Server 查数据库用ToolCollection组合两个工具集让 Agent 自己决定调哪个。多 Server 协同的写法和单 Server 几乎一样只是把多个StdioServerParameters分别包进ToolCollection.from_mcp再把 tools 合并成一个列表传给CodeAgent。最后留一个实用习惯每次改完 MCP 配置先用 Inspector 跑一遍工具再跑 Agent。这个顺序能帮你把大部分问题挡在模型调用之前省下反复调 Key 的时间。