MCP 集成深度指南

# STDIO 示例：Context7
[mcp_servers.context7]
command = "npx"                         # 启动命令
args = ["-y", "@upstash/context7-mcp"]  # 命令参数
​
[mcp_servers.context7.env]              # 环境变量
CONTEXT7_API_KEY = "your-api-key"

# Streamable HTTP 示例：GitHub MCP
[mcp_servers.github]
url = "https://api.githubcopilot.com/mcp/"  # 远程地址
# OAuth 认证：通过 codex mcp login github 完成

# 方式一：直接设置（值写在 config.toml 中）
[mcp_servers.my-tool.env]
API_KEY = "sk-xxx"           # 值明文写入配置
DATABASE_URL = "postgres://..."
​
# 方式二：从宿主环境转发（值来自系统环境变量）
[mcp_servers.my-tool]
command = "node"
args = ["server.js"]
env_vars = ["API_KEY", "DATABASE_URL"]  # 仅转发，不存储值

# 1. 添加远程 MCP
codex mcp add github --url https://api.githubcopilot.com/mcp/
​
# 2. 执行 OAuth 登录（浏览器弹窗授权）
codex mcp login github

# 固定回调端口（OAuth 提供商要求时使用）
mcp_oauth_callback_port = 5555
​
# 自定义回调 URL（远程开发机 / devbox 场景）
mcp_oauth_callback_url = "https://devbox.example.internal/callback"

[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_OAUTH_TOKEN"  # 从环境变量读取 Token
http_headers = { "X-Figma-Region" = "us-east-1" }  # 可选静态头

[mcp_servers.internal-api]
url = "https://internal.example.com/mcp"
# 静态头：值直接写入配置
http_headers = { "X-Team" = "platform", "X-Region" = "cn-east" }
# 动态头：值从环境变量读取
env_http_headers = { "Authorization" = "INTERNAL_API_TOKEN" }

# ① 添加 STDIO Server
codex mcp add context7 -- npx -y @upstash/context7-mcp
​
# ② 添加 Streamable HTTP Server
codex mcp add github --url https://api.githubcopilot.com/mcp/
​
# ③ OAuth 登录
codex mcp login github
​
# ④ 查看已配置列表
codex mcp list
# 输出示例：
#   context7     stdio    enabled
#   github       http     enabled
#   openai-docs  http     enabled
​
# ⑤ 临时禁用（编辑 config.toml）
# [mcp_servers.playwright]
# enabled = false
​
# ⑥ 移除不再需要的 Server
codex mcp remove playwright

# 场景一：GitHub MCP 只保留 Issue 和 PR 相关工具
[mcp_servers.github]
url = "https://api.githubcopilot.com/mcp/"
enabled_tools = [
    "list_issues",
    "create_issue",
    "get_pull_request",
    "create_pull_request",
    "list_pull_requests"
]
​
# 场景二：Playwright 禁用可能有安全风险的工具
[mcp_servers.playwright]
command = "npx"
args = ["@playwright/mcp@latest"]
disabled_tools = ["browser_execute_javascript", "browser_pdf"]
​
# 场景三：白名单 + 黑名单组合
[mcp_servers.chrome_devtools]
url = "http://localhost:3000/mcp"
enabled_tools = ["open", "screenshot", "navigate"]  # 先保留这 3 个
disabled_tools = ["screenshot"]  # 再从中移除 screenshot → 最终只有 open 和 navigate

[mcp_servers.example]
# === STDIO 服务器专用 ===
command = "npx"                        # 启动命令（必填）
args = ["-y", "@example/mcp"]          # 命令参数
cwd = "/path/to/project"               # 工作目录
env_vars = ["MY_SECRET"]               # 从宿主环境转发的变量
​
# === Streamable HTTP 服务器专用 ===
# url = "https://example.com/mcp"      # 服务器地址（必填）
# bearer_token_env_var = "MY_TOKEN"    # Bearer Token 环境变量名
# http_headers = { "X-Custom" = "value" }  # 静态 HTTP 头
# env_http_headers = { "Auth" = "ENV" }    # 动态 HTTP 头
​
# === 通用选项 ===
enabled = true                         # 是否启用（false 临时禁用）
# required = true                      # 启动时必须成功初始化
startup_timeout_sec = 10.0             # 启动超时（默认 10 秒）
tool_timeout_sec = 60.0                # 单次工具调用超时（默认 60 秒）
# enabled_tools = ["tool_a"]           # 工具白名单
# disabled_tools = ["tool_b"]          # 工具黑名单

# 基础启动
codex mcp-server
​
# 使用 MCP Inspector 调试
npx @modelcontextprotocol/inspector codex mcp-server

import asyncio
from agents import Agent, Runner
from agents.mcp import MCPServerStdio
​
async def main() -> None:
    async with MCPServerStdio(
        name="Codex CLI",
        params={
            "command": "npx",
            "args": ["-y", "codex", "mcp-server"],
        },
        client_session_timeout_seconds=360000,
    ) as codex_mcp_server:
        developer = Agent(
            name="Developer",
            instructions=(
                "You are an expert developer. "
                'Call codex with "approval-policy": "never" '
                'and "sandbox": "workspace-write".'
            ),
            mcp_servers=[codex_mcp_server],
        )
        designer = Agent(
            name="Designer",
            instructions="Design a 3-sentence brief, then hand off.",
            model="gpt-5",
            handoffs=[developer],
        )
        await Runner.run(designer, "Build a fun browser game!")
​
if __name__ == "__main__":
    asyncio.run(main())

# .agents/skills/my-skill/agents/openai.yaml
interface:
  display_name: "GitHub Workflow"
  short_description: "Automate GitHub PR and Issue management"
​
policy:
  allow_implicit_invocation: true
​
dependencies:
  tools:
    - type: "mcp"
      value: "github"                   # 对应 config.toml 中的 mcp_servers 名称
      description: "GitHub MCP server"
      transport: "streamable_http"
      url: "https://api.githubcopilot.com/mcp/"
    - type: "mcp"
      value: "openaiDeveloperDocs"
      description: "OpenAI Docs MCP server"
      transport: "streamable_http"
      url: "https://developers.openai.com/mcp"

codex mcp add context7 -- npx -y @upstash/context7-mcp

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
​
[mcp_servers.context7.env]
CONTEXT7_API_KEY = "your-api-key-here"

codex mcp add playwright -- npx @playwright/mcp@latest

codex mcp add github --url https://api.githubcopilot.com/mcp/
codex mcp login github

codex mcp add openai-docs --url https://developers.openai.com/mcp

# ===========================================================================
# MCP 服务器配置 — 全栈开发者精选版
# 原则：只装高频使用的，避免上下文浪费
# 文档：https://developers.openai.com/codex/mcp
# ===========================================================================
​
# ---------------------------------------------------------------------------
# 1. Context7 — 实时开发文档（STDIO）
# ---------------------------------------------------------------------------
[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
​
[mcp_servers.context7.env]
CONTEXT7_API_KEY = "your-api-key-here"
​
# ---------------------------------------------------------------------------
# 2. Playwright — 浏览器自动化（STDIO）
# ---------------------------------------------------------------------------
[mcp_servers.playwright]
command = "npx"
args = ["@playwright/mcp@latest"]
# 无头模式：args = ["@playwright/mcp@latest", "--headless"]
# 指定浏览器：args = ["@playwright/mcp@latest", "--browser", "firefox"]
​
# ---------------------------------------------------------------------------
# 3. GitHub — 平台深度集成（Streamable HTTP + OAuth）
# ---------------------------------------------------------------------------
[mcp_servers.github]
url = "https://api.githubcopilot.com/mcp/"
# 首次使用：codex mcp login github
​
# ---------------------------------------------------------------------------
# 4. OpenAI Docs — 开发者文档（Streamable HTTP，无需认证）
# ---------------------------------------------------------------------------
[mcp_servers.openai-docs]
url = "https://developers.openai.com/mcp"

# ---------------------------------------------------------------------------
# 5. Linear — 项目管理（Streamable HTTP + OAuth）
# 适用：使用 Linear 管理 Issue/Sprint 的团队
# ---------------------------------------------------------------------------
[mcp_servers.linear]
url = "https://mcp.linear.app/sse"
# 首次使用：codex mcp login linear
enabled_tools = [
    "list_issues",
    "create_issue",
    "update_issue",
    "list_projects"
]
tool_timeout_sec = 30
​
# ---------------------------------------------------------------------------
# 6. 自定义内部工具 — 企业内部 API（STDIO）
# 适用：封装内部 CLI / REST API 为 MCP Server
# ---------------------------------------------------------------------------
[mcp_servers.internal-deploy]
command = "node"
args = ["/opt/tools/deploy-mcp/server.js"]
cwd = "/opt/tools/deploy-mcp"
env_vars = ["DEPLOY_TOKEN", "REGISTRY_URL"]  # 从宿主环境转发
startup_timeout_sec = 15
tool_timeout_sec = 120          # 部署操作可能较慢
enabled_tools = ["deploy_staging", "rollback", "status"]
disabled_tools = ["deploy_production"]  # 生产部署需人工审批
​
# ---------------------------------------------------------------------------
# 7. 自定义内部工具 — 远程模式（Streamable HTTP + Bearer Token）
# ---------------------------------------------------------------------------
[mcp_servers.internal-api]
url = "https://mcp.internal.example.com/v1"
bearer_token_env_var = "INTERNAL_MCP_TOKEN"
http_headers = { "X-Team" = "platform" }
required = true                 # 该工具是核心依赖，启动时必须成功

#!/bin/bash
# Codex MCP 一键安装脚本
set -e
​
echo "=== Installing MCP Servers ==="
​
# STDIO Servers
codex mcp add context7 -- npx -y @upstash/context7-mcp
codex mcp add playwright -- npx @playwright/mcp@latest
​
# Streamable HTTP Servers
codex mcp add github --url https://api.githubcopilot.com/mcp/
codex mcp add openai-docs --url https://developers.openai.com/mcp
​
# OAuth Login
echo "\n=== OAuth Login ==="
codex mcp login github
​
# Verify
echo "\n=== Installed MCP Servers ==="
codex mcp list
​
echo "\n✅ All MCP servers configured successfully!"