概览
通过 Model Context Protocol 将代码代理连接到您的 Glossia 项目。
Glossia 提供一个 模型上下文协议 (MCP) 服务器，使编码代理能够与您的本地化项目进行交互。该服务器实现了 OAuth 2.1 与 PKCE 及动态客户端注册 (RFC 7591)，因此任何兼容 MCP 的客户端均可进行身份验证，无需手动设置凭据。
MCP 服务器提供的功能
连接后，编码代理可以：
- 查询您所有项目的翻译状态
- 触发翻译和修订
- 检查配置和内容条目
- 访问项目上下文以获取更智能的代码建议
服务器 URL
| 环境 | URL |
|---|---|
| 生产 | https://glossia.ai/mcp |
| 本地开发 | http://localhost:4050/mcp |
认证流程
MCP 服务器使用带有 PKCE 的标准 OAuth 2.1 授权码流程。您无需手动创建 OAuth 客户端。流程如下：
- 代理通过此方式发现您的服务器
/.well-known/oauth-authorization-server - 代理作为 OAuth 客户端通过动态注册端点注册自身
- 代理打开您的浏览器以进行登录和授权同意
- 在您批准后，代理会接收访问令牌并将其附加到所有 MCP 请求中
将 Glossia 添加到编程代理
OpenAI Codex
将服务器添加到您的 Codex 配置文件位置 ~/.codex/config.toml:
[mcp_servers.glossia]
url = "https://glossia.ai/mcp"
然后运行 OAuth 登录：
codex mcp login glossia
您的浏览器将打开以进行身份验证。批准后，Codex 会在本地存储令牌并用于后续会话。
验证连接：
codex mcp list
本地开发时，替换 URL：
[mcp_servers.glossia-local]
url = "http://localhost:4050/mcp"
Claude Code
将服务器添加到您的 Claude Code MCP 设置（.claude/settings.json 或全局设置文件）：
{
"mcpServers": {
"glossia": {
"url": "https://glossia.ai/mcp",
"transport": "streamable-http"
}
}
}
首次连接时，Claude Code 将自动处理 OAuth 流程。
其他 MCP 客户端
任何支持以下 MCP 授权规范 均可使用。关键要求如下：
- 传输：流式 HTTP
- 发现：客户端必须支持 OAuth 2.0 受保护资源元数据 (RFC 9728)
- 注册：动态客户端注册 (RFC 7591) 或 客户端 ID 元数据文档
- 认证流程: 使用 PKCE (S256) 的授权码
将客户端指向您的 Glossia MCP 服务器 URL，并让它自动处理发现和注册。
发现端点
服务器发布两个元数据文档，MCP 客户端使用它们来启动 OAuth 流程：
| 端点 | 描述 |
|---|---|
/.well-known/oauth-authorization-server |
授权服务器元数据（端点、支持的授权类型、PKCE 方法） |
/.well-known/oauth-protected-resource |
受保护资源元数据（范围、授权服务器） |
速率限制
OAuth 端点实施速率限制以防止滥用：
| 端点 | 限制 |
|---|---|
POST /oauth/register |
5 每分钟请求 |
POST /oauth/token |
30 每分钟请求 |
POST /oauth/introspect |
30 每分钟请求 |
POST /oauth/revoke |
每分钟 30 次请求 |
当速率限制被超过时，服务器返回 HTTP 429 及一个 Retry-After 标头。
故障排除
注册失败，错误为 "invalid_client_metadata"
动态注册端点仅接受特定 token_endpoint_auth_method 值。公开客户端（大多数编码代理）应发送 "none", Glossia 会自动处理，通过回退到默认身份验证方法并强制执行 PKCE。
"OAuth 回调无效" 审批后
确保您的 Glossia 服务器正在运行，且可在您配置的 URL 处访问。回调发生在代码代理临时打开的本地端口上。防火墙或 VPN 有时会阻止此通信。
令牌交换失败
请检查 code_challenge_methods_supported 字段是否存在于授权服务器元数据中。服务器必须支持 S256 协议以确保 PKCE 正常工作。Glossia 默认已包含此支持。
代理无法连接服务器
进行本地开发时，请确保 Phoenix 服务器正在运行（mix phx.server），并监听预期的端口（默认：4050）。MCP 端点必须可被代理进程访问。