{
  "id": "tool-calling-mcp",
  "module": "agents",
  "level": 2,
  "minutes": 25,
  "audiences": [
    "beginner",
    "developer",
    "researcher"
  ],
  "software": [
    "claude",
    "claude-code",
    "cherry-studio",
    "imcp",
    "peekaboo",
    "5ire"
  ],
  "text": {
    "en": {
      "title": "Tool Calling and MCP (Model Context Protocol) Explained",
      "description": "How LLM function calling works step by step, what the Model Context Protocol (MCP) standardises — hosts, clients, servers, tools, resources, prompts, transports, auth — how it relates to A2A, and how to write good tools for agents.",
      "updated": "2026-10-10",
      "takeaways": [
        "With tool calling, the model never runs code itself: it outputs a structured request (tool name + JSON arguments), your program executes it and returns the result.",
        "Tools are described by a name, a natural-language description and a JSON Schema for the parameters — the description is effectively a prompt and decides whether the model uses the tool correctly.",
        "MCP standardises how AI applications discover and call external tools and data, so one MCP server works in many clients (desktop assistants, IDEs, coding agents).",
        "MCP connects agents to tools and data; A2A connects agents to other agents. Both are now governed under the Linux Foundation's Agentic AI Foundation."
      ],
      "faq": [
        {
          "q": "What is the difference between function calling and MCP?",
          "a": "Function calling is a model capability: the model can emit structured tool-call requests in one API. MCP is an open protocol on top: it defines how an application discovers tools from external servers, calls them and receives results, so tools can be shared across apps and models."
        },
        {
          "q": "What is an MCP server?",
          "a": "A program that exposes tools (actions), resources (readable data) and prompts (templates) over MCP. It can run locally (started by the app and talking over stdio) or remotely over HTTP, e.g. a server for GitHub, a database, a file system or a browser."
        },
        {
          "q": "Is MCP only for Claude?",
          "a": "No. Anthropic introduced MCP in November 2024 as an open standard; it is now supported by many clients and model providers and, since December 2025, governed by the Agentic AI Foundation under the Linux Foundation."
        },
        {
          "q": "Are MCP servers safe?",
          "a": "They run code and can access data with your permissions, so treat them like any software you install: use trusted sources, least privilege, approval for sensitive actions, and be aware of tool poisoning and prompt injection."
        }
      ],
      "sources": [
        {
          "title": "OpenAI API docs, Function calling",
          "url": "https://platform.openai.com/docs/guides/function-calling"
        },
        {
          "title": "Anthropic docs, Tool use with Claude",
          "url": "https://docs.anthropic.com/en/docs/build-with-claude/tool-use/overview"
        },
        {
          "title": "Anthropic (2024), Introducing the Model Context Protocol",
          "url": "https://www.anthropic.com/news/model-context-protocol"
        },
        {
          "title": "Model Context Protocol, Specification",
          "url": "https://modelcontextprotocol.io/specification"
        },
        {
          "title": "Model Context Protocol, Architecture overview",
          "url": "https://modelcontextprotocol.io/docs/learn/architecture"
        },
        {
          "title": "Linux Foundation, Formation of the Agentic AI Foundation",
          "url": "https://www.linuxfoundation.org/press/linux-foundation-announces-the-formation-of-the-agentic-ai-foundation"
        },
        {
          "title": "A2A Protocol (Agent2Agent) documentation",
          "url": "https://a2a-protocol.org/"
        },
        {
          "title": "Anthropic Engineering (2025), Writing effective tools for agents",
          "url": "https://www.anthropic.com/engineering/writing-tools-for-agents"
        },
        {
          "title": "JSON-RPC 2.0 Specification",
          "url": "https://www.jsonrpc.org/specification"
        }
      ],
      "url": "https://aimap.page/en/learn/agents/tool-calling-mcp/",
      "markdown": "## Tool calling: how a model \"uses\" software\n\nAn LLM only produces tokens; it cannot open a file or call an API by itself. **Tool calling** (also called *function calling*) bridges the gap:\n\n1. Your application sends the model the conversation **plus a list of tools**, each with a name, a description and a JSON Schema for its parameters.\n2. If a tool would help, the model replies with a **structured tool call** instead of (or alongside) text: `{\"name\": \"get_weather\", \"arguments\": {\"city\": \"Shanghai\"}}`.\n3. **Your code** validates the arguments, executes the tool and sends the result back as a tool message.\n4. The model reads the result and either answers or calls another tool.\n\n```mermaid\nsequenceDiagram\n  participant App as Your application\n  participant LLM as Model\n  participant Tool as Tool / API\n  App->>LLM: messages + tool definitions (name, description, JSON Schema)\n  LLM-->>App: tool_call get_weather(city=\"Shanghai\")\n  App->>Tool: execute (after validation and permission check)\n  Tool-->>App: temp_c=21, sky=cloudy\n  App->>LLM: tool result\n  LLM-->>App: \"It is 21 °C and cloudy in Shanghai.\"\n```\n\nA tool definition looks like this (format varies slightly by provider — see the [OpenAI](https://platform.openai.com/docs/guides/function-calling) and [Anthropic](https://docs.anthropic.com/en/docs/build-with-claude/tool-use/overview) docs):\n\n```json\n{\n  \"name\": \"search_issues\",\n  \"description\": \"Search GitHub issues in one repository. Use for questions about bugs or feature requests. Returns at most 20 issues with number, title, state and URL.\",\n  \"input_schema\": {\n    \"type\": \"object\",\n    \"properties\": {\n      \"repo\":  { \"type\": \"string\", \"description\": \"owner/name, e.g. 'ollama/ollama'\" },\n      \"query\": { \"type\": \"string\", \"description\": \"keywords; supports 'is:open'\" }\n    },\n    \"required\": [\"repo\", \"query\"]\n  }\n}\n```\n\nThe model was trained to emit such calls; the **security boundary is your code**, which decides what actually runs.\n\n## Why a protocol was needed\n\nBefore MCP, every AI application integrated every tool separately: *M* apps × *N* tools = *M×N* custom integrations. The **Model Context Protocol (MCP)**, introduced by Anthropic in November 2024 ([announcement](https://www.anthropic.com/news/model-context-protocol)), makes it *M + N*: a tool provider writes one **MCP server**, and any MCP-capable application can use it. It is often described as \"USB-C for AI apps\".\n\n## MCP architecture\n\n```mermaid\nflowchart LR\n  subgraph Host[\"Host application (desktop assistant, IDE, coding agent)\"]\n    LLM[\"Model\"]\n    C1[\"MCP client\"]\n    C2[\"MCP client\"]\n  end\n  C1 <-->|\"stdio (local process)\"| S1[\"MCP server: files / git / browser\"]\n  C2 <-->|\"Streamable HTTP + OAuth\"| S2[\"Remote MCP server: SaaS / database\"]\n```\n\n- **Host** – the AI application the user runs; it contains the model loop and creates one **client** per server connection.\n- **Server** – exposes capabilities. Messages are **JSON-RPC 2.0**; servers run locally over **stdio** or remotely over **Streamable HTTP**, with an OAuth-based authorisation model for remote servers ([specification](https://modelcontextprotocol.io/specification)).\n\nServers offer three primitives ([architecture](https://modelcontextprotocol.io/docs/learn/architecture)):\n\n| Primitive | Controlled by | Example |\n|---|---|---|\n| **Tools** | the model (with user approval) | `create_issue`, `run_query`, `click` |\n| **Resources** | the application | file contents, database schema, docs |\n| **Prompts** | the user | reusable templates such as \"review this PR\" |\n\nClients can also offer features to servers, such as *sampling* (letting a server ask the host's model for a completion), *roots* (which folders a server may see) and *elicitation* (asking the user for input). On connection, client and server negotiate versions and capabilities; the client then lists the tools and passes their definitions to the model.\n\nMany apps listed on this site act as MCP hosts or servers — e.g. [Claude](/apps/claude), [Claude Code](/apps/claude-code), [Cherry Studio](/apps/cherry-studio) and [5ire](/apps/5ire) as clients; [iMCP](/apps/imcp) (macOS Messages, Contacts, Reminders, Calendar) and [Peekaboo](/apps/peekaboo) (screen capture) as servers.\n\n## MCP and A2A\n\nMCP connects an agent to **tools and data** (\"vertical\"). The **Agent2Agent protocol (A2A)**, started by Google, connects agents **to each other** (\"horizontal\"): an agent publishes an *Agent Card* describing its skills and endpoint, and other agents delegate tasks to it ([a2a-protocol.org](https://a2a-protocol.org/)). In December 2025 MCP was contributed to the newly formed **Agentic AI Foundation** under the Linux Foundation ([press release](https://www.linuxfoundation.org/press/linux-foundation-announces-the-formation-of-the-agentic-ai-foundation)), and A2A joined it in August 2026, so both are now vendor-neutral standards. More in [A2A and Multi-agent Systems](/learn/a2a-multi-agent).\n\n## Writing tools agents can actually use\n\nTool quality is one of the biggest levers on agent success ([How AI Agents Work](/learn/how-agents-work)). Practical rules, consistent with Anthropic's guidance on [writing tools for agents](https://www.anthropic.com/engineering/writing-tools-for-agents):\n\n1. **Describe purpose and limits** – when to use the tool, when not to, what it returns.\n2. **Fewer, task-shaped tools** beat thin wrappers around every API endpoint; avoid near-duplicates that confuse selection.\n3. **Clear parameter names, types, enums and examples** in the schema.\n4. **Return concise, relevant output** – paginate or filter; don't dump 10,000 lines into the context.\n5. **Actionable errors** – \"repo not found; expected 'owner/name'\" helps the model recover; a stack trace does not.\n6. **Least privilege and approvals** – read-only by default; destructive actions need confirmation. Tool descriptions themselves can be an attack vector ([Prompt Injection and Tool Poisoning](/learn/prompt-injection)).\n\n## Try it\n\nConnect a local MCP server to an MCP-capable desktop app, ask a question that requires it, and inspect the tool calls the app shows. Then read the server's tool descriptions: you are reading the prompt the model sees."
    },
    "zh-hans": {
      "title": "工具调用与 MCP（模型上下文协议）详解",
      "description": "大模型的函数调用一步步怎么工作，MCP 统一了什么（宿主、客户端、服务器、工具、资源、提示、传输方式、鉴权），它和 A2A 的关系，以及怎样为 Agent 写出好用的工具。",
      "updated": "2026-10-10",
      "takeaways": [
        "工具调用时，模型自己从不执行代码：它输出一个结构化请求（工具名 + JSON 参数），由你的程序执行并把结果送回去。",
        "工具由名称、自然语言描述和参数的 JSON Schema 定义；描述本质上就是提示词，决定了模型能不能用对这个工具。",
        "MCP 统一了 AI 应用发现和调用外部工具与数据的方式，一个 MCP 服务器可以在很多客户端里使用（桌面助手、IDE、编程 Agent）。",
        "MCP 连接 Agent 与工具和数据，A2A 连接 Agent 与 Agent；两者现在都由 Linux 基金会旗下的 Agentic AI Foundation 治理。"
      ],
      "faq": [
        {
          "q": "函数调用（function calling）和 MCP 有什么区别？",
          "a": "函数调用是模型的一种能力：在某个 API 里，模型可以输出结构化的工具调用请求。MCP 是建立在它之上的开放协议：规定应用如何从外部服务器发现工具、调用工具、取回结果，让工具可以在不同应用和模型之间共用。"
        },
        {
          "q": "MCP 服务器是什么？",
          "a": "一个通过 MCP 对外提供工具（动作）、资源（可读数据）和提示（模板）的程序。它可以在本地运行（由应用启动，通过 stdio 通信），也可以通过 HTTP 远程提供，比如 GitHub、数据库、文件系统、浏览器各自的服务器。"
        },
        {
          "q": "MCP 只能给 Claude 用吗？",
          "a": "不是。Anthropic 在 2024 年 11 月把 MCP 作为开放标准推出，如今已有大量客户端和模型厂商支持；2025 年 12 月起由 Linux 基金会旗下的 Agentic AI Foundation 治理。"
        },
        {
          "q": "MCP 服务器安全吗？",
          "a": "它们会运行代码，并以你的权限访问数据，所以要像对待任何安装的软件一样对待它：用可信来源、给最小权限、敏感操作要人工确认，并警惕工具投毒和提示注入。"
        }
      ],
      "sources": [
        {
          "title": "OpenAI API 文档，Function calling",
          "url": "https://platform.openai.com/docs/guides/function-calling"
        },
        {
          "title": "Anthropic 文档，Tool use with Claude",
          "url": "https://docs.anthropic.com/en/docs/build-with-claude/tool-use/overview"
        },
        {
          "title": "Anthropic（2024），Introducing the Model Context Protocol",
          "url": "https://www.anthropic.com/news/model-context-protocol"
        },
        {
          "title": "Model Context Protocol 规范",
          "url": "https://modelcontextprotocol.io/specification"
        },
        {
          "title": "Model Context Protocol，架构概览",
          "url": "https://modelcontextprotocol.io/docs/learn/architecture"
        },
        {
          "title": "Linux 基金会，成立 Agentic AI Foundation 的新闻稿",
          "url": "https://www.linuxfoundation.org/press/linux-foundation-announces-the-formation-of-the-agentic-ai-foundation"
        },
        {
          "title": "A2A（Agent2Agent）协议文档",
          "url": "https://a2a-protocol.org/"
        },
        {
          "title": "Anthropic Engineering（2025），Writing effective tools for agents",
          "url": "https://www.anthropic.com/engineering/writing-tools-for-agents"
        },
        {
          "title": "JSON-RPC 2.0 规范",
          "url": "https://www.jsonrpc.org/specification"
        }
      ],
      "url": "https://aimap.page/zh-hans/learn/agents/tool-calling-mcp/",
      "markdown": "## 工具调用：模型如何“使用”软件\n\n大模型只会输出 token，自己没法打开文件或调用 API。**工具调用**（也叫*函数调用*）就是连接两者的桥梁：\n\n1. 你的应用把对话**连同一份工具清单**发给模型，每个工具有名称、描述和参数的 JSON Schema。\n2. 如果某个工具有帮助，模型会回复一个**结构化的工具调用**（代替文字或和文字一起）：`{\"name\": \"get_weather\", \"arguments\": {\"city\": \"上海\"}}`。\n3. **你的代码**校验参数、执行工具，再把结果作为工具消息发回去。\n4. 模型读到结果，要么给出回答，要么继续调用下一个工具。\n\n```mermaid\nsequenceDiagram\n  participant App as 你的应用\n  participant LLM as 模型\n  participant Tool as 工具 / API\n  App->>LLM: 消息 + 工具定义（名称、描述、JSON Schema）\n  LLM-->>App: 工具调用 get_weather(city=\"上海\")\n  App->>Tool: 执行（先校验参数、检查权限）\n  Tool-->>App: temp_c=21, sky=cloudy\n  App->>LLM: 工具结果\n  LLM-->>App: \"上海现在 21 °C，多云。\"\n```\n\n一个工具定义大致长这样（各家格式略有不同，见 [OpenAI](https://platform.openai.com/docs/guides/function-calling) 和 [Anthropic](https://docs.anthropic.com/en/docs/build-with-claude/tool-use/overview) 的文档）：\n\n```json\n{\n  \"name\": \"search_issues\",\n  \"description\": \"在一个 GitHub 仓库里搜索 issue。用于回答关于 bug 或功能需求的问题。最多返回 20 条，包含编号、标题、状态和链接。\",\n  \"input_schema\": {\n    \"type\": \"object\",\n    \"properties\": {\n      \"repo\":  { \"type\": \"string\", \"description\": \"owner/name 格式，例如 'ollama/ollama'\" },\n      \"query\": { \"type\": \"string\", \"description\": \"关键词，支持 'is:open'\" }\n    },\n    \"required\": [\"repo\", \"query\"]\n  }\n}\n```\n\n模型经过训练会输出这样的调用；**安全边界在你的代码里**，由它决定什么真正被执行。\n\n## 为什么需要一个协议\n\nMCP 出现之前，每个 AI 应用都要逐个对接每个工具：*M* 个应用 × *N* 个工具 = *M×N* 套定制集成。Anthropic 在 2024 年 11 月推出的**模型上下文协议（MCP）**（[发布公告](https://www.anthropic.com/news/model-context-protocol)）把它变成 *M + N*：工具提供方写一个 **MCP 服务器**，任何支持 MCP 的应用都能用。它常被比作“AI 应用的 USB-C 接口”。\n\n## MCP 的架构\n\n```mermaid\nflowchart LR\n  subgraph Host[\"宿主应用（桌面助手、IDE、编程 Agent）\"]\n    LLM[\"模型\"]\n    C1[\"MCP 客户端\"]\n    C2[\"MCP 客户端\"]\n  end\n  C1 <-->|\"stdio（本地进程）\"| S1[\"MCP 服务器：文件 / git / 浏览器\"]\n  C2 <-->|\"Streamable HTTP + OAuth\"| S2[\"远程 MCP 服务器：SaaS / 数据库\"]\n```\n\n- **宿主（Host）**：用户运行的 AI 应用，里面有模型循环，并为每个服务器连接创建一个**客户端**。\n- **服务器（Server）**：对外提供能力。消息格式是 **JSON-RPC 2.0**；服务器可以在本地通过 **stdio** 运行，也可以通过 **Streamable HTTP** 远程提供，远程服务器使用基于 OAuth 的授权机制（[规范](https://modelcontextprotocol.io/specification)）。\n\n服务器提供三种基本能力（[架构说明](https://modelcontextprotocol.io/docs/learn/architecture)）：\n\n| 能力 | 由谁控制 | 例子 |\n|---|---|---|\n| **工具（Tools）** | 模型（经用户批准） | `create_issue`、`run_query`、`click` |\n| **资源（Resources）** | 应用 | 文件内容、数据库表结构、文档 |\n| **提示（Prompts）** | 用户 | 可复用的模板，比如“审查这个 PR” |\n\n客户端也可以向服务器提供能力，比如 *sampling*（让服务器请宿主的模型生成内容）、*roots*（服务器能看到哪些文件夹）、*elicitation*（向用户询问输入）。连接建立时，双方协商版本和能力；客户端随后列出工具，把它们的定义交给模型。\n\n本站收录的不少软件就是 MCP 宿主或服务器：例如 [Claude](/apps/claude)、[Claude Code](/apps/claude-code)、[Cherry Studio](/apps/cherry-studio)、[5ire](/apps/5ire) 是客户端；[iMCP](/apps/imcp)（macOS 的信息、通讯录、提醒事项、日历）和 [Peekaboo](/apps/peekaboo)（截屏与画面分析）是服务器。\n\n## MCP 与 A2A\n\nMCP 把 Agent 连接到**工具和数据**（“纵向”）。由 Google 发起的 **Agent2Agent 协议（A2A）** 把 Agent **彼此**连接起来（“横向”）：一个 Agent 发布 *Agent Card*，描述自己的技能和接入地址，其他 Agent 就可以把任务委派给它（[a2a-protocol.org](https://a2a-protocol.org/)）。2025 年 12 月，MCP 被捐给 Linux 基金会新成立的 **Agentic AI Foundation**（[新闻稿](https://www.linuxfoundation.org/press/linux-foundation-announces-the-formation-of-the-agentic-ai-foundation)），A2A 也在 2026 年 8 月加入，两者都成了厂商中立的标准。详见 [A2A 与多 Agent 协作](/learn/a2a-multi-agent)。\n\n## 怎样写出 Agent 真正用得好的工具\n\n工具质量是决定 Agent 成败的最大因素之一（见 [AI Agent 工作原理](/learn/how-agents-work)）。下面这些实用原则，与 Anthropic 关于 [为 Agent 编写工具](https://www.anthropic.com/engineering/writing-tools-for-agents) 的建议一致：\n\n1. **写清用途和边界**：什么时候用、什么时候不用、返回什么。\n2. **少而精、按任务设计的工具**，胜过给每个 API 端点套一层薄包装；避免功能几乎重复、让模型难以选择的工具。\n3. **在 Schema 里写清参数名、类型、枚举值和示例。**\n4. **返回精简、相关的输出**：分页或过滤，别把一万行内容倒进上下文。\n5. **可操作的报错**：“仓库不存在，应为 'owner/name' 格式”能帮模型自我纠正，一段堆栈信息则不能。\n6. **最小权限与人工确认**：默认只读，破坏性操作需要确认。工具描述本身也可能成为攻击入口（见 [提示注入与工具投毒](/learn/prompt-injection)）。\n\n## 动手试试\n\n把一个本地 MCP 服务器接入支持 MCP 的桌面应用，问一个必须用到它的问题，再查看应用显示的工具调用记录。然后读一读这个服务器的工具描述：你读到的，正是模型看到的提示词。"
    }
  }
}