Speko AI

spekoai-mcp

适用于 SpekoAI 的 FastMCP v4 服务。托管端点为：

https://mcp.speko.ai/mcp

它接受使用 OAuth 或 Speko Platform API 密钥进行身份验证的 POST 请求。配置 URL，然后让客户端协商协议；不要手动添加协议标头：

Authorization: Bearer <OAuth access token or sk_live_xxx>
Content-Type: application/json

该传输方式是无状态且仅支持 JSON 的。现代客户端直接使用 MCP 2026-07-28；Cursor 等采用握手的客户端通过 initialize 协商 MCP 2025-11-25。两条路径均无需会话：没有 Mcp-Session-Id、SSE 响应、本地 OAuth 事务存储或 stdio 传输。Better Auth 负责授权、许可、刷新令牌和客户端注册；MCP 服务仅在每个请求中验证已签名的访问令牌。

客户端设置

使用直接 HTTP 安装程序并选择 OAuth（默认的交互式选项）：

npx @spekoai/mcp@latest init

也可以直接配置支持 OAuth 的客户端。例如，Codex 读取：

[mcp_servers.speko]
url = "https://mcp.speko.ai/mcp"

如需自动化，请导出 Platform API 密钥并添加 bearer 设置：

[mcp_servers.speko]
url = "https://mcp.speko.ai/mcp"
bearer_token_env_var = "SPEKO_API_KEY"

工具界面

托管工具界面绑定到主机名；profile 查询参数会被忽略。主端点通过领域/操作名称提供运维工具：

• 账户：organization.get、credits.balance.get、 credits.ledger.list、usage.summary.get；
• Agent：agents.list、agents.preview_stacks、agents.create、 agents.get、agents.update、agents.delete，以及部署、版本、工具和监控操作；
• 会话和通话：创建、列出、检查、查看转录、录音和测试通话操作；
• 电话号码，包括自带运营商： phone_numbers.sip_connections.create 用于连接客户的 SIP 中继，phone_numbers.import 用于关联通过该中继接入的号码，无需 SIP 网关或支持工单；
• 自定义语音：voice_clones.create 将录音链接中的语音克隆到 ElevenLabs、Cartesia、MiniMax 或 CSM，其提供商语音 ID 可用于 audio.synthesize；voice_clones.list、.provision 和 .delete；
• 知识库、评估、迁移辅助工具、音频辅助工具和 docs.search。

构建器配置

应用构建者使用以下精选主机：

https://builder-mcp.speko.ai/mcp

它包含文档搜索、目录、Agent 读取、堆栈预览、集成代码片段、测试通话审核路径，以及受限的 agents.create 和 agents.test_call 写入操作。生成的应用在运行时使用 Speko SDK；它们不会调用 MCP 工具。

Replit 配置

Replit 使用自己的主机：

https://replit.speko.ai/mcp

它按构建时顺序提供 28 个工具——code_snippets.get、语音和模型目录、文档搜索及堆栈预览优先，然后是 Agent、号码和转录读取，最后是写入操作。它加入了构建器配置中省略的两条路径：知识库，让语音常见问题解答有地方存放；以及电话号码，这是应用内助手可用后的下一项需求。网关操作、评估、监控、场景、账单、API 密钥、迁移和所有破坏性删除操作均不包含在内。

助手目录主机

助手目录发布在各自独立的主机上，每个主机都遵循对应目录的策略。工具界面由主机决定：没有任何查询参数、标头或账户设置可以扩大其范围。

Anthropic MCP Directory

https://anthropic.speko.ai/mcp

提供账户范围内的读取、语音转文本、外呼，以及只读的电话合规诊断：

• 账户：organization.get、credits.balance.get、credits.ledger.list、 usage.summary.get；
• Agent：agents.list、agents.get、agents.preview_stacks、 agents.versions.list、agents.tools.list、agents.tools.get、 agents.calls.list、agents.test_call.get；
• 会话和通话：sessions.list、sessions.get、 sessions.transcript.get、sessions.recording.get、calls.get、 calls.recording.get；
• 电话号码：phone_numbers.list、phone_numbers.get、 phone_numbers.available.search；
• 知识库：knowledge_bases.list、knowledge_bases.get、 knowledge_bases.documents.list、knowledge_bases.documents.get；
• 评估和监控：evals.get、agents.monitoring.results.list；
• 音频：audio.transcribe；
• 拨打电话：sessions.phone.create — 每次工具调用拨打一个外呼电话，并由 服务端注入 AI 声明。ChatGPT 和连接器调用默认有严格的 5 分钟上限；如需更改， 请明确设置 body.maxDurationSeconds（S2S 为 30–3600 秒，cascade 最高为 14400 秒）；
• 挂断：sessions.end — 使用 session_id 立即请求挂断。 可以安全地重复调用。ending 响应表示请求已确认；使用 sessions.get 确认会话已结束；
• 合规：phone_numbers.kyb.get — OAuth 连接器授权和声明提交会在后端自动完成；
• 迁移辅助工具：migration.workspace.inspect、 migration.external_config.parse、migration.session_config.build、 migration.briefing.render；
• 其他：docs.search。

以下工具有意不在此主机上，因为每个工具要么会按需生成合成语音， 要么会为之后执行相关操作做准备：

分组	不提供的工具
音频生成	audio.synthesize
实时会话／通话创建	sessions.create、agents.test_call
Agent 配置和部署	agents.create、agents.update、agents.deploy、agents.rollback、agents.tools.create、agents.tools.update、agents.tools.delete
知识库写入	knowledge_bases.create、knowledge_bases.documents.create、knowledge_bases.documents.delete、knowledge_bases.documents.finalize
电话号码配置	phone_numbers.create、phone_numbers.update
批量或定时评估	agents.evals.*、agents.monitors.*
不可撤销及面向外部的写入	agents.delete、phone_numbers.delete、knowledge_bases.delete、share_cards.create

配置 Agent 就等同于为其做好启动准备：已部署的 Agent 无需进一步调用工具， 就会在入站流量中开口说话。因此，Agent 创建、更新、部署和回滚操作与生成工具 本身一样，不予提供。audio.transcribe 予以保留，因为语音转文字不会生成音频， 只会返回文本。

此主机有意提供 sessions.phone.create。每次明确调用工具时，它都会拨打一个电话 给一个号码，使用客户在其他地方部署的 Agent——没有批量、定时或无人值守的调用方式， 且呼叫者无法配置实际通话的 Agent。目录主机创建的每通电话都会由服务端注入 AI 声明：第一句话会说明呼叫者是 AI，而且无法通过提示词让 Agent 隐瞒这一点。 只能读取通话记录、却无法发起通话的界面是查看器，而非连接器。 sessions.create（浏览器会话令牌，在聊天客户端中毫无用处）和 agents.test_call（让两个合成 Agent 彼此通话）均不提供。 最后一行被移除的原因不同。删除操作会移除能力，而不是启用任何功能，因此这些工具不受上述规则约束；但已发布的接口必须能用一句诚实的话描述，而由于这里包含三个不可逆的删除操作和一个公共页面创建工具，因此不能将其称为只读接口。phone_numbers.delete 还会释放一个计费号码。所有四种资源的读取操作仍然保留。在此主机上调用被扣留的工具会返回 Unknown tool: '<name>'，与从未注册过的工具名称返回的结果相同。

OpenAI Plugin Directory

https://chatgpt.speko.ai/mcp

21 个工具。 这是单独的一份列表，并非复用 Anthropic 的列表，因为两个目录禁止的内容不同：OpenAI 不限制生成音频，因此保留 audio.synthesize 和外呼功能；而其关于销售数字商品的规则会移除电话号码配置功能以及积分和用量读取功能。其中三个读取工具是为了避免 agents.test_call 成为死胡同：审查测试通话需要使用 agents.test_call.get 获取运行的会话 ID，使用 agents.calls.list 在运行结果被覆盖时找回该 ID，并使用 calls.recording.get 获取音频。

身份验证和下游调用

OAuth 客户端会通过 MCP 受保护资源元数据发现 Better Auth。Better Auth 会签发绑定到确切 MCP 资源 URL 的 JWT 访问令牌。MCP 服务会在每次请求时验证令牌的签名、颁发者、受众、有效期和作用域，且不会保留 OAuth 或协议状态。

产品级 Platform API 密钥会在每次请求时通过 GET /v1/auth/api-key-context 单独验证。Speko API 工具会原样转发 API 密钥。对于 OAuth 调用方，MCP 服务会签发一个独立的、绑定到 Platform API 的 60 秒 JWT；它绝不会转发客户端提供的 MCP 令牌。

配置：

• SPEKOAI_API_URL — Platform API 源站，默认为 https://api.speko.dev；
• SPEKOAI_ROUTER_URL — Speko Router 源站，默认为 https://router.speko.dev。 audio.transcribe 和 audio.synthesize 会优先使用 Router；当 Router 无法处理请求时，则回退到 Platform 端点。对于没有 Speko API 密钥的会话，两者都会回退，因为 Router 通过 API 密钥进行身份验证，而不接受 OAuth 委托令牌。对于 WAV/PCM 以外的任何容器格式，audio.transcribe 也会回退，因为 Router 无法解码这些格式。当请求正文包含 Router 语音请求正文无法表达的内容时，audio.synthesize 会回退：speed、instructions、spokenForm、单独的 model、intent.region，或多个允许的提供方；
• SPEKOAI_OAUTH_ISSUER — Better Auth 颁发者，例如 https://platform.speko.ai/api/auth；
• SPEKOAI_MCP_BASE_URL — 用于派生确切资源受众的公共 MCP 源站；
• SPEKOAI_MCP_DELEGATION_SECRET — 仅与 Platform 共享的 32 个字符以上密钥，用于无状态 API 委托；
• SPEKOAI_MCP_DEFAULT_PROFILE — 仅用于部署的工具接口，在裸路径 /mcp 上提供（builder | connector | chatgpt | customer）。 托管服务会显式设置此项；公共查询参数无法选择或覆盖它。 未设置时，本地和可自托管使用会保留旧版完整接口。

部署顺序、冒烟测试和故障诊断，请参阅 docs/fastmcp-v4.md。