夜雨聆风
AI Agent开发必懂:Skill调用MCP原理+实操一步到位
现在做AI开发，早就不是单纯调大模型API、写几行Prompt就能搞定生产级项目了。
很多开发者做完Demo都会遇到同一个痛点：大模型本身再强，连不上数据库、读不了业务文件、调不通内部API，就永远只能停留在“聊天玩具”阶段。
想要让AI真正落地办公、运维、数据查询、业务自动化场景，必须吃透两个核心概念：Skill（智能体技能流程） 和 MCP（Model Context Protocol 模型上下文协议）。
不少新手开发者经常搞混：Skill和MCP到底啥关系？为什么两个都要配？Skill怎么才能正常调用MCP？配置完为啥提示“没有可用数据库MCP工具”？
今天这篇文章，不讲空话、不堆概念，从核心定位、底层原理、完整调用流程、实操配置、常见报错排查，一次性讲透Skill调用MCP全逻辑，AI开发人手必备收藏。
壹、 先搞懂核心定位：Skill和MCP分工完全不同
很多人踩坑的根源，就是把Skill和MCP混为一谈，以为二选一就行，其实二者是各司其职、强弱搭配、缺一不可的黄金组合。
🔹 MCP：AI智能体的「通用USB-C接口」
MCP全称Model Context Protocol（模型上下文协议），是Anthropic推出的AI标准化外部连接协议，业内公认AI时代的通用USB-C接口。
它的核心作用只有一个：统一AI模型和外部系统的通信标准。
不管你要连接SQL Server、MySQL、本地文件、飞书企业应用、第三方业务API、运维服务器，不需要每对接一个工具就写一套定制胶水代码。
只要适配MCP标准，一次配置、处处调用，完美解决AI对接外部服务碎片化、兼容性差、维护麻烦的痛点。
简单总结MCP：只管“有没有能力”，不管“怎么用能力”。
👉 相当于AI的手脚和感官，负责底层连接、工具注册、指令执行。
🔹 Skill：AI智能体的「标准化工作流剧本」
Skill是AI Agent的业务技能编排层，以标准化文档（SKILL.md）为载体，专门用来定义业务流程。
它不做任何底层连接、不写数据库连接字符串、不处理接口签名，只专注三件事：
-
这个业务要做什么
-
执行步骤先后顺序
-
需要调用哪个MCP工具、传什么参数、拿到结果后怎么处理
简单总结Skill：只管“怎么干活”，不管“工具怎么连”。
👉 相当于AI的工作手册和执行大脑，负责流程编排、逻辑调度、任务串联。
🔹 核心关系一句话讲清
MCP负责造枪（提供能力），Skill负责瞄准开枪（调度使用）。
没有MCP，Skill无工具可用；没有Skill，MCP有能力没人调度，没法落地复杂业务。
贰、 底层调用原理：Skill调用MCP核心全链路
Skill调用MCP不是复杂黑盒，整个链路只有4步，所有AI Agent框架、Claude Code、Claude Desktop全部通用。
✅ 第一步：配置MCP，注册外部工具能力
开发者提前在配置文件中，配置好各类外部服务的MCP服务信息（比如查询天气、文件读写权限、API对接参数）。
系统启动后，MCP服务自动初始化，把天气查询、文件读取等能力注册成可被AI调用的标准化工具，随时待命。
✅ 第二步：编写Skill，声明依赖MCP工具
创建业务Skill工作流，在Skill头部明确声明：当前这个业务流程，依赖哪个MCP服务、需要调用哪个工具函数。
比如做天气查询的Skill，就必须声明依赖天气查询的MCP工具，不声明就无法关联调用。
✅ 第三步：Agent匹配Skill，解析MCP调用指令
用户下发业务指令后，AI Agent自动匹配对应的Skill工作流，逐行读取Skill中的执行步骤，精准解析出：
-
要调用哪个MCP服务
-
执行哪个具体工具方法
-
需要传递哪些业务参数
✅ 第四步：MCP执行操作，结果回传给Skill闭环
Agent通过MCP客户端发送标准化调用请求，MCP服务执行数据库查询、文件操作等任务，执行完成后把结果原路返回。
Skill接收返回数据，继续执行后续业务逻辑，整理结果输出给用户，全链路闭环、全程无需人工干预。
叁、 极简实操落地：Skill调用查询天气 MCP 示范
1、准备MCP
以Spring Boot工程为例进行说明，工程目录如下
pom.xml
Spring AI MCP 服务端核心依赖spring-ai-starter-mcp-server-webflux，让 Spring Boot 项目变成 MCP 服务端，自动注册工具、自动处理 AI 调用请求。
<?xml version="1.0" encoding="UTF-8"?>
<projectxmlns="http://maven.apache.org/POM/4.0.0"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>3.4.2</version>
<relativePath/><!-- lookup parent from repository -->
</parent>
<groupId>com.example</groupId>
<artifactId>mcp-server</artifactId>
<version>0.0.1-SNAPSHOT</version>
<name>mcp-server</name>
<description>demo</description>
<url/>
<licenses>
<license/>
</licenses>
<developers>
<developer/>
</developers>
<scm>
<connection/>
<developerConnection/>
<tag/>
<url/>
</scm>
<properties>
<java.version>17</java.version>
</properties>
<dependencies>
<dependency>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
<optional>true</optional>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-webflux</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-mcp-server-webflux</artifactId>
<version>1.0.1</version>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
<configuration>
<excludes>
<exclude>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
</exclude>
</excludes>
</configuration>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<executions>
<execution>
<id>default-compile</id>
<phase>compile</phase>
<goals>
<goal>compile</goal>
</goals>
<configuration>
<annotationProcessorPaths>
<path>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
</path>
</annotationProcessorPaths>
</configuration>
</execution>
<execution>
<id>default-testCompile</id>
<phase>test-compile</phase>
<goals>
<goal>testCompile</goal>
</goals>
<configuration>
<annotationProcessorPaths>
<path>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
</path>
</annotationProcessorPaths>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
<repositories>
<repository>
<id>spring-milestones</id>
<name>Spring Milestones</name>
<url>https://repo.spring.io/milestone</url>
<snapshots>
<enabled>false</enabled>
</snapshots>
</repository>
</repositories>
</project>
application.yaml
spring:
application:
name:mcp-server
ai:
mcp:
server:
name:mcp-serverMCP服务名称（AI看到的名字）
version:1.0.0# 版本
type:sync# 同步调用（最常用）
WeatherService.java
MCP 工具实现。
核心注解说明
-
@Tool标记方法 = MCP 工具AI 能看到工具名、描述、参数 -
@ToolParam告诉 AI：参数含义、是否必填 -
ToolContext可选，AI 对话上下文（如用户 ID、对话 ID 等）
package com.example.demo.service;
import lombok.extern.slf4j.Slf4j;
import org.springframework.ai.chat.model.ToolContext;
import org.springframework.ai.tool.annotation.Tool;
import org.springframework.ai.tool.annotation.ToolParam;
import org.springframework.stereotype.Service;
import org.springframework.web.client.RestClient;
import java.util.Map;
@Slf4j
@Service
publicclassWeatherService{
privatefinal RestClient restClient;
publicWeatherService(){
this.restClient = RestClient.create();
}
@Tool(description = "可以获取到某个城市的天气信息")
public Map<String, String> getTemperature(@ToolParam(required = true, description = "入参城市，请传入城市拼音") String city,
ToolContext toolContext) {
System.out.println("获取到了城市信息:" + city);
return Map.of("datas", city + "的天气为大雪，温度为零下5度到零下10度");
}
}
McpServerConfig
自动扫描类中所有@Tool方法，注册成 MCP 可用工具，Claude 等 AI 客户端可以自动发现并调用。
package com.example.demo.config;
import com.example.demo.service.WeatherService;
import org.springframework.ai.tool.ToolCallbackProvider;
import org.springframework.ai.tool.method.MethodToolCallbackProvider;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
@Configuration
publicclassMcpServerConfig{
@Bean
public ToolCallbackProvider weatherTools(WeatherService weatherService){
return MethodToolCallbackProvider.builder()
.toolObjects(weatherService)
.build();
}
}
2、MCP核心配置（.mcp.json）
在工程根目录下创建.mcp.json文件，并配置MCP服务
{
"mcpServers": {
"filesystem": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-filesystem",
"C:/Users/XXX/Documents",
"C:/Users/XXX/Desktop"
],
"env": {}
},
"my-mcp-server": {
"type": "sse",
"url": "http://IP:端口/sse"
}
}
}
3、Skill核心编写规则（关键）
Skill无需复杂代码，核心就两点：头部声明依赖MCP，步骤内写调用参数。
Skill头部必须绑定MCP服务名，执行步骤中标准化调用天气查询能力。
---
name: weather
description: 当用户询问天气时，要求用户输入城市，查询城市天气后，返回给用户
dependencies:
- mcp: my-mcp-server # 依赖 MCP 工具名
tools:
- name: getTemperature
mcp: my-mcp-server # 绑定到 MCP 服务
function: getTemperature # MCP 工具方法
---
# 步骤
1. 用户询问天气时，要求用户输入城市名
2. 调用`getTemperature`查询天气信息
3. 查询后的信息不要进行任何加工，直接返回给用户
4、生效关键动作
配置修改完成后，必须彻底退出Claude Code所有进程，重新启动生效，只关窗口不重启，配置永远不生效，必然报错无可用MCP工具。
肆、 高频报错速解：没有可用的数据库MCP工具
开发中最常见报错：当前环境中没有可用的数据库 MCP 工具来查询。
不是代码问题，全是配置和操作问题，按以下顺序排查秒修复：
-
配置文件路径错误：必须写入官方指定Claude配置目录，不要新建、不要放错文件夹
-
未彻底重启客户端：必须退出托盘进程，仅关闭窗口配置不加载
-
Skill未声明MCP依赖：Skill头部没绑定 MCP服务，Agent识别不到可用工具