企业官网建设流程全解析

最近一段时间我几乎每天都在琢磨AI编程，绕不开一个词：MCP。这个东西全称是Model Context Protocol，模型上下文协议，目的很直接——把外部数据源和工具以标准化的方式接到AI模型身边。我最早听说它的时候，以为是又一种RAG之类的配菜，真上手才发现，它改的是AI应用的“连接方式”这件事本身。

这篇文章是我这一段实践的完整记录：MCP解决了什么、协议怎么工作、我怎么从零写了一个自己的MCP服务端，再把它接进常用的AI编程助手，以及最后那些让我折腾半天的坑。适合想认真用AI编程但是受够了“复制-粘贴-交给模型读”这种流程的人，也适合刚听说MCP、不知道从哪动手的新手。你不需要懂底层协议原理，只需要会一点Python，跟着做一遍就能跑通。

1. 为什么要关注MCP：先理解它解决的问题

1.1 AI编程的低效循环，卡在“上下文”上

用AI编程，最常用的姿势是什么？把相关代码一段段复制进对话窗口，然后让模型帮你分析、改bug、补测试。短项目还好，项目一大了就尴尬：模型看不到整个项目的目录结构，看不到被调用的模块，更看不到数据库和配置文件。于是我们不断复制粘贴，人成了“搬运工”。

也有人做插件和工具调用，每个平台自己定义一套工具注册和调用格式。结果就是同一个功能换个工具就得重写一遍。MCP想做的，就是把这层“拿数据、执行动作”的接口标准化。可以把它看成AI应用的HDMI接口——以前每个设备都要单独接一根线，现在统一成一个口，谁都能插。

这带来的好处是双向的。对应用开发者来说，写一个MCP Server，就能服务所有支持MCP的AI工具；对使用AI工具的人来说，不需要记住每家平台各自怎么接数据库、怎么读文件，一个入口全部搞定。正是这种“连接方式的标准化”，让MCP在AI编程领域越来越像是刚需，而不是锦上添花的玩具。

1.2 三件套：Host、Client、Server

MCP的架构不复杂，就三层：Host、Client、Server。

• Host：AI程序本身，比如你正在用的AI编码工具、聊天机器人。
• Client：Host内部的一个连接器，负责和Server建立连接、收发消息。
• Server：独立运行的进程，向外暴露一组能力。

用外卖来解释很贴切。你（模型）不知道每家的锅灶怎么用的。你告诉“中间人”要一份番茄炒蛋。中间人（Client）负责找到会做这道菜的商家（Server），把菜按统一包装端回来。以后要想加一道宫保鸡丁，只需要再签一家商家，接入同一个外卖平台。Server怎么实现、用什么语言写，Host完全不关心，双方只认协议。

一开始我容易把Client和Host搞混，后来记住一句话：Host是你打开的软件，Client是软件里帮你接线的那个代理进程。绝大多数时候你不用自己写Client，AI工具都内置好了，你需要写的只有Server，以及告诉Host“这个Server怎么启动”。

1.3 把MCP理解成AI世界的“USB-C”

USB-C把充电、数据传输、视频输出统一到一个口上，MCP把AI需要的数据访问、工具调用、提示模板统一到一种协议上。一个MCP Server写一次，可以被不同AI辅助工具复用；一个AI工具也可以用同一个入口连接很多不同Server。

我用一个实际的场景来描述这种价值。之前我往AI编程工具里塞知识库，用的是插件A提供的方法；换到另一个工具，又得重新配置插件B的文件格式和调用方式。而用MCP之后，我只需要维护一个“知识库Server”，所有支持的AI工具都能识别它export出来的“查询资料”工具。生态一旦形成，边际成本极低。

2. MCP协议拆解：它到底是怎么工作的

2.1 底层是JSON-RPC 2.0，简单到能背下来

MCP协议在传输层上跑的是JSON-RPC 2.0。JSON-RPC是一种极其简单的请求-响应协议，不搞复杂状态机。MCP把初始化握手、工具发现、工具调用定义为一套方法。

核心方法就几个：

• initialize：启动时握手，双方确认协议版本和能力。
• notifications/initialized：Client通知Server握手完成。
• tools/list：询问Server提供了哪些工具。
• tools/call：请求执行某个工具。
• resources/list、resources/read：枚举和读取资源。
• prompts/list、prompts/get：获取提示模板。

请求长这样：

{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "read_file", "arguments": {"path": "/home/user/demo.py"} } }

Server返回这样的结构：

{ "jsonrpc": "2.0", "id": 1, "result": { "content": [ {"type": "text", "text": "print('hello')"} ], "isError": false } }

为什么要选JSON-RPC？答案很简单：跨语言、零依赖、调试友好。AI生态几乎所有语言都有现成的JSON解析库，客户端和服务端不用引入厚重的框架，用最朴素的字符串流就能通信。我甚至手动模拟过这个协议，整个过程不涉及魔法。

另一个值得注意的点：MCP的握手不是一次性的。初始化完成之后，Client通常还会主动拉一遍tools/list，把工具清单缓存到本地。所以我们在写Server时，工具注册要尽早完成，避免初始化完又动态增减导致Client拿到不一致的缓存。

2.2 三大能力：Tools、Resources、Prompts

MCP Server对外能暴露三类能力，很多人只听说过Tools，其实另外两个也很有用。

我的建议是，第一次做服务端，先从Tools开始，因为效果立竿见影。你在对话里让模型“查一下数据库”，模型真的会去调用工具，这种体验很震撼。Resources适合接知识库，相当于把“喂给模型的背景材料”也变成标准接口。Prompts则偏团队协作，能把“AI应该怎么干活”沉淀成模板，减少各自为政的随机性。

值得强调一句：Tools和Resources的边界不是绝对的。同一个数据，你可以做成Resource让模型自由阅读，也可以做成Tool让模型按需查询。比如一个日志文件，Resource适合小文件整体给模型看，Tool适合大文件按行号取片段。我在实践中按体积做了区分：小于50KB用Resource，大于50KB用Tool加参数裁剪。

2.3 传输方式怎么选：stdio和HTTP

MCP有两种主流传输方式，刚上手一定要分清。

• stdio：Server作为子进程启动，消息走标准输入/输出。
• HTTP：Server暴露一个HTTP端点，比如使用Streamable HTTP方式通信。

本地开发调试用stdio，理由很直白：不用配端口、不用管跨域、不用准备证书，进程即开即关，像本地起一个命令行工具一样干净。远程共享、服务器部署用HTTP，适合多客户端同时访问同一个MCP服务。

协议版本迭代也影响传输细节。较新的协议规范大多采用Streamable HTTP作为远程传输，Server可以返回一条JSON，也可以按SSE流式推送多条。这里不过多展开，因为你实际开发时，SDK会帮你处理好协议版本差异。只需要脑子里有个概念：本地用stdio，远程用HTTP，两条路线分开走。

3. 手把手做一个MCP服务端：最小可用工程

3.1 环境准备与SDK选型

我用的是Python SDK，生态最成熟，文档也全。如果你主力是JavaScript，用官方TypeScript SDK，写法非常相似。

先建一个干净的项目目录：

mkdir mcp-demo cd mcp-demo python -m venv .venv source .venv/bin/activate pip install "mcp[cli]"

这里强烈建议建虚拟环境。后面接入AI编程助手时，配置command直接填venv里的Python绝对路径，可以少踩很多环境混乱的坑。很多“Server启动就报ModuleNotFoundError”的问题，根源就是进程用了全局Python，没走venv。

3.2 第一个Server：一个只读文件查看器

先写个最简单的，感受一下MCP的开发体验。

from mcp.server.fastmcp import FastMCP mcp = FastMCP("file-reader") @mcp.tool() def read_file(path: str, start: int = 0, length: int = 4000) -> str: """读取本地文件指定区间的内容，用于AI分析代码和配置。路径必须是绝对路径。""" with open(path, "r", encoding="utf-8") as f: f.seek(start) return f.read(length) if __name__ == "__main__": mcp.run()

就这么几行。FastMCP帮我们完成了绝大多数脏活：生成参数Schema、注册JSON-RPC方法、处理initialize握手、管理stdio通信。工具描述直接写在docstring里，SDK会自动转成模型看到的工具声明——描述越具体，模型越容易在正确的场景调用，千万别用“通用工具”这种模糊说法。

再加一个“查询SQLite”的工具，这一步更接近真实需求。

@mcp.tool() def query_orders(db_path: str, sql: str) -> list: """对SQLite数据库执行只读查询，返回行字典列表。只允许SELECT开头的语句。""" import os if not os.path.isfile(db_path): return [{"error": "数据库文件不存在"}] sql = sql.strip() if not sql.lower().startswith("select"): return [{"error": "仅允许SELECT查询"}] import sqlite3 conn = sqlite3.connect(db_path) try: conn.row_factory = sqlite3.Row rows = conn.execute(sql).fetchall() return [dict(row) for row in rows] finally: conn.close()

给模型开放数据库能力，是MCP最香的场景。但风险也随之而来。我在工具里做了两道闸：第一道，只允许SELECT开头的语句，从源头堵住篡改数据；第二道，返回行字典列表，让模型能看到列名和值，而不是一堆裸元组。后面讲安全的时候我还会展开说。

3.3 本地验证：先别急着接IDE

写好Server之后，不要急着配AI编程助手。先用SDK写一个测试Client，验证Server本身能不能正常工作。这样出了问题，你能精确定位是Server的问题还是AI工具配置的问题。

测试脚本：

import asyncio from mcp import ClientSession, StdioServerParameters from mcp.client.stdio import stdio_client async def main(): params = StdioServerParameters( command="python", args=["server.py"] ) async with stdio_client(params) as (read, write): async with ClientSession(read, write) as session: tools = await session.list_tools() print("工具列表:", [t.name for t in tools.tools]) result = await session.call_tool( "read_file", {"path": "server.py"} ) print(result.content) asyncio.run(main())

第一次跑通这个脚本的时候，你会看到工具列表里有read_file和query_orders，然后调用read_file打印出server.py自己的内容。这个过程虽然朴素，但意义很大：证明你的Server独立可用，JSON-RPC握手没问题，工具调用链路是通的。后面再接AI编程助手，就等于“换个客户端再连一次”，思路完全一致。

如果不想写脚本，也可以用官方SDK自带的MCP Inspector调试面板，它会启动一个可视化界面，能看到工具列表、参数Schema、调用结果，特别适合排查Server返回内容的结构问题。我一般先用脚本快速验证，再用Inspector看细节。

4. 把MCP Server接进AI编程助手，完成闭环

4.1 配置入口：两类方式

现在主流的AI编程助手基本都支持MCP了。配置方式大体分两类：一类在图形设置面板里添加，填命令和参数；另一类在项目根目录放配置文件。我用项目根目录的配置文件举例，因为它通用性好，而且可以跟着Git提交，团队里其他人拉下来就能用。

配置文件本质是一个JSON，里面有一个mcpServers对象，每个key是一个Server的名字，值就是启动方式。

4.2 本地Server配置：路径和命令是重灾区

{ "mcpServers": { "file-reader": { "command": "/absolute/path/mcp-demo/.venv/bin/python", "args": ["/absolute/path/mcp-demo/server.py"] } } }

这里有两个关键点，都是我踩过坑总结出来的。

第一，command要填绝对路径。AI编程助手拉起Server进程时，工作目录不一定是你的项目目录。如果你直接填“python”，很可能调用的是系统全局Python，而这个全局环境里没装mcp包，于是一启动就报ModuleNotFoundError。填venv里的Python绝对路径，就绕开了这个问题。

第二，args里的Server脚本路径也要用绝对路径。别用相对路径，因为你没法保证子进程的当前目录在哪。这也是新手最容易困惑的地方：明明在终端里跑python server.py没问题，换成AI助手配置就起不来，十有八九是路径问题。

配置完成后重启AI助手，或者重新加载窗口。然后在对话里说一句：“用read_file读一下server.py。”模型如果正确调用了工具，你会看到它真的打开了文件，而不是依赖你粘贴的内容。那一刻你会理解MCP解决了什么问题。

4.3 工具返回值的结构，直接影响模型表现

模型不是人，但它对“结构化文本”的敏感度很高。Server返回的数据格式，直接决定了模型能不能高效理解。

我总结了三条经验。

文本类结果，给清晰摘要，报错信息带上行号和关键片段。比如读取配置文件失败时，返回“第12行缺失右括号”，模型就能直接给出修复建议，而不是对着错误码瞎猜。

数据库结果，返回字典列表，列名就是字典key。模型不需要额外推理“第一列是什么”，可以直接组织成自然语言回答。

大文件绝对不要整段返回。我增加start和length参数，让模型按区间读取，就是怕一个文件把模型的上下文窗口撑爆。你的工具设计越精细，模型的上下文利用率就越高。

4.4 远程Server：先用本地，再碰远程

如果你后续想做成团队共享的服务，可以配置远程MCP Server，用url字段替代command和args，再加一个headers字段放鉴权信息：

{ "mcpServers": { "team-tools": { "url": "https://example.com/mcp", "headers": { "Authorization": "Bearer YOUR_TOKEN" } } } }

但我的建议非常明确：跑通本地之前，绝对不要碰远程。远程Server涉及网络策略、跨域、鉴权、响应超时等一系列问题，调试成本成倍增加。我在本地链路跑顺之后，才尝试部署远程版本，前后折腾了一整天，主要原因就是日志分散在两边，一个问题要同时盯Server端和AI助手端的日志才能定位，效率极低。

5. 常见问题与排错速查表

5.1 五个高频问题实录

这些问题基本覆盖了新手起步时会遇到的80%故障。

最常见的套路是“直接用现象搜方案”，但我更推荐你按下面的排查方法做一次系统定位，之后再遇到问题，五分钟就能搞定。

5.2 排查方法论：三步定位

我调试MCP问题时有一套固定流程。

第一步，先用测试Client测Server，什么都不接，只看Server本身能不能跑通。这样能快速排除“配置写错”和“Server没写对”这两个最大的变量。

第二步，看初始化握手。SDK开启DEBUG日志后，能看到initialize的请求和响应，以及tools/list的交互过程。只要握手通了，说明双方协议没问题，问题大概率在客户端配置。

第三步，测tools/call。这时要关注参数传递：模型可能把“日期”传成字符串、把“路径”传成相对路径，服务端要做参数校验并给出清晰报错，而不是抛一个500似的模糊异常。

日志级别一定要设成DEBUG。我见过很多同学卡了半天，最后发现日志里清清楚楚写着“找不到工具read_file”，只是默认级别没打印出来。

5.3 安全与边界：给工具加权限是底线

MCP把模型从“只会说话”变成了“能动手”，这是好事，但也意味着风险。我对自己所有工具都定了三条铁律。

第一，只暴露必要权限。给模型开放数据库能力时，只允许SELECT就是底线。如果需要写操作，宁可再加一个专门的高权限Server，也不要让同一个工具既读又写。

第二，文件操作必须做白名单校验。路径要限定在指定目录内，防止路径穿越，比如“../../etc/passwd”这种输入。模型没有主观恶意，但它会猜，会从对话上下文里找路径，你的校验越严格，出事的概率越低。

第三，远程Server不要裸奔公网。除非有完善的鉴权代理，否则别把MCP Server直接暴露到公网。本地stdio模式天然安全，因为它只跟父进程通信；一旦改成HTTP，就要认真对待Token、HTTPS、访问控制这些东西。

最后聊聊我自己的体感。我一开始看到MCP那一堆术语，Host、Client、Server、JSON-RPC，脑子里是抵触的，总觉得“我这需求用得着这么重吗”。真正跑通最小例子之后才发现，里面80%的复杂度都被SDK吞掉了。最值得做的一件事，是先别急着设计一大堆Tools，耐下心跑通“读文件”“查SQLite”这两个小工具，然后把它们接到你最常用的AI编程环境里。你会发现以前那种“复制文件内容、贴进对话窗口、再描述需求”的循环，是真的能被替代掉的。踩过几次坑后，我最大的心得是：stdio本地链路是一切的前提，远程和鉴权都是后话。先把第一步走稳，后面怎么玩都顺手。