Auth Example

MCP HTTP服务器

基于HTTP的模型上下文协议（MCP）服务器实现，支持OAuth2/JWT身份验证。

特性

• MCP协议支持：实现模型上下文协议（MCP）规范（v2025-06-18）
• OAuth2/JWT身份验证：使用AuthAction进行安全身份验证
• HTTP传输：用于MCP通信的RESTful API端点
• 流式HTTP传输：MCP检查器的服务器发送事件支持
• 工具系统：具有内置工具的可扩展工具框架
• 根系：MCP Inspector的文件系统根支持
• 健康监测：内置健康检查和监控端点

内置工具

1. 回声：回显输入文本
2. 时间：获取当前服务器时间
3. 计算：执行基本的数学计算

快速开始

先决条件

• Node.js 16.0.0或更高版本
• npm或纱线

安装

1. 克隆存储库：

git clone 
cd mcp-server

1. 安装依赖项：

npm install

1. 创建一个 .env 使用您的配置文件：

# Server Configuration
PORT=3000
APP_DOMAIN=http://localhost

# AuthAction Configuration
AUTHACTION_DOMAIN=tenant-name.tenant-region.authaction.com
AUTHACTION_AUDIENCE=your-authaction-api-identifier

1. 启动服务器：

npm start

对于自动重启的开发：

npm run dev

API终点

公共端点

• GET / -服务器信息和可用端点
• GET /health -健康检查端点
• GET /.well-known/oauth-authorization-server -OAuth2授权服务器元数据
• GET /.well-known/oauth-protected-resource -OAuth2受保护的资源元数据

受保护的端点

• POST /mcp -MCP协议端点（需要JWT身份验证）
• POST /mcp/stream -StreamableHTTP MCP端点（对于MCP检查器，需要JWT身份验证）

MCP协议

服务器实现以下MCP方法：

initialize

初始化MCP连接并协商协议版本。

请求：

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "initialize",
  "params": {}
}

答复：

{
  "jsonrpc": "2.0",
  "id": 0,
  "result": {
    "protocolVersion": "2025-06-18",
    "capabilities": {
      "tools": {},
      "sampling": {},
      "roots": {
        "listChanged": true
      }
    },
    "serverInfo": {
      "name": "mcp-server",
      "version": "1.0.0"
    }
  }
}

tools/list

列出可用工具。

请求：

{
  "jsonrpc": "2.0",
  "id": "2",
  "method": "tools/list",
  "params": {}
}

答复：

{
  "jsonrpc": "2.0",
  "id": "2",
  "result": {
    "tools": [
      {
        "name": "echo",
        "description": "Echo back the input text",
        "inputSchema": {
          "type": "object",
          "properties": {
            "text": {
              "type": "string",
              "description": "Text to echo back"
            }
          },
          "required": ["text"]
        }
      }
    ]
  }
}

roots/list

列出可用的文件系统根目录。

请求：

{
  "jsonrpc": "2.0",
  "id": "3",
  "method": "roots/list",
  "params": {}
}

答复：

{
  "jsonrpc": "2.0",
  "id": "3",
  "result": {
    "roots": [
      {
        "name": "default",
        "uri": "file:///",
        "description": "Default file system root"
      }
    ]
  }
}

tools/call

执行一个工具。

请求：

{
  "jsonrpc": "2.0",
  "id": "3",
  "method": "tools/call",
  "params": {
    "name": "echo",
    "arguments": {
      "text": "Hello, World!"
    }
  }
}

答复：

{
  "jsonrpc": "2.0",
  "id": "3",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Echo: Hello, World!"
      }
    ]
  }
}

认证

MCP的主要终点(/mcp)需要JWT身份验证。在Authorization标头中包含JWT令牌：

Authorization: Bearer 

两个MCP端点都需要JWT身份验证以确保安全性和一致性。

JWT配置

服务器使用以下配置验证JWT：

• 发行人: https://{AUTHACTION_DOMAIN}/
• 观众: {AUTHACTION_AUDIENCE}
• 算法：RS256
• JWKS端点: https://{AUTHACTION_DOMAIN}/.well-known/jwks.json

项目结构

mcp-server/
├── src/
│   ├── server.js              # Main Express server setup
│   ├── mcp-handler.js         # MCP protocol handler
│   ├── streamable-http-handler.js # StreamableHTTP handler
│   └── tools.js               # Tool definitions and handlers
├── index.js                   # Entry point
├── test-client.js             # Test client
├── package.json               # Dependencies and scripts
└── README.md                  # Documentation

添加自定义工具

要添加自定义工具，请修改 src/tools.js 文件：

1. 将工具定义添加到 tools 数组：

{
  name: "my-tool",
  description: "Description of my tool",
  inputSchema: {
    type: "object",
    properties: {
      // Define your tool's parameters
    },
    required: ["required-param"]
  }
}

1. 将工具处理程序添加到 toolHandlers 对象：

my-tool: async (args) => {
  // Implement your tool logic
  return {
    content: [
      {
        type: "text",
        text: "Tool result"
      }
    ]
  };
}

测试

运行测试客户端以验证服务器功能：

npm test

这将测试所有端点并验证身份验证要求。

环境变量

错误处理

服务器使用标准错误代码实现了正确的JSON-RPC 2.0错误处理：

• -32700：分析错误
• -32600：无效请求
• -32601：未找到方法
• -32602：无效参数
• -32603：内部错误

安全考虑

1. JWT验证：所有MCP请求都需要有效的JWT令牌
2. 速率限制：JWKS请求受到速率限制，以防止DoS攻击
3. 输入验证：所有工具输入都根据模式进行验证
4. 错误处理：敏感信息不会在错误消息中暴露