14:00 痛点先摆在台面上Claude 只能读写文件连个数据库都查不了这怎么当生产力工具我下午被这事儿卡了快二十分钟。想让 Claude 帮我跑一段用户留存分析数据在远端结果它一句我没有数据库访问能力把我噎回来。Bash 倒是能跑 psql可那不叫 Agent那叫让我自己写脚本再让它执行。翻了翻《Claude Code 实战Harness 工程之道》第 6 章作者把这事说得很透Claude 本身只有 Read/Bash/Edit 这类基础工具外部系统全靠 MCPModel Context Protocol扩展。MCP 是个客户端-服务器协议——Claude 当客户端你写的或者别人写好的服务当服务器中间走 stdio 或 HTTP。书里管这叫把 M×N 问题压成 MNM 个模型接 N 个工具原本要 M×N 个适配现在大家遵守同一协议模型方写 M 个客户端、工具方写 N 个服务器就完事。定位我理解了——MCP 扩展的就是 Agentic Loop 里工具执行那一格的工具池。说白了给 Claude 加挂件。14:20 配置先跑通MCP 配置两条路都简单到离谱。第一条是 CLI# 加一个本地 stdio 服务器claude mcpaddfilesystem npx-ymodelcontextprotocol/server-filesystem /workspace# 加一个远程 HTTP 服务器带认证头claude mcpadd--transporthttp--headerAuthorization: Bearer${TOKEN}\company-jira https://jira.company.com/mcp# 加到用户级别所有项目都能用claude mcpadd--scopeuser github -- npx-ymodelcontextprotocol/server-github# 管理claude mcp list# 看哪些挂上了claude mcptestgithub# 测连接claude mcp remove github# 删掉第二条是项目根放一个.mcp.json团队共享配置走这个{mcpServers:{filesystem:{command:npx,args:[-y,modelcontextprotocol/server-filesystem,.]},fetch:{command:npx,args:[-y,modelcontextprotocol/server-fetch]},github:{type:http,url:https://api.githubcopilot.com/mcp/,headers:{Authorization:Bearer ${GITHUB_TOKEN}}},database:{command:npx,args:[-y,bytebase/dbhub,--dsn,${DATABASE_URL}]}}}我一开始选了 CLI图快。后来换台机器又得敲一遍老老实实迁回.mcp.json。这是个真实教训临时验证用 CLI团队/长期用配置文件。环境变量那种${VAR:-default}兜底写法是书里抄的挺好用。14:40 实战一内置 MCP 挂数据库先上最痛的一刀——数据库。官方有现成的modelcontextprotocol/server-postgresnpm 直接跑{mcpServers:{postgres:{command:npx,args:[-y,modelcontextprotocol/server-postgres],env:{DATABASE_URL:${DATABASE_URL:-postgresql://localhost:5432/mydb}}}}}存到.mcp.jsonclaude mcp list看一眼状态是 connected问它这张表有哪些字段——它真去查了。这一下午就值了。中途踩了个坑DATABASE_URL我开始写死成 localhost结果 Claude 跑去连我本地的空库问啥都回表不存在。改成${DATABASE_URL:-...}兜底之后才顺。15:10 实战二自定义 MCP 服务器内置的能用但我想要的不止这些。我想给 Claude 一个 todo 工具让它自己记任务。这得自己写 MCP 服务器。书里给了 Python 和 TS 两个版本。我先抄的 Python因为快。Python 版mcp-servers/todo-server.py配套requirements.txt写mcp1.0.0pip install -r requirements.txtfrommcp.serverimportServerfrommcp.server.stdioimportstdio_server serverServer(todo-server)todos[]defgenerate_id():returnstr(len(todos)1)server.tool(todo_add)asyncdefadd_todo(text:str)-str:Add a new todo itemtodo_idgenerate_id()todos.append({id:todo_id,text:text,done:False})returnfAdded:{todo_id}-{text}server.tool(todo_list)asyncdeflist_todos()-str:List all todo itemsifnottodos:returnNo todos found.return\n.join(f[{xift[done]else }]{t[id]}:{t[text]}fortintodos)asyncdefmain():asyncwithstdio_server()as(read_stream,write_stream):awaitserver.run(read_stream,write_stream)if__name____main__:importasyncio asyncio.run(main())跑起来一报错——generate_id没定义。书里这段省了 ID 生成函数我自己补了一个generate_id()返回len(todos)1能用就行。这是抄书必经环节别指望开箱即用。后来我想顺便试 TS 版因为 TS 版多了个 resource资源概念能暴露stats://current这种 URI 给 Claude 读统计。TS 版mcp-servers/todo-server.ts配套package.json装modelcontextprotocol/sdk和zod记得写type: moduleimport{McpServer}frommodelcontextprotocol/sdk/server/mcp.js;import{StdioServerTransport}frommodelcontextprotocol/sdk/server/stdio.js;import{z}fromzod;// 内存存储consttodos:{id:string;text:string;done:boolean}[][];// 创建 MCP 服务器constservernewMcpServer({name:todo-server,version:1.0.0,});// 工具添加待办server.tool(todo_add,Add a new todo item,// Claude 用这个判断何时调用{text:z.string().describe(The todo text)},// 输入参数 schemaasync({text}){consttodo{id:Math.random().toString(36).substring(2,9),text,done:false,};todos.push(todo);return{content:[{type:text,text:Added:${todo.id}-${todo.text}}],};});// 工具列出待办server.tool(todo_list,List all todo items,{},async(){consttexttodos.length0?No todos found.:todos.map((t)[${t.done?x: }]${t.id}:${t.text}).join(\n);return{content:[{type:text,text}]};});// 资源统计信息server.resource(stats,Server statistics,async(){return{contents:[{uri:stats://current,mimeType:application/json,text:JSON.stringify({total:todos.length,completed:todos.filter((t)t.done).length,pending:todos.filter((t)!t.done).length,},null,2),}],};});// 启动asyncfunctionmain(){consttransportnewStdioServerTransport();awaitserver.connect(transport);console.error(MCP Server started);// 日志走 stderr别污染 stdout}main().catch(console.error);这里有个细节我踩了一脚console.error不是写错。MCP 走 stdio 通信stdout 是协议通道你 print 一条调试日志进去 Claude 就懵了。日志必须吐到 stderr。挂上之后Claude 调用工具的命名规则是mcp__todo-server__todo_add——双下划线分段。这名字可以直接写进 Skills 的allowed-tools让 Skill菜谱指挥 MCP 工具食材干活书里管这叫厨房与菜谱。15:50 调试三板斧跑不通的时候三招从轻到重claude mcp list# 看哪些挂上了、状态对不对claude mcptesttodo-server# 单测某一个服务器claude --mcp-debug# 全局开 debug看协议层报文--mcp-debug是压箱底那招输出会非常啰嗦但能看到 Claude 到底发什么、服务器回什么。我 TS 版第一次跑不通就是靠它看出package.json里漏写type: moduleimport 路径全炸。16:20 收尾一下午跑下来MCP 这套东西的体感是配置简单、协议干净、坑都集中在「抄书少抄了一行」「stdout/stderr 搞混」这种小事上。MN 的设计是真省事——我今天写的 todo-server明天接个 Cursor、后天接别的客户端服务器代码一行不用改。顺便一提雷达鸭后台数据查询我后来就是用这套自定义 MCP 服务器接 UniCloud 的 HTTP 接口写的Claude 直接问留存、问日活比我自己开控制台点快多了。那问题来了——既然 MCP 把 Claude 的手脚放开了数据库能连、API 能调、自定义逻辑能跑那它和你自己写个 CLI 脚本让 Claude 用 Bash 调到底差在哪仅仅是多了层协议包装吗标签MCP、Claude Code、Model Context Protocol、AI Agent、数据库集成个人介绍雷达鸭 App 独立开发者10 年软件开发经验软件设计师、人工智能应用工程师专注鸿蒙 ArkTS Web 前端正在探索 AI 自动化。雷达鸭在华为应用市场和微信小程序都能搜到收录中国一人公司赚钱案例。声明本文基于《Claude Code 实战Harness 工程之道》黄佳 著第 6 章内容整理与实战记录代码示例与配置参考原书。遵循 MIT 协议。
