实用指南：企业应用中的MCP工具——初学者友好版
《实用笔记》操作指南：企业应用中的MCP工具——初学者友好版：为采用该模式的团队提供合同、校验规则以及可直接插入的代码模块。
以下笔记为“企业应用中的MCP工具：适合初学者的深入解析”提供了一条实用的学习路径。重点在于契约、校验以及可直接插入的代码占位符，而非激励性表述。 在完成概览阶段时，首先列出契约内容：所需输入、成功信号以及部分失败时的处理方式。这样的清单能确保后续的代码修改保持一致性。 将此阶段视为输入与经过验证的输出之间的契约。为相关成果命名，明确成功校验标准，并杜绝无声的半完成状态。
1. 问题所在：企业为何最初需要MCP
第一部分：问题所在——为何将阶段视为可度量的界面最为有效。在扩大范围之前，先记录一个成功的案例、一个失败案例以及回滚说明。在功能结果旁同时记录执行时间以及令牌或查询成本。提前了解成本情况，可避免在从演示环境过渡到共享环境时出现意外费用。
BEFORE MCP — the N x M integration problem
┌───────────┐ ┌─────────────┐
│ Agent A │───────▶│ CRM API │ (custom connector #1)
└───────────┘ └─────────────┘
┌───────────┐ ┌─────────────┐
│ Agent A │───────▶│ Ticketing │ (custom connector #2)
└───────────┘ └─────────────┘
┌───────────┐ ┌─────────────┐
│ Agent B │───────▶│ CRM API │ (custom connector #3 -
└───────────┘ └─────────────┘ yes, AGAIN, for a different agent)
┌───────────┐ ┌─────────────┐
│ Agent B │───────▶│ Data │ (custom connector #4)
└───────────┘ │ Warehouse │
└─────────────┘
N agents x M systems = N x M custom, non-reusable integrations.
Every new agent re-implements auth, retries, schemas, error handling.
AFTER MCP — one protocol, many servers, many clients
┌───────────┐ ┌───────────────────┐
│ Agent A │──┐ ┌─▶│ MCP Server: CRM │
└───────────┘ │ ┌───────────┐ │ └───────────────────┘
├───▶│ MCP │───┤ ┌───────────────────┐
┌───────────┐ │ │ (shared │ ├─▶│ MCP Server: Ticket │
│ Agent B │──┘ │ protocol)│ │ └───────────────────┘
└───────────┘ └───────────┘ │ ┌──────────────────┐
└─▶│ MCP Server: DW │
└──────────────────┘
Any MCP-compatible agent can now talk to any MCP server.
Build the connector once, reuse it everywhere.
2. 核心概念简述
“两个核心概念解析”阶段若被视为可度量的对象会更为有效。在扩大范围之前，先收集一份优秀的操作记录、一个失败案例以及回滚说明。 将配置置于应用程序代码之外。环境文件、密钥存储和功能开关应集中存放，以便操作人员无需查看整个系统结构即可进行审计。 提供具有明确数据结构和清晰副作用标签的工具。主机需要在自动批准之前知道哪些调用会改变系统状态。
服务器可提供的三种基本功能
将某个阶段视为可度量的对象来处理时，三种基本要素才能发挥最佳作用。在扩大范围之前，需记录一份理想运行案例、一个故障案例以及回滚说明。 同时记录正常流程与恢复流程。重试机制、人工审核环节以及死信处理都是产品本身的一部分，而非后续需要补充的内容。 应提供具有明确结构规范和清晰副作用标识的工具。主机需要在自动批准之前知道哪些调用会改变状态。 将某个阶段视为输入与经过验证的输出之间的契约。为相关成果命名，定义成功判定标准，绝不允许出现无声的半完成状态。
3. 架构：三层结构的整体呈现
在“架构全部”阶段，修改代码之前需明确输入参数、该步骤的负责人以及结束标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。应在功能结果旁记录执行时间以及令牌或查询成本。提前了解成本情况，可避免在从演示环境过渡到共享环境时出现意外费用。
┌─────────────────────────── HOST APPLICATION ───────────────────────────┐
│ e.g. an internal AI assistant, IDE plugin, support copilot │
│ │
│ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ │
│ │ MCP Client 1 │ │ MCP Client 2 │ │ MCP Client 3 │ │
│ └───────┬───────┘ └───────┬───────┘ └───────┬───────┘ │
└───────────┼────────────────────────┼───────────────────────┼───────────┘
│ JSON-RPC over │ JSON-RPC over │ JSON-RPC over
│ stdio / HTTPS │ stdio / HTTPS │ stdio / HTTPS
▼ ▼ ▼
┌──────────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ MCP Server │ │ MCP Server │ │ MCP Server │
│ wraps HR system │ │ wraps Ticketing │ │ wraps Data │
│ (tools: lookup, │ │ (tools: create, │ │ Warehouse │
│ update) │ │ status, close) │ │ (tools: query) │
└──────────────────┘ └──────────────────┘ └─────────────────┘
4. 构建你的第一个MCP服务器（Node.js / TypeScript）
在“构建你的第一个项目”的第4阶段中，应在修改代码之前明确输入参数、该步骤的负责人以及结束标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 配置信息应置于应用程序代码之外。环境文件、密钥存储以及功能标志应集中存放于一个位置，这样操作人员无需查看整个系统结构即可进行审核。 在网关处进行身份验证，在数据层再次授权。仅凭承载令牌并不足以界定租户边界。
4.1 项目设置
在4 1项目的准备阶段，应在修改代码之前明确输入参数、该步骤的负责人以及终止标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 需同时记录正常流程和异常恢复流程。重试机制、人工审核环节以及错误处理都属于产品功能的一部分，而非后续需要补充的内容。 在网关处进行身份验证，在数据层再次授权。仅凭承载令牌并不足以界定租户边界。
mkdir helpdesk-mcp-server && cd helpdesk-mcp-server
npm init -y
npm install @modelcontextprotocol/sdk zod
npm install -D typescript tsx @types/node
npx tsc --init
在4 1项目的准备阶段，应在修改代码之前明确输入参数、该步骤的负责人以及终止标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 应将此阶段视为输入参数与经过验证的输出结果之间的契约。为相关成果命名，明确成功判定标准，杜绝默许部分完成的情况。
4.2 服务器代码
在处理“4.2 服务器阶段”时，首先需列出相关规范：所需输入参数、成功信号以及部分失败时的处理方式。这样的清单能确保后续的代码修改始终符合预期。 在功能结果旁记录执行时间以及令牌或查询成本。提前了解成本情况，可避免在从演示环境过渡到共享环境时出现意外费用。 需为每次调用记录工具名称、参数哈希值、延迟时间以及最终结果。没有这些记录，调试过程将会浪费大量时间。
// src/server.ts
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";
// --- A stand-in for a real internal ticketing API client ---
// In a real enterprise server this would call your ITSM system
// (ServiceNow, Jira Service Management, Zendesk, an internal API, etc.)
const ticketStore = new Map<string, { status: string; subject: string }>();
let nextId = 1000;
// 1. Create the server instance.
// "name" and "version" identify this server to any client that connects.
const server = new McpServer({
name: "helpdesk-mcp-server",
version: "1.0.0",
});
// 2. Register a tool: create_support_ticket
server.registerTool(
"create_support_ticket",
{
title: "Create Support Ticket",
description:
"Creates a new IT helpdesk ticket for the requesting employee.",
inputSchema: {
subject: z.string().describe("Short summary of the issue"),
priority: z.enum(["low", "medium", "high", "urgent"]),
employeeId: z.string().describe("Requesting employee's ID"),
},
outputSchema: {
ticketId: z.string(),
status: z.string(),
},
},
async ({ subject, priority, employeeId }) => {
const ticketId = `TCK-${nextId++}`;
ticketStore.set(ticketId, { status: "open", subject });
const output = { ticketId, status: "open" };
// MCP tool results return a "content" array (what a human/LLM reads)
// and, optionally, "structuredContent" (typed data other code can use).
return {
content: [
{
type: "text",
text: `Created ticket ${ticketId} (priority: ${priority}) for employee ${employeeId}.`,
},
],
structuredContent: output,
};
}
);
// 3. Register a second tool: get_ticket_status
server.registerTool(
"get_ticket_status",
{
title: "Get Ticket Status",
description: "Looks up the current status of an existing support ticket.",
inputSchema: {
ticketId: z.string(),
},
outputSchema: {
status: z.string(),
},
},
async ({ ticketId }) => {
const ticket = ticketStore.get(ticketId);
if (!ticket) {
// Returning isError lets the model know the call failed
// WITHOUT crashing the whole conversation.
return {
content: [{ type: "text", text: `No ticket found with ID ${ticketId}.` }],
isError: true,
};
}
return {
content: [{ type: "text", text: `Ticket ${ticketId} is currently "${ticket.status}".` }],
structuredContent: { status: ticket.status },
};
}
);
// 4. Wire the server to a transport and start listening.
// stdio is perfect for local development and desktop-hosted tools.
const transport = new StdioServerTransport();
await server.connect(transport);
4.3 这里实际发生了什么（逐行解析）
在处理“4 3 What’s”阶段时，首先写下契约内容：所需的输入参数、成功标志以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改保持一致性。 将配置信息与应用程序代码分开存放。环境文件、密钥存储以及功能开关应集中于一个位置，这样操作人员无需查看整个系统结构即可进行审计。 为每次调用记录工具名称、参数哈希值、延迟时间以及执行结果。如果没有这些记录，调试代理将陷入无止境的循环，耗费大量时间。
4.4 运行它
在处理“4 4 运行测试”阶段时，首先需明确相关约定：所需的输入参数、成功标志，以及部分失败时的处理方式。这份清单能确保后续的代码修改始终符合约定。 同时记录正常流程与异常恢复路径。重试机制、人工审核环节以及错误消息处理都是产品功能的一部分，而非后续需要补充的内容。 需为每次调用记录工具名称、参数哈希值、响应延迟及最终结果。没有这些记录，调试过程将会浪费大量时间。
npx tsx src/server.ts
在处理“4 4 运行测试”阶段时，首先需明确相关约定：所需的输入参数、成功标志，以及部分失败时的处理方式。这份清单能确保后续的代码修改始终符合约定。 应将此阶段视为输入参数与验证后输出结果之间的契约。为相关产物命名，明确成功判定标准，杜绝无声的半完成状态。
5. 在企业应用中构建MCP客户端
将“构建MCP”的五个阶段视为可衡量的指标会更为有效。在扩大范围之前，先记录一份最佳操作案例、一个故障案例以及回滚说明。同时将功能测试结果与耗时、令牌或查询成本一并记录下来。提前了解成本情况，就能避免在从演示环境过渡到共享环境时出现意外费用。
// src/client.ts
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
async function main() {
// 1. Describe how to launch the server. Here we spawn it as a
// local subprocess - in production you'd more commonly point
// this at a remote HTTP-based server instead (see Section 6).
const transport = new StdioClientTransport({
command: "npx",
args: ["tsx", "src/server.ts"],
});
// 2. Create a client and connect. This performs the MCP
// handshake and capability negotiation automatically.
const client = new Client({ name: "internal-ai-assistant", version: "1.0.0" });
await client.connect(transport);
// 3. Discover what tools this server offers - this is the same
// mechanism an LLM uses to "learn" what it can do.
const { tools } = await client.listTools();
console.log("Available tools:", tools.map((t) => t.name));
// 4. Call a tool, just like the LLM would.
const result = await client.callTool({
name: "create_support_ticket",
arguments: {
subject: "VPN keeps disconnecting",
priority: "high",
employeeId: "E-4821",
},
});
console.log(result.content);
await client.close();
}
main();
从概念层面看其重要性
从概念上讲，“为何这很重要”这一阶段若被视为可测量的对象会更为有效。在扩大范围之前，先记录一份典型的成功案例、一个失败案例以及回滚说明。 应将配置与应用程序代码分开。环境文件、密钥存储和功能开关应集中存放于一处，这样操作人员无需查看整个系统结构即可进行审计。 提供具有明确数据结构和清晰副作用标签的工具。主机需要在自动批准之前知道哪些调用会改变系统状态。
6. 从本地原型到企业级部署
在“6 From Local Prototype”阶段，将其视为可度量的对象来处理效果最佳。在扩大范围之前，需记录一份理想运行案例、一个故障案例以及回滚说明。 同时记录正常流程与恢复流程。重试机制、人工审核环节以及错误处理都是产品本身的组成部分，而非后续需要补充的内容。 应提供具有明确结构规范和清晰副作用标识的工具。主机需要在自动批准之前知道哪些调用会改变状态。 在“6 From Local Prototype”阶段，将其视为输入与经过验证的输出之间的契约。为相关成果命名，明确成功标准，绝不允许出现无声的半完成状态。
// src/httpServer.ts
import express from "express";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
const app = express();
app.use(express.json());
app.post("/mcp", async (req, res) => {
// In a real enterprise deployment, authentication middleware would
// run BEFORE this point - verifying a bearer token, checking scopes,
// and attaching the caller's identity to the request.
const server = buildHelpdeskServer(); // same registerTool calls as before
const transport = new StreamableHTTPServerTransport({
sessionIdGenerator: undefined, // stateless mode: simplest to scale horizontally
});
res.on("close", () => transport.close());
await server.connect(transport);
await transport.handleRequest(req, res, req.body);
});
app.listen(3000, () => console.log("MCP server listening on :3000"));
7. 企业级考量检查清单
在“7项企业级考量检查清单”阶段，应在修改代码之前明确输入参数、该步骤的负责人以及完成标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。应在功能结果旁记录执行时间以及令牌或查询成本。提前了解成本情况，可避免在系统从演示环境过渡到共享环境时出现意外账单。
8. 这些内容在实际企业应用中的体现
在“8 Where This Shows”阶段，应在修改代码之前明确输入参数、该步骤的负责人以及退出标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 配置信息应置于应用程序代码之外。环境文件、密钥存储以及功能标志应集中存放于一个位置，这样操作人员无需查看整个流程即可进行审计。 在网关处进行身份验证，在数据层再次授权。仅凭承载令牌并不足以界定租户边界。
9. 初学者常犯的错误
在“初学者面临的9个常见陷阱”阶段，修改代码之前需明确输入参数、该步骤的负责人以及终止标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 需同时记录正常流程与异常恢复路径。重试机制、人工审核环节以及错误处理都是产品本身的组成部分，而非后续需要补充的功能。 在网关处进行身份验证，在数据层再次授权。仅凭承载令牌并不足以界定租户边界。 在“初学者面临的9个常见陷阱”阶段，修改代码之前需明确输入参数、该步骤的负责人以及终止标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 应将此阶段视为输入参数与验证后输出结果之间的契约。为相关工件命名，明确成功判定标准，杜绝无声的半完成状态。
10. 总结
在完成“10. 总结”阶段时，首先写下相关契约：所需输入、成功信号以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改保持一致性。 在功能结果旁记录执行时间以及令牌或查询成本。提前了解成本情况，可避免在从演示环境过渡到共享环境时出现意外费用。 为每次调用记录工具名称、参数哈希值、延迟时间以及最终结果。没有这些记录，调试代理将陷入无休止的循环，耗费大量时间。
操作检查清单
在“操作检查清单”阶段，应在修改代码之前明确输入参数、该步骤的负责人以及终止标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏的状态。
应优先选择小型、可测试的单元，而非庞大的脚本。当某个步骤出错时，故障应指向单一责任模块，而非复杂的处理流程。
在网关处进行身份验证，在数据层进行重新授权。仅凭承载令牌无法界定租户边界。
编写简短的操作手册：说明如何轮换密钥、如何清空队列、以及如何回滚上一次的数据导入操作。
将此阶段视为输入数据与经过验证的输出结果之间的契约。为相关工件命名，明确成功标准，拒绝默许部分完成的状态。
在网关处进行身份验证，在数据层进行重新授权。仅凭承载令牌无法界定租户边界。
在推广该技术栈之前，应先冻结版本，为关键流程记录标准输出日志，并明确回滚步骤。共享环境需要设置速率限制、租户验证机制，以及负责密钥轮换的明确责任人。与其展示花哨的一次性演示，不如注重扎实的可靠性。
关于100916d5ed60的批注：请将提供商密钥移出代码仓库，设定单会话令牌上限，并将日志存储在评估用示例文件旁，以便后续模型更换时仍能保持对比性。