使用说明

带HTTP传输的MCP服务器

一个Python MCP（模型上下文协议）服务器，支持stdio和HTTP/SSE传输，并具有可选的OAuth2身份验证。

特性

双传输支持：stdio和HTTP，带服务器发送事件（SSE）
可选的OAuth2身份验证有两种模式：
- 内置OAuth：服务器发行自己的令牌（演示/开发）
- 外部OIDC：通过自省端点（生产）验证令牌
两个工具： list_profiles 和 get_titans
Titan角色攻击演示数据
JSON格式的响应
基于环境的配置

安装

pip install -r requirements.txt

快速开始

选项1：不使用OAuth（简单）

python server.py

在ChatGPT中配置：

{
  "name": "Demo MCP Server",
  "url": "http://127.0.0.1:8000/sse"
}

选项2：内置OAuth（演示/开发）

生成OAuth2凭据：

python generate_credentials.py

启动服务器：

python server.py

使用OAuth2设置在ChatGPT中配置（请参阅下面的配置部分）

选项3：与外部OIDC提供商（生产）合作

配置外部OIDC提供程序（Keycloak、Auth0、Okta等）
创建 .env 文件：

OAUTH_ENABLED=true
OAUTH_MODE=external
OIDC_INTROSPECTION_ENDPOINT=https://auth.example.com/oauth/introspect
OIDC_CLIENT_ID=mcp-server-client-id
OIDC_CLIENT_SECRET=mcp-server-client-secret

启动服务器：

python server.py

配置ChatGPT以指向您的外部OIDC提供商

用法

HTTP/SSE传输（默认）

使用HTTP传输运行服务器：

python server.py
# Or explicitly:
python server.py --transport sse --host 127.0.0.1 --port 8000

服务器将在以下位置可用：

SSE端点： http://127.0.0.1:8000/sse
消息端点： http://127.0.0.1:8000/messages/

标准运输

使用stdio传输运行服务器：

python server.py --transport stdio

配置

OAuth模式

服务器支持两种OAuth模式：

模式	描述	用例
`builtin`	服务器发行自己的令牌	演示、开发、小型部署
`external`	通过自检验证令牌	生产、企业、SSO

模式1：内置OAuth（默认）

用于演示和开发目的。服务器处理完整的OAuth流。

# .env file
OAUTH_ENABLED=true
OAUTH_MODE=builtin
OAUTH_CLIENT_ID=chatgpt-mcp-xxxxxxxxxxxx
OAUTH_CLIENT_SECRET=your-secret-here
SERVER_HOST=127.0.0.1
SERVER_PORT=8000
USE_HTTPS=false

自动生成凭据：

python generate_credentials.py

ChatGPT配置：

{
  "name": "Demo MCP Server",
  "url": "http://127.0.0.1:8000/sse",
  "description": "Demo server with built-in OAuth",
  "auth": {
    "type": "oauth2",
    "authorization_url": "http://127.0.0.1:8000/oauth/authorize",
    "token_url": "http://127.0.0.1:8000/oauth/token",
    "client_id": "chatgpt-mcp-xxxxxxxxxxxx",
    "client_secret": "your-secret-here",
    "scope": "read write"
  }
}

模式2：外部OIDC提供者（令牌自检）

用于生产部署。服务器使用令牌自检端点验证来自外部OIDC提供者的令牌。

# .env file
OAUTH_ENABLED=true
OAUTH_MODE=external

# Token Introspection Configuration
OIDC_INTROSPECTION_ENDPOINT=https://auth.example.com/oauth/introspect
OIDC_CLIENT_ID=mcp-server-client-id
OIDC_CLIENT_SECRET=mcp-server-client-secret

# Server Configuration
SERVER_HOST=127.0.0.1
SERVER_PORT=8000

ChatGPT配置：

{
  "name": "Demo MCP Server",
  "url": "http://127.0.0.1:8000/sse",
  "description": "MCP server with external OIDC",
  "auth": {
    "type": "oauth2",
    "authorization_url": "https://auth.example.com/oauth/authorize",
    "token_url": "https://auth.example.com/oauth/token",
    "client_id": "chatgpt-client-id",
    "client_secret": "chatgpt-client-secret",
    "scope": "openid profile read write"
  }
}

注： OAuth URL指向您的 外部供应商，而不是MCP服务器！

提供商特定示例

钥匙锁

OAUTH_MODE=external
OIDC_INTROSPECTION_ENDPOINT=https://keycloak.example.com/realms/myrealm/protocol/openid-connect/token/introspect
OIDC_CLIENT_ID=mcp-server
OIDC_CLIENT_SECRET=your-secret-here

身份验证0

OAUTH_MODE=external
OIDC_INTROSPECTION_ENDPOINT=https://yourtenant.auth0.com/oauth/introspect
OIDC_CLIENT_ID=mcp-server-client-id
OIDC_CLIENT_SECRET=your-secret-here

八月

OAUTH_MODE=external
OIDC_INTROSPECTION_ENDPOINT=https://yourorg.okta.com/oauth2/default/v1/introspect
OIDC_CLIENT_ID=mcp-server-client-id
OIDC_CLIENT_SECRET=your-secret-here

适用于克劳德桌面（HTTP/SSE）

在 claude_desktop_config.json:

{
  "mcpServers": {
    "demo-mcp-server": {
      "url": "http://127.0.0.1:8000/sse"
    }
  }
}

适用于克劳德桌面（Stdio）

{
  "mcpServers": {
    "demo-mcp-server": {
      "command": "python",
      "args": ["/path/to/server.py", "--transport", "stdio"]
    }
  }
}

可用工具

list_profiles

列出服务器上所有可用的配置文件。

参数： 无

退货： 配置文件对象的JSON数组 profile_id 和 name 领域

示例响应：

[
  {
    "profile_id": "eren",
    "name": "Eren Yeager"
  },
  {
    "profile_id": "mikasa",
    "name": "Mikasa Ackerman"
  }
]

获取它

获取特定配置文件的巨头。

参数：

profile_id （string，必填）：获取titans的配置文件ID

退货： 指定配置文件的带titans的JSON对象

成功响应示例：

{
  "profile_id": "eren",
  "titans": [
    "founding",
    "war hammer"
  ],
  "status": "success"
}

错误响应示例：

{
  "profile_id": "unknown",
  "status": "error",
  "error": "Profile not found"
}

演示数据

服务器包括对Titan角色进行攻击的演示数据：

eren -埃伦·耶格尔（创始和战锤巨人）
mikasa -Mikasa Ackerman（进攻巨人）

测试

测试令牌反思

使用附带的测试脚本验证您的OIDC配置：

# Test introspection endpoint
python test_oidc_token.py introspect --token "your-token-here" \
  --introspection-url https://auth.example.com/oauth/introspect \
  --client-id mcp-server --client-secret secret

# Test token with MCP server
python test_oidc_token.py test --token "your-token-here" --server http://127.0.0.1:8000

# Test OIDC discovery
python test_oidc_token.py discover --issuer https://auth.example.com

定制

替换中的演示数据和逻辑 server.py:

DATA 词典 -替换为实际数据源（数据库、文件、API）
list_profiles() -修改以返回您的个人资料格式
get_titans(profile_id) -修改以返回您的数据格式

故障排除

服务器未连接

检查服务器是否正在运行： curl http://127.0.0.1:8000/sse
验证URL是否准确 http://127.0.0.1:8000/sse
检查防火墙是否允许端口8000

工具未出现

检查服务器日志是否有错误
即使在UI中不可见，工具也应该工作
试着直接问：“列出个人资料”或“为艾伦找到巨人”

OAuth/OIDC问题

“令牌自检请求超时”

检查自检端点URL
验证网络连接
检查客户端凭据是否正确

“令牌未激活”

令牌可能已过期
令牌可能已被撤销
检查令牌是由正确的提供者颁发的

身份验证失败

验证 OIDC_CLIENT_ID 和 OIDC_CLIENT_SECRET 是正确的
检查自检端点是否支持基本身份验证
验证您的MCP服务器客户端是否具有自检权限

OAuth2详细信息

内置OAuth模式

它是如何工作的：

ChatGPT将用户重定向到 /oauth/authorize
服务器自动批准（演示模式）并返回授权码
ChatGPT在以下位置交换访问令牌代码 /oauth/token
ChatGPT包括 Bearer {token} 在所有MCP请求中
服务器根据内存存储验证令牌

安全说明：

⚠️ 自动批准仅用于演示-在生产中实施正确的登录/同意
⚠️ 存储在内存中的令牌-使用数据库进行生产
⚠️ 使用HTTPS进行生产设置 USE_HTTPS=true 当位于HTTPS代理/负载均衡器之后时
✓ 客户端机密存储在 .env （不支持git）

外部OIDC模式（令牌自检）