HTTP 传输方式¶
通过 HTTP 暴露 MCP 服务器。为远程部署、多客户端场景,以及服务器作为长期运行 服务运行的生产环境而设计。
运行¶
MCP_TRANSPORT=http uv run python -m novelai_image_mcp serve
# or via the CLI flag:
uv run python -m novelai_image_mcp serve --transport http
服务器默认绑定到 127.0.0.1:8000/mcp。可用 MCP_HOST / MCP_PORT /
MCP_PATH 覆盖:
MCP_TRANSPORT=http \
MCP_HOST=0.0.0.0 \
MCP_PORT=9000 \
MCP_PATH=/mcp \
uv run python -m novelai_image_mcp serve
URL¶
完整的端点 URL 是:
http://${MCP_HOST}:${MCP_PORT}${MCP_PATH}
智能体配置¶
MCP 客户端配置(mcpServers)¶
在 docker compose up --build(或任何其他 HTTP 部署)之后,用 http 类型
把你的 MCP 宿主指向该 URL:
{
"mcpServers": {
"novelai-image-http": {
"type": "http",
"url": "http://127.0.0.1:8000/mcp",
"headers": {
"Authorization": "Bearer <MCP_AUTH_TOKEN>"
}
}
}
}
把 http://127.0.0.1:8000/mcp 换成你自行部署的端点(例如置于 TLS 终止反向
代理之后的 https://mcp.example.com/mcp)。
Authorization 头不是 NovelAI token:服务器用自己的 NOVELAI_TOKEN 与
NovelAI 通信。只有当服务器上设置了 MCP_AUTH_TOKEN 时这个头才有意义,此时
它必须与之匹配(Authorization: Bearer <MCP_AUTH_TOKEN>)。在没有
MCP_AUTH_TOKEN(也没有 MCP_ROUTE_TOKENS)时,端点会接受未认证的客户端
—— 请把它置于 TLS 与反向代理之后,或让 MCP_HOST 保持 localhost。
自定义 Python 智能体¶
import asyncio
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client
async def main():
async with streamablehttp_client("http://localhost:8000/mcp") as (read, write, _):
async with ClientSession(read, write) as session:
await session.initialize()
tools = await session.list_tools()
print([t.name for t in tools])
asyncio.run(main())
Curl(调试)¶
streamable-http 传输方式用 Server-Sent Events 承载服务器 → 客户端的消息。 用一条原始 HTTP 请求来查看服务器:
curl -X POST http://localhost:8000/mcp \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}'
Insiders 头与路由¶
HTTP 是唯一能携带 opt-in 头的传输方式,所以路由相关的接口都放在这里。客户端
逐请求用 X-MCP-Insiders opt-in,并用路由头声明自己的 route:
{
"mcpServers": {
"novelai-image-http": {
"type": "http",
"url": "http://127.0.0.1:8000/mcp",
"headers": {
"Authorization": "Bearer <MCP_AUTH_TOKEN>",
"X-MCP-Insiders": "true",
"X-MCP-Agent-ID": "team-a",
"X-MCP-Model": "nai-diffusion-5-full"
}
}
}
}
带上该头之后,服务器会解析出一个 route(这里是 team-a),把生成的图像写到
<NOVELAI_OUTPUT_DIR>/team-a/,向 novelai_image_mcp.audit.team-a logger
输出一行,并向审计 JSONL 追加一条记录。不带该头时什么都不变 —— 没有作用域
目录,也没有审计文件。
opt-in 同时门控 director_tool 的实验性 emotion / emotion_level 参数;
没有 opt-in 时,传入任意一个都会以 ToolError 失败。
头语法、候选头列表、审计记录字段、脱敏规则与扩展点见 Insiders 头、路由与审计。
按路由绑定的 token¶
MCP_AUTH_TOKEN 仍是单个静态 token。MCP_ROUTE_TOKENS 增加了绑定到 route 的
token,这样一个网关就能给不同团队发放不同的密钥:
MCP_AUTH_TOKEN=static-token
MCP_ROUTE_TOKENS='{"team-a":"token-for-team-a","team-b":"token-for-team-b"}'
路由 token 以其 route 的身份认证;当同一请求通过路由头声明了另一个 route 时,
它会被以 401 拒绝。未声明任何可用 route 的请求会被接受,并归属到该 token 的
route;只有两个不同且都存在的 route 才会 fail closed。两者都未配置时,不会安装
任何认证中间件,端点行为与从前一致。
Docker 部署¶
最简单的生产部署:
docker compose up --build
仓库根目录的
docker-compose.yml
用合理的默认值配置了 streamable-http 传输方式:
services:
mcp:
build:
context: .
dockerfile: apps/server/Dockerfile
ports:
- "8000:8000"
environment:
MCP_TRANSPORT: streamable-http
MCP_HOST: 0.0.0.0
MCP_PORT: 8000
NOVELAI_OUTPUT_DIR: /app/outputs
volumes:
- novelai-outputs:/app/outputs
healthcheck 每 30 秒探测一次绑定端口(默认 8000)。
生产环境检查清单¶
警告
传输方式本身不带认证。 MCP_AUTH_TOKEN(与 MCP_ROUTE_TOKENS)在 MCP
端点前面加了一道 bearer 校验,但那只是一个共享密钥,不是身份提供方 —— 而且
路由头由客户端提供,可以被伪造。在把服务器暴露到互联网之前,请把它置于:
TLS 终止(Caddy、nginx、Traefik、AWS ALB)之后
认证层(mTLS、OAuth 代理、API 网关)之后
限流器(防止 Anlas 被滥用)之后
小技巧
本地多客户端使用时绑定 localhost。 如果你只需要同一台机器上的多个智能体
(例如一个 Python 智能体和一个 Node 智能体),设置 MCP_HOST=127.0.0.1
并跳过 TLS。只有跨网络边界时才需要反向代理。
输出目录
在 Docker 中,NOVELAI_OUTPUT_DIR=/app/outputs 由一个命名卷
(novelai-outputs)支撑。生成的图像在容器重启后仍然保留。在 Kubernetes 中,
请把该卷替换为 PersistentVolumeClaim。
并发模型¶
服务器使用单个共享的
httpx.AsyncClient(连接池)。多个并发的工具调用共用 该连接池 —— 没有逐请求的 HTTP 开销。每个 MCP 请求都在服务器事件循环上运行于自己的 asyncio task 中。
服务器不对请求排队或限流 —— 那是上游代理的职责。