MCP 服务器

MCP 服务器是 LLM 智能体的主要交互点。它将所有配置的 API 作为 MCP 工具暴露给 LLM 调用。

配置

mcp:
  transport: stdio

传输方式

三种传输方式可用：

传输方式	描述	何时使用
stdio	标准输入/输出	本地 LLM 客户端（VS Code、Cursor、Claude Desktop）
sse	服务器发送事件	远程客户端、基于 HTTP 的通信
streamable-http	带流式传输的 HTTP	Web 客户端、现代 MCP 客户端

stdio（默认）

LLM 客户端将 swag2mcp 作为子进程运行。通信通过标准输入和输出进行。不需要网络端口。

mcp:
  transport: stdio

swag2mcp mcp

SSE

用于基于 HTTP 通信的服务器发送事件传输。MCP 服务器监听 HTTP 端口，LLM 客户端远程连接。

mcp:
  transport: sse
  addr: "127.0.0.1:8080"
  path: "/mcp"

swag2mcp mcp --transport sse --http-addr 127.0.0.1:8080

Streamable HTTP

支持流式响应的现代 HTTP 传输。类似于 SSE，但使用不同的协议。

mcp:
  transport: streamable-http
  addr: "127.0.0.1:8080"
  path: "/mcp"

swag2mcp mcp --transport streamable-http --http-addr 0.0.0.0:8080

参数

transport

• 类型： string
• 默认值： "stdio"
• 选项： stdio、sse、streamable-http
• 效果： 确定 MCP 服务器如何与 LLM 客户端通信。

addr

• 类型： string
• 默认值： ":8080"
• 描述： SSE 和 Streamable HTTP 传输的监听地址。格式：host:port。
• 示例： ":8080"、"127.0.0.1:8080"、"0.0.0.0:9000"

path

• 类型： string
• 默认值： "/mcp"
• 描述： MCP 端点的 URL 路径。LLM 客户端发送请求到 http://<addr><path>。
• 示例： "/mcp"、"/api/mcp"、"/v1/mcp"

auth.token

• 类型： string
• 默认值： ""（无认证）
• 描述： HTTP 传输认证的 Bearer 令牌。设置后，LLM 客户端必须在每个请求中包含 Authorization: Bearer <token>。
• 注意： 支持 $(ENV_VAR) 解析。

auth.type

• Type: string
• Default: "" (no JWT auth)
• Options: jwks, oidc, introspection
• Description: JWT authentication type for HTTP transport. When set, enables dynamic token verification using JWKS, OIDC Discovery, or token introspection.

auth.jwks_url

• Type: string
• Default: ""
• Description: URL of the JWKS (JSON Web Key Set) endpoint. Required when auth.type is jwks or resolved via OIDC discovery.

auth.issuer

• Type: string
• Default: ""
• Description: Expected JWT issuer (iss claim). If set, tokens with a different issuer are rejected.

auth.audience

• Type: string
• Default: ""
• Description: Expected JWT audience (aud claim). If set, tokens without this audience are rejected.

auth.introspection_url

• Type: string
• Default: ""
• Description: Token introspection endpoint URL. Required when auth.type is introspection.

auth.client_id

• Type: string
• Default: ""
• Description: Client ID for introspection auth. Required when auth.type is introspection.

auth.client_secret

• Type: string
• Default: ""
• Description: Client secret for introspection auth. Supports $(ENV_VAR) resolution.

HTTP 认证

使用 bearer 令牌保护 MCP HTTP 端点：

mcp:
  auth:
    token: "my-secret-token"

或通过 CLI 标志：

swag2mcp mcp --auth-token "my-secret-token"

With JWT authentication (JWKS)

Protect the MCP HTTP endpoint with JWT verification via a JWKS endpoint:

mcp:
  auth:
    type: jwks
    jwks_url: "https://auth.example.com/.well-known/jwks.json"
    issuer: "https://auth.example.com/"
    audience: "swag2mcp"

swag2mcp mcp --transport sse --http-addr 0.0.0.0:8080 \
  --auth-type jwks \
  --auth-jwks-url "https://auth.example.com/.well-known/jwks.json" \
  --auth-issuer "https://auth.example.com/" \
  --auth-audience "swag2mcp"

With JWT authentication (OIDC Discovery)

mcp:
  auth:
    type: oidc
    issuer: "https://auth.example.com/"
    audience: "swag2mcp"

With JWT authentication (Token Introspection)

mcp:
  auth:
    type: introspection
    introspection_url: "https://auth.example.com/introspect"
    client_id: "my-client"
    client_secret: "$(MCP_CLIENT_SECRET)"

swag2mcp mcp --transport sse --http-addr 0.0.0.0:8080 \
  --auth-type introspection \
  --auth-introspection-url "https://auth.example.com/introspect" \
  --auth-client-id "my-client" \
  --auth-client-secret "$(MCP_CLIENT_SECRET)"

健康检查

MCP 服务器提供无需 MCP 初始化即可工作的健康检查端点：

curl http://127.0.0.1:8080/health
# {"status":"ok","version":"v1.2.0"}

启动标志

CLI 标志覆盖 YAML 配置。如果未设置标志，则使用 YAML 中 mcp 部分的值作为回退。

标志	类型	默认值	描述
--transport	string	"stdio"	传输类型：stdio、sse、streamable-http
--http-addr	string	":8080"	HTTP 服务器地址（用于 SSE 和 Streamable HTTP）
--http-path	string	"/mcp"	MCP 处理程序的 URL 路径
--auth-token	string	""	HTTP 传输认证的 Bearer 令牌
--logfile	string	""	日志文件路径（未设置时输出到 stderr）
--disable-llm-auth	bool	true	从 MCP 工具列表中移除 auth 工具
--dump-dir	string	""	用于调试的 HTTP 请求转储目录
--tags	string	""	按标签过滤 spec（逗号分隔）
--auth-type	string	""	JWT auth type: jwks, oidc, introspection
--auth-jwks-url	string	""	JWKS URL for JWT auth
--auth-issuer	string	""	JWT issuer for token validation
--auth-audience	string	""	JWT audience for token validation
--auth-introspection-url	string	""	Token introspection URL
--auth-client-id	string	""	Client ID for introspection auth
--auth-client-secret	string	""	Client secret for introspection auth