最近在开发 AI 应用时常常会遇到两个问题一是团队里的 Agent 越来越多二是 MCP Client 也越来越多。不同的 Agent 可能要放在不同的 MCP Server 里每次要在多个客户端之间来回切换光是找可用的 Agent 就要花不少精力。所以我做了这样一个东西一个用于“搜索 AI Agent”的 MCP Server让任意 MCP Client 都可以通过统一的协议去查询、筛选和获取 Agent 的元数据。它是一个很典型的 MCP 服务端实践也适合用来理解 MCP 的完整调用链。这篇文章会把从 MCP 基础概念、Minimal Server 搭建到完整的 Agent 搜索 Server 实现、多客户端接入、常见坑点排查全部串起来。新手可以把它当 MCP 的入门实操教程已经熟悉 MCP 的开发者则可以直接跳到第 4 节和第 5 节看代码和接线方案。1. 为什么需要一个“MCP 里搜索 Agent”的 Server1.1 从一次工具混乱讲起我身边很多团队已经进入“AI Agent 数量失控”的阶段有人用 Claude Desktop有人用 Dify有人在自己写的 Python 业务系统里接 MCP Client。每个系统里都会维护一组 Agent 连接信息包括 Agent 名称、用途、依赖的工具、调用端点。一开始只有两个 Agent 时直接写死在代码里没问题等规模到十几个之后每次新增 Agent 都要改所有客户端配置运维成本直线上升。这时候最容易想到的方案是做一个“Agent 注册中心”或者“Agent 目录服务”。但问题来了客户端五花八门难道要为每个客户端都写一套 API而 MCP 本身就是为“让客户端统一访问工具和数据”设计的所以把 Agent 目录封装成 MCP Server是最保值、复用面最广的做法。1.2 MCP、Server、Client、Agent 是什么关系先做一组概念区分后面代码里全都会用到MCPModel Context Protocol是一个开放协议用于给 AI 模型提供访问外部工具、数据源、上下文信息的标准化接口。它解决的是“模型与应用环境之间如何通信”的问题。MCP Server 是一段提供工具、资源、提示词的程序。它把某种能力暴露出来比如数据库查询、文件搜索、Agent 列表查询。MCP Client 是连接 MCP Server 并调用其能力的程序。常见的 MCP Client 有 Claude Desktop、Dify、Cursor、自研 Python 程序等。AI Agent 在这一场景里是被搜索、被调用的业务对象。它可能是另一个 LLM 应用、一套自动化工作流、或者一个能执行任务的工具链。用一句话概括MCP Server 是“能力的提供方”MCP Client 是“能力的消费方”Agent 是我们希望通过 MCP 标准化访问的业务实体。1.3 本文要解决的问题我要做的 Agent Search MCP Server本质上是一个“只读查询类”MCP Server。它不执行 Agent 的复杂逻辑只解决三件事通过 MCP Tool 提供关键词搜索 Agent 的能力。通过 MCP Resource 暴露某个 Agent 的详细配置信息。通过 MCP Prompt 生成“创建新 Agent 的模板”帮助其他 Agent 或客户端快速发起注册流程。这样任何一个支持 MCP 的客户端只要能连上这个 Server就能在对话中搜索 Agent而不需要关心后端到底用的是哪个 Agent 平台、数据库还是配置文件。2. MCP 核心概念与环境准备2.1 MCP 协议的构成在开始写代码前先熟悉 MCP 的三个核心建模单元因为它们会贯穿第 4 节的实战Tools客户端可调用的函数有入参和出参适合脚本化操作和工具调用。Resources暴露只读数据资源类似 REST 里的 GET 接口适合提供配置、文档、目录等结构化内容。Prompts可复用的提示词模板适合让 LLM 理解“怎么执行某个流程”比如“如何注册一个新 Agent”。另外还有 Transport传输层常见的有 stdio、SSE、HTTP/sse 等。本地开发调试最常用 stdioDify 等平台支持 SSE/HTTP 方式接入。2.2 环境准备版本说明MCP 生态迭代较快本文以 Python 3.10 和mcpSDK 为准。你实际安装时版本号可能有更新下面所有代码的重点是“配置思路”和“协议调用逻辑”按你的环境版本微调即可。需要准备的工具Python 3.10 及以上版本。pip 或 uv 包管理器。一个支持 MCP 的客户端用于最终验证比如 Claude Desktop、Dify、或者直接用 Python 写测试 Client。如果要在本地跑 HTTP/SSE 模式准备好可用的端口比如 8000。命令行安装 SDKpip install mcp[cli]也可以使用 uvuv add mcp[cli]为了验证安装是否成功可以执行mcp --version如果出现版本号说明 SDK 安装正常。2.3 项目结构我建议按下面的目录组织代码方便后续扩展agent-search-mcp/ ├── server.py # MCP Server 主入口 ├── agent_data.py # Agent 数据层模拟数据库 ├── client.py # 本地测试用 MCP Client ├── .mcp.json # MCP Client 配置文件 └── README.md # 项目说明这样拆分的好处是数据层单独放后续可以替换成 MySQL、PostgreSQL 或者调用真实 Agent 平台的 API而 MCP 层代码不需要大改。3. 用一个最小 MCP Server 理解调用链很多初学者会把 MCP 想得很神秘实际上它的本地调用链非常简单。本节先写一个 20 行左右的 Server再写一个 Client把整条调用链跑通。3.1 编写最小 Server文件路径minimal_server.pyfrom mcp.server.fastmcp import FastMCP # 创建 MCP Server 实例 mcp FastMCP(minimal-demo) # 声明一个 Tool返回欢迎语 mcp.tool() def hello(name: str) - str: Say hello to a user. return fHello, {name}! This is an MCP tool. # 声明一个 Resource返回版本信息 mcp.resource(config://app) def get_config() - dict: Return app config. return { name: minimal-demo, version: 1.0.0, author: your-name } # 启动 Serverstdio 模式适合本地调试 if __name__ __main__: mcp.run(transportstdio)代码解释FastMCP是 MCP Python SDK 提供的高层封装简化了协议细节。mcp.tool()会把下面的函数注册成一个 Tool参数和返回值需要能被 JSON 序列化。mcp.resource(config://app)注册了一个只读资源URI 是config://app。mcp.run(transportstdio)表示以标准输入输出作为传输层。Client 通过子进程启动这个 Server然后通过 stdin/stdout 通信。3.2 编写最小 Client文件路径minimal_client.pyimport asyncio from mcp import ClientSession, StdioServerParameters from mcp.client.stdio import stdio_client async def main(): # 定义要启动的 Server 进程参数 server_params StdioServerParameters( commandpython, args[minimal_server.py], ) async with stdio_client(server_params) as (read, write): async with ClientSession(read, write) as session: # 初始化握手 await session.initialize() # 调用 Tool result await session.call_tool(hello, {name: CSDN}) print(Tool result:, result.content) # 读取 Resource resource await session.read_resource(config://app) print(Resource content:, resource) if __name__ __main__: asyncio.run(main())代码解释StdioServerParameters声明如何启动子进程command和args就是在命令行里运行该 Server 的方式。stdio_client()创建子进程并建立 stdin/stdout 双向管道。ClientSession负责维护 MCP 协议会话必须先initialize()完成握手。call_tool()是执行 Tools 的方法read_resource()是读取 Resources 的方法。3.3 运行调用链先在一个终端启动 Server如果直接跑 ClientClient 会自动拉起 Server因此你其实不需要单独手动启动python minimal_client.py预期输出类似Tool result: [TextContent(textHello, CSDN! This is an MCP tool.)] Resource content: [TextResourceContents(uriTextUri(config://app), mime_typetext/plain, text{name: minimal-demo, version: 1.0.0, author: your-name})]到这里你已经理解了 MCP 的最小闭环Client 启动 Server 进程 → 双方握手 → Client 调用 Tool → Server 执行并返回结构化结果。3.4 最低限度你要记住的三件事initialize()必须在任何调用前完成。Tool 的入参通过call_tool(name, arguments)传入arguments是字典。Resource 的读取结果是TextResourceContents列表需要按resource.contents解析。4. 实现一个 Agent 搜索 MCP Server现在进入本文的核心实现一个能搜索 AI Agent 的 MCP Server。4.1 功能需求设计我们把它设计成一个轻量级 Agent 目录服务功能如下search_agents按关键字搜索 Agent支持分页和按领域过滤。get_agent根据 Agent ID 获取详细信息。register_agent往目录中注册一个新 Agent。agent_list_resource通过 Resource 暴露完整 Agent 列表。new_agent_prompt通过 Prompt 输出“创建并注册新 Agent”的模板。这里要特别说明从安全角度register_agent只是演示数据写入思路。生产环境中如果要开放注册能力必须加上身份认证、请求校验和数据持久化避免恶意覆盖已有 Agent 信息。4.2 数据结构设计为了不过度引入数据库依赖本示例采用内存数据 JSON 文件持久化。未来可以替换为数据库或真实 Agent 平台的 API。文件路径agent_data.pyimport json import os import uuid from typing import Optional DATA_FILE os.path.join(os.path.dirname(__file__), agents.json) DEFAULT_AGENTS [ { id: agent-001, name: 文档总结 Agent, description: 对长文档进行摘要和结构化提取, domain: nlp, tools: [file_reader, text_splitter], endpoint: agent-service://doc-summary, enabled: True, }, { id: agent-002, name: SQL 查询 Agent, description: 根据自然语言生成并执行 SQL, domain: database, tools: [sql_executor, schema_lister], endpoint: agent-service://sql-query, enabled: True, }, { id: agent-003, name: RAG 问答 Agent, description: 基于知识库检索的问答助手, domain: rag, tools: [vector_search, rerank], endpoint: agent-service://rag-qa, enabled: False, }, ] def load_agents() - list[dict]: 从 JSON 文件加载 Agent 列表不存在则使用默认数据 if os.path.exists(DATA_FILE): with open(DATA_FILE, r, encodingutf-8) as f: return json.load(f) return DEFAULT_AGENTS def save_agents(agents: list[dict]) - None: 持久化 Agent 列表到 JSON 文件 with open(DATA_FILE, w, encodingutf-8) as f: json.dump(agents, f, ensure_asciiFalse, indent2) def search_agents(keyword: str , domain: str , limit: int 10, offset: int 0) - dict: 按关键字和领域搜索支持分页 agents load_agents() keyword keyword.strip() domain domain.strip() filtered [] for agent in agents: if not agent[enabled]: continue if keyword and keyword.lower() not in (agent[name] agent[description]).lower(): continue if domain and domain ! agent[domain]: continue filtered.append(agent) total len(filtered) paged filtered[offset: offset limit] return { total: total, items: paged, } def get_agent(agent_id: str) - Optional[dict]: 根据 ID 查询单个 Agent agents load_agents() for agent in agents: if agent[id] agent_id: return agent return None def add_agent(name: str, description: str, domain: str, tools: list[str], endpoint: str) - dict: 新增 Agent返回创建后的完整数据 agents load_agents() new_agent { id: fagent-{uuid.uuid4().hex[:8]}, name: name, description: description, domain: domain, tools: tools, endpoint: endpoint, enabled: True, } agents.append(new_agent) save_agents(agents) return new_agent这里把数据层与 MCP 层分开后续如果要在生产环境使用只需要把search_agents、get_agent、add_agent三个方法改成访问数据库或调用远端接口即可。4.3 编写 MCP Server 主逻辑文件路径server.pyfrom mcp.server.fastmcp import FastMCP from agent_data import search_agents, get_agent, add_agent mcp FastMCP(agent-search-server) mcp.tool() def search_agents_tool(keyword: str , domain: str , limit: int 10, offset: int 0) - dict: 搜索可用的 AI Agent。 - keyword: 搜索关键词匹配 Agent 名称和描述 - domain: 按领域过滤例如 nlp / database / rag - limit: 返回条数上限 - offset: 分页偏移量 result search_agents(keywordkeyword, domaindomain, limitlimit, offsetoffset) return result mcp.tool() def get_agent_tool(agent_id: str) - dict: 根据 Agent ID 获取详情 agent get_agent(agent_id) if not agent: return {error: fagent {agent_id} not found} return agent mcp.tool() def register_agent_tool( name: str, description: str, domain: str, tools: list[str], endpoint: str, ) - dict: 注册一个新的 AI Agent。请确认 name 和 endpoint 在目录中唯一。 agent add_agent( namename, descriptiondescription, domaindomain, toolstools, endpointendpoint, ) return agent mcp.resource(agents://list) def agent_list_resource() - str: 返回所有可用 Agent 的摘要列表只读 result search_agents(keyword, domain, limit100, offset0) lines [f- {a[id]}: {a[name]} ({a[domain]}) - {a[description]} for a in result[items]] return \n.join(lines) mcp.resource(agents://{agent_id}) def agent_detail_resource(agent_id: str) - str: 返回指定 Agent 的完整信息 agent get_agent(agent_id) if not agent: return fAgent {agent_id} not found return fName: {agent[name]}\nDescription: {agent[description]}\nDomain: {agent[domain]}\nTools: {, .join(agent[tools])}\nEndpoint: {agent[endpoint]} mcp.prompt() def new_agent_prompt() - str: 生成创建新 Agent 的提示词模板 return 你正在帮助用户创建并注册一个新的 AI Agent。请按以下格式整理信息 1. Agent 名称英文短横线格式如 customer-support 2. 功能描述一句完整描述 3. 领域分类从 nlp / database / rag / vision / audio 中选择 4. 依赖工具列表逗号分隔 5. 调用端点必须是合法 URI例如 agent-service://xxx 确认信息完整后调用 register_agent_tool 完成注册。 if __name__ __main__: mcp.run(transportstdio)这里需要重点解释几个细节Tool 函数名不能和 Python 内置函数冲突所以加了_tool后缀但 MCP 对外暴露的名称就是函数名本身例如search_agents_tool。客户端调用时必须使用这个名称。Resource 支持路径参数写法是agents://{agent_id}MCP SDK 会做 URI 模板匹配。Prompt 返回的是一个字符串模板LLM 客户端可以把它作为上下文交给模型引导模型按指定流程注册 Agent。4.4 编写测试客户端文件路径client.pyimport asyncio from mcp import ClientSession, StdioServerParameters from mcp.client.stdio import stdio_client async def main(): server_params StdioServerParameters( commandpython, args[server.py], ) async with stdio_client(server_params) as (read, write): async with ClientSession(read, write) as session: await session.initialize() print( 1. Search Agents ) result await session.call_tool( search_agents_tool, {keyword: SQL, limit: 5}, ) print(result.content[0].text) print(\n 2. Get Agent Detail ) detail await session.call_tool( get_agent_tool, {agent_id: agent-002}, ) print(detail.content[0].text) print(\n 3. Read Resource ) resource await session.read_resource(agents://list) print(resource.contents[0].text) print(\n 4. Read Agent Detail Resource ) resource_detail await session.read_resource(agents://agent-001) print(resource_detail.contents[0].text) print(\n 5. List Prompts ) prompts await session.list_prompts() for p in prompts.prompts: print(f- {p.name}: {p.description}) if __name__ __main__: asyncio.run(main())4.5 运行与预期结果在项目根目录执行python client.py预期输出大致如下顺序相同 1. Search Agents {total: 1, items: [{id: agent-002, name: SQL 查询 Agent, ...}]} 2. Get Agent Detail {id: agent-002, name: SQL 查询 Agent, ...} 3. Read Resource - agent-001: 文档总结 Agent (nlp) - 对长文档进行摘要和结构化提取 - agent-002: SQL 查询 Agent (database) - 根据自然语言生成并执行 SQL 4. Read Agent Detail Resource Name: 文档总结 Agent Description: 对长文档进行摘要和结构化提取 Domain: nlp Tools: file_reader, text_splitter Endpoint: agent-service://doc-summary 5. List Prompts - new_agent_prompt: 生成创建新 Agent 的提示词模板到这里一个完整的、支持 Tool、Resource、Prompt 三类能力的 Agent 搜索 MCP Server 就完成了。5. 从任意 MCP Client 接入一个 MCP Server 的复用价值最终要体现在“能从不同客户端接入”。这里给出三种常见接入方式。5.1 使用通用 MCP 客户端配置很多桌面向客户端比如 Claude Desktop、支持 MCP 的 IDE都支持通过 JSON 配置连接 stdio 类型的 Server。配置片段示例以 Claude Desktop 为例配置文件位置按客户端实际版本确定{ mcpServers: { agent-search: { command: python, args: [/absolute/path/to/agent-search-mcp/server.py] } } }配置完成后客户端会自动启动该 Server并在对话中暴露search_agents_tool、get_agent_tool、register_agent_tool等工具。你可以在对话中直接让 AI 执行“搜索一下数据库领域的 Agent”AI 会调用 Tool 并返回结果。5.2 在 Dify 中添加本地 MCP 服务Dify 是目前很常用的 LLM 应用开发平台支持 MCP 工具的接入。在 Dify 中添加本地 MCP 服务的操作路径通常如下打开 Dify 的工作流或 Agent 应用。找到“工具”或“插件”配置入口。选择添加 MCP 服务。根据本地 Server 的传输方式选择 stdio 或 SSE/HTTP。如果 Server 已启动为 HTTP 模式则填入对应的 Endpoint URL。如果你希望 Dify 通过 HTTP 访问本地 Server可以修改server.py的启动方式if __name__ __main__: mcp.run(transporthttp, host127.0.0.1, port8000)注意HTTP 模式只绑定到127.0.0.1时仅允许本机访问。如果部署在服务器上需要被其他机器访问要绑定到服务网卡 IP并配合防火墙、鉴权等安全策略不要直接暴露到公网。5.3 使用 .mcp 文件管理.mcp文件是 MCP 客户端之间共享 Server 配置的一种约定格式。一个典型的.mcp文件内容如下{ name: agent-search, type: stdio, command: python, args: [/absolute/path/to/agent-search-mcp/server.py], env: {} }有了这个文件后可以在支持.mcp文件导入的客户端中直接加载减少重复配置。团队协作时把.mcp文件提交到 Git 仓库新成员拉下来后一键导入即可。5.4 部署相关建议本地开发用 stdio 最省事但远程客户端需要 HTTP/SSE。多个 Agent 可以跑在同一台机器的不同端口通过 Nginx 或网关做统一入口。如果同一个 Server 需要服务多个用户必须引入鉴权机制MCP 本身只是一个协议不负责身份认证。6. 常见问题与排查思路在开发和接入 MCP Server 时很容易碰到下面几类问题。我整理成表格方便你快速对照排查。问题现象常见原因解决思路Client 启动后马上报错没有输出command或args写错进程启动失败在命令行手动执行python server.py验证是否能正常运行调用 Tool 返回Method not foundSDK 版本过旧或 Server 内部注册函数未生效升级mcpSDK检查装饰器是否写错确认函数放在 Server 启动前call_tool卡住不返回Server 卡在某个阻塞操作比如无限循环或请求第三方接口超时在 Tool 函数里增加超时控制本地先用client.py做最小验证Resource URI 400/404URI 模板写错或路径参数与函数参数名不一致检查mcp.resource(agents://{agent_id})中的参数名必须与函数参数一致中文输出乱码终端编码问题设置PYTHONIOENCODINGutf-8检查 JSON 文件是否用 UTF-8 保存Dify 连接不上本地 HTTP Server端口未监听、防火墙未放行、绑定了 127.0.0.1先 curl 测试再用--host 0.0.0.0启动并配置安全策略修改了 agents.json 但客户端没感知Resource 和 Tool 每次执行时重新读取文件但客户端可能缓存了列表重新发起调用或重启客户端检查load_agents()是否每次都被执行一个比较实用的排查顺序是先手动运行python server.py确认没有语法错误和端口冲突。再运行python client.py确认最基本的 Tool/Resource 调用正常。如果本地正常但某个客户端异常重点排查该客户端的 MCP 配置格式。最后再看日志。SDK 在 stdio 模式下会把协议日志输出到 stderr客户端一般会捕获 stderr 并展示方便定位握手失败的具体原因。7. 最佳实践与工程建议7.1 目录与命名规范一个 Agent 目录服务最忌讳的是 Agent 信息混乱。建议形成以下规范id全局唯一生成后不可变更。name使用短横线英文格式作为展示名和内部标识。domain收敛到固定枚举而不是自由文本方便后续做筛选和权限控制。endpoint统一使用合法 URI 协议例如agent-service://、https://避免出现“localhost:8080”这类不完整的地址。7.2 数据与安全边界MCP Server 在默认的 stdio 模式下相当于在客户端本地执行任意 Python 代码。虽然这里用的是 FastMCP 高层封装但你写的 Tool 函数本质上就是一段会被客户端驱动的代码。因此在生产环境要注意不要把敏感凭据硬编码在 Tool 中。register_agent_tool这类写操作必须加权限校验。如果 Server 要暴露到网络必须实现鉴权层MCP 协议本身不包含认证机制。使用 HTTP 模式时建议放在反向代理后面用 HTTPS 加密传输。涉及到批量注册或删除 Agent 时先导出备份再执行变更。7.3 输入校验与异常处理我在实战中遇到最多的问题不是协议逻辑而是 Tool 函数的入参边界。例如mcp.tool() def search_agents_tool(keyword: str , domain: str , limit: int 10, offset: int 0) - dict: if limit 0 or limit 100: limit 10 if offset 0: offset 0 try: result search_agents(keywordkeyword, domaindomain, limitlimit, offsetoffset) return result except Exception as e: return {error: str(e)}这样做的好处是即使客户端传入异常参数Server 也能返回明确的错误信息而不是直接崩溃。7.4 日志与可观测性MCP Server 的日志默认会写到 stderr很多客户端会把它展示出来。建议在关键 Tool 调用前后输出结构化日志import logging logging.basicConfig(levellogging.INFO) logger logging.getLogger(agent-search-mcp) logger.info(search_agents called with keyword%s, domain%s, keyword, domain)在 HTTP 部署模式中可以接入更完整的日志采集和链路追踪系统方便定位“哪个客户端在何时调用了哪个 Tool”。8. 总结与下一步学习方向这篇文章围绕“Search AI Agents from Any MCP Client”这个需求从 MCP 基础概念讲起完成了一个最小调用链的验证然后实现了一个包含 Tools、Resources、Prompts 三类能力的 Agent 搜索 MCP Server并且演示了如何从自定义 Python Client、通用 MCP 客户端、Dify 本地 MCP 服务这几个方向接入。整篇文章的核心收获可以归纳为四条MCP 的调用链非常清晰Client 启动 Server 进程 → 握手 → 调用 Tool / 读取 Resource / 使用 Prompt → 返回 JSON。一个只读查询类的 MCP Server 是最容易上手的实战项目但它同样能覆盖 MCP 的大部分核心概念。数据层和协议层解耦是这个项目的关键设计决定。后续替换数据库、接入真实 Agent 平台都不会影响 MCP 层。任何 MCP 能力接入生产环境前都要先想清楚安全边界谁可以调用、谁可以写入、数据是否敏感。如果你接下来要继续深入 MCP 方向可以考虑这几个方向把agent_data.py换成 PostgreSQL 或 Redis实现真正的多实例共享 Agent 目录。增加 Agent 的健康检查 Tool让搜索时能过滤掉下线的 Agent。研究 MCP Authorization 规范给写操作加上基于角色的权限控制。用 Python 实现一个 MCP Gateway统一路由多个 MCP Server让客户端只需要连接一个入口。代码已经从最小 Demo 到完整服务端都贴出来了建议动手跑一遍。如果运行中遇到问题回到第 6 节的排查表大多数场景都能找到答案。