其它综合

关注公众号 jb51net

关闭
首页 > 网络编程 > 其它综合 > MCP协议与mcp.json配置文件

MCP协议与mcp.json配置文件详解(附详细代码)

作者：Rysxt

MCP是Anthropic开发的一个开放标准,旨在让AI模型,特别是大型语言模型,能够动态访问外部数据和工具,而不仅仅依赖预训练的静态知识,这篇文章主要介绍了MCP协议与mcp.json配置文件详解的相关资料,需要的朋友可以参考下

一、MCP协议概述

MCP（Model Context Protocol，模型上下文协议）是由Anthropic推出的开放标准协议，旨在为大型语言模型与外部工具、数据源之间建立标准化连接通道。它采用客户端-服务器架构，通过JSON-RPC 2.0协议实现通信，支持stdio、SSE、HTTP等多种传输方式。

​​核心价值​​：

二、mcp.json配置文件结构

mcp.json是MCP服务的核心配置文件，采用JSON格式定义服务器参数。基本结构如下：

{
  "mcpServers": {
    "server_name": {
      "type": "stdio",
      "command": "python",
      "args": ["server.py"],
      "env": {
        "API_KEY": "your_api_key"
      },
      "description": "服务器描述"
    }
  }
}

三、配置参数详解与对比

核心参数对比表

参数类别参数名称类型必需默认值说明适用传输类型
​​基础标识​​server_nameString是-服务器唯一标识符，如"filesystem"、"github"所有
​​传输方式​​typeString否自动推断通信协议类型所有
​​本地执行​​commandStringstdio必需-启动命令或可执行文件路径stdio
​​本地执行​​argsArray否[]命令行参数列表stdio
​​远程连接​​urlStringSSE/HTTP必需-远程服务器URL地址SSE/HTTP
​​远程连接​​headersObject否{}HTTP请求头信息SSE/HTTP
​​环境变量​​envObject否{}子进程环境变量stdio
​​权限控制​​alwaysAllowArray否[]预先授权的工具列表所有
​​状态控制​​disabledBoolean否false是否禁用此服务器所有
​​超时配置​​timeoutNumber否30000ms工具调用超时时间所有
​​超时配置​​initTimeoutNumber否10000ms服务器初始化超时时间所有
​​进程管理​​stderrString否"inherit"标准错误输出处理方式stdio
​​指令文档​​instructionsString否-服务器使用指南所有
​​认证凭据​​credentialsObject否-身份验证凭据配置所有

详细参数说明

1. 传输方式参数（type）

​​可选值​​：

​​配置示例​​：

{
  "type": "stdio",  // 本地进程通信
  "type": "sse",    // 远程SSE连接
  "type": "http"    // HTTP协议
}

2. 本地命令执行参数

​​command​​：要执行的命令或可执行文件路径，支持绝对路径或相对路径，支持环境变量引用（如$HOME、%USERPROFILE%）。

​​args​​：传递给命令的参数列表，按数组顺序传递，支持包含空格的参数。

​​示例​​：

{
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user"]
}

3. 远程服务器参数

​​url​​：远程MCP服务器的完整URL地址，必须包含协议（http://、https://、ws://、wss://），可以包含端口号。

​​headers​​：发送到远程服务器的HTTP头部信息，支持环境变量引用和用户字段占位符。

​​示例​​：

{
  "url": "https://api.example.com/mcp",
  "headers": {
    "Authorization": "Bearer ${API_TOKEN}",
    "X-Client-Version": "1.0.0"
  }
}

4. 环境变量参数（env）

为子进程设置的环境变量，支持系统环境变量、应用配置和运行时设置。

​​安全最佳实践​​：

​​示例​​：

{
  "env": {
    "API_KEY": "${MY_API_KEY}",
    "LOG_LEVEL": "info",
    "DATABASE_URL": "${DB_CONNECTION_STRING:-sqlite:///default.db}"
  }
}

5. 超时配置

​​timeout​​：单个工具调用的最大执行时间，包括网络请求的超时时间，不包括服务器初始化时间。

​​initTimeout​​：MCP服务器初始化的超时时间，包括进程启动、网络连接建立、握手协议完成等。

​​设置建议​​：

​​示例​​：

{
  "timeout": 60000,      // 60秒工具调用超时
  "initTimeout": 15000   // 15秒初始化超时
}

四、配置示例

示例1：本地文件系统服务器

{
  "mcpServers": {
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user"],
      "env": {},
      "timeout": 30000
    }
  }
}

示例2：远程GitHub工具服务器

{
  "mcpServers": {
    "github": {
      "type": "sse",
      "url": "https://api.github.com/mcp",
      "headers": {
        "Authorization": "Bearer ${GITHUB_TOKEN}",
        "Accept": "application/vnd.github.v3+json"
      },
      "timeout": 60000
    }
  }
}

示例3：Web搜索服务器

{
  "mcpServers": {
    "web-search": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@smithery/cli@latest", "run", "@smithery-ai/brave-search"],
      "env": {
        "BRAVE_API_KEY": "your_brave_api_key"
      },
      "description": "Web搜索工具"
    }
  }
}

五、配置位置与优先级

MCP配置文件支持多级配置，优先级从高到低：

​​合并规则​​：相同服务器名称后写覆盖先写，优先级local > project > global。

六、最佳实践

1. 安全配置

2. 性能优化

3. 监控与日志

4. 版本控制

七、常见问题与解决方案

问题可能原因解决方案
服务器无法启动端口被占用更改network.port配置，使用未被占用的端口
客户端无法连接主机地址配置错误检查network.host配置，确保客户端可访问
工具调用失败工具参数配置错误检查parameters配置，确保参数类型和必填项正确
资源访问被拒绝资源配置错误或权限不足检查template和list配置，确保资源路径正确
身份验证失败API密钥错误或配置不当检查authentication配置，确保API密钥正确

八、总结

MCP协议通过标准化的mcp.json配置文件，实现了AI模型与外部工具的无缝连接。掌握配置参数的含义和设置方法，能够帮助开发者构建高效、安全的MCP服务，为AI应用提供强大的扩展能力。建议在实际配置过程中，充分利用MCP Inspector等工具进行可视化验证，结合日志分析进行调试，并遵循最佳实践进行配置优化和安全加固。

到此这篇关于MCP协议与mcp.json配置文件详解的文章就介绍到这了,更多相关MCP协议与mcp.json配置文件内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家！

您可能感兴趣的文章:
阅读全文