MCP 与 AI 工具

连接你的 AI 助手复制链接

将 SMSPVA 文档 MCP 添加到 AI 客户端，即可在开发时查询 API 方法和代码示例。服务由 SMSPVA 托管，无需下载项目、安装 Node.js 或 Docker，也无需提供 SMSPVA API 密钥。

在支持 Streamable HTTP 远程 MCP 的客户端中，填写以下完整地址：

https://mcp.smspva.com/docs

在客户端的 MCP 设置中，使用上述信息添加远程服务，保存后启用或重新连接。若出现服务信任提示，请先查看内容再确认。将下方示例合并到现有配置中，不要覆盖其他服务。

此 MCP 只搜索和读取公开文档，并返回代码示例。它不能购买号码、读取你的私人短信或邮件，也不能修改账户。API MCP 是另一项独立服务，详见本页后半部分。两者均不包含 Alternative API。

Codex复制链接

在 Codex 的 config.toml 中添加以下配置。如果已有指向本地进程的 mcp_servers.smspva_docs，请将该条目替换为 URL 配置，不要重复添加同名表。保留独立的 API 连接 mcp_servers.smspva。

[mcp_servers.smspva_docs]
url = "https://mcp.smspva.com/docs"
startup_timeout_sec = 20
tool_timeout_sec = 45

重新连接服务或重启 Codex 会话以应用更改。该条目不需要 command、args、env 或令牌。配置文件位置及客户端操作方式见 Codex 官方 MCP 指南。

Cursor复制链接

将以下配置添加到项目内的 .cursor/mcp.json，或用户目录中的 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "smspva_docs": {
      "url": "https://mcp.smspva.com/docs"
    }
  }
}

在 Cursor 的 MCP 设置中启用服务。更多说明见 Cursor 官方 MCP 指南。

VS Code复制链接

在命令面板运行 MCP: Add Server，选择 HTTP，输入 https://mcp.smspva.com/docs，并将服务标识设为 smspva_docs。选择配置保存位置，并查看服务信任提示。工作区 .vscode/mcp.json 的等效配置如下：

{
  "servers": {
    "smspva_docs": {
      "type": "http",
      "url": "https://mcp.smspva.com/docs"
    }
  }
}

配置格式可能因所选代理提供方而异。请参阅 VS Code 配置指南和配置参考。

在对话中试用复制链接

连接后，请明确让 AI 助手使用 SMSPVA 文档 MCP。例如：

• “使用 SMSPVA 文档 MCP，给我一个查询余额的 Python 示例，用中文解释，不要执行代码。”
• “在西班牙文文档中查找 Private Email 的供应商查询方法，并返回 JavaScript 请求示例。”
• “阅读中文版 Rental 流程，解释如何激活租赁并获取消息。”

连接成功后，应能看到四个工具：smspva_docs_search、smspva_docs_read_page、smspva_docs_get_examples 和 smspva_docs_list_pages。如果助手看不到这些工具，请确认当前会话已启用该服务，且组织策略允许连接。

服务包含 228 页文档，每种语言 76 页，覆盖全部 56 个已批准 API 方法。托管文档包由 SMSPVA 维护，用户无需自行构建。每次返回结果都会标明文档快照。当前价格和余量仍需通过 API 或本网站的实时列表查询。

连接问题排查复制链接

• 使用完整地址 https://mcp.smspva.com/docs，保留 /docs。不要改成首页，也不要添加 /sse。
• 在浏览器直接打开 /docs 时返回 405 可能是正常现象：它是协议端点，不是网页。请通过 MCP 客户端测试连接。
• 浏览器内运行的客户端收到 403，可能是其 Origin 不在允许列表中。CORS 通配符不会绕过服务的 Origin 检查。请使用原生客户端，或向 SMSPVA 支持团队提供客户端名称和完整错误信息。
• 收到 429 时，请等待后再重试。遇到超时或 503，稍后重新连接，并检查网络及组织策略。反复添加同一服务无法解决这些问题。
• 不要向此文档端点发送 SMSPVA 密钥。连接不需要购买服务、访问账户或授权执行示例。

搜索、阅读与获取示例复制链接

请明确指定 locale：en、es 或 zh。服务会使用该语言的页面和示例，不会自动切换语言，也不会翻译代码。页面标识在三种语言中保持一致，例如 api/balance、rental/default-services、email/providers、sdks 和 index。

section 可选 activation、rental、email 或 guides。获取请求示例时，language 可选 curl、javascript、typescript、python、php、go、csharp 或 java；也可以获取 JSON 响应、shell 环境设置等其他代码块。kind 用于区分 request、response 和 guide 示例。

以下内容是 MCP tools/call 请求的参数。搜索西班牙文 Activation 参考：

{
  "name": "smspva_docs_search",
  "arguments": {"query": "saldo", "locale": "es", "section": "activation", "limit": 5}
}

读取中文版余额页面：

{
  "name": "smspva_docs_read_page",
  "arguments": {"page": "api/balance", "locale": "zh", "max_chars": 6000}
}

获取英文页面中的 Python 请求示例：

{
  "name": "smspva_docs_get_examples",
  "arguments": {"page": "api/balance", "locale": "en", "language": "python", "kind": "request", "limit": 1}
}

代码块直接取自选定页面。HTTP 方法、参数名、响应码及重要警告的含义均保持不变。长页面或较多示例可以根据结果中的分页信息继续读取。

API MCP：调用 SMSPVA复制链接

本地 Alpha 版本已将 Activation V2、Rental 和 Private Email 的全部 56 个方法开放为 MCP 工具。它需要 Node.js 22.16 或更高版本，通过 stdio 连接 MCP 客户端，无需 Docker。

当前版本以本地进程运行，尚未提供远程 HTTP 端点或 OAuth，也未发布到软件包仓库、GitHub 或 MCP 目录。Alternative API 不包含在内。

构建与连接 API 服务复制链接

在项目目录中执行：

cd sdk/javascript
npm ci
cd ../../mcp
npm ci
npm run build

在客户端的 MCP 配置中添加服务。将绝对路径替换为本机 mcp/src/cli.mjs 的实际位置：

{
  "mcpServers": {
    "smspva": {
      "command": "node",
      "args": ["/absolute/path/to/mcp/src/cli.mjs"],
      "env": {
        "SMSPVA_API_KEY": "YOUR_API_KEY",
        "SMSPVA_READ_ONLY": "true"
      }
    }
  }
}

请将真实的 SMSPVA_API_KEY 保存在客户端的密钥存储或私有本地配置中，不要粘贴到聊天中，也不要作为工具参数传入。公开方法无需密钥；受保护的方法在未配置密钥时会返回验证错误。

示例启用了 SMSPVA_READ_ONLY，只开放 36 个只读工具。在此模式下，即使客户端知道另外 20 个工具的名称，服务也会拒绝调用它们。若要启用全部 56 个工具，可以删除该设置或将其设为 false。未设置时，默认开放全部 56 个工具。

Codex：API 服务复制链接

可将以下示例加入 Codex 的 config.toml，并使用 Node.js 22.16+。启动 Codex 前，请确保其环境中已有 SMSPVA_API_KEY。此示例不会安装服务。配置说明见 OpenAI 官方文档。

[mcp_servers.smspva]
command = "node"
args = ["/absolute/path/to/mcp/src/cli.mjs"]
env_vars = ["SMSPVA_API_KEY"]
startup_timeout_sec = 20
tool_timeout_sec = 45

[mcp_servers.smspva.env]
SMSPVA_READ_ONLY = "true"

调用工具复制链接

工具名称采用 smspva_<family>_<snake_case_sdk_method> 格式，其中 API 类别为 activation、rental 或 email。参数名称与 API 参考保持一致。国家、服务、供应商、价格和余量查询会读取 API 的当前数据，不依赖软件包内置的固定列表。

下面是 MCP tools/call 请求的参数。查询账户余额：

{
  "name": "smspva_activation_get_balance",
  "arguments": {}
}

读取当前 Email 供应商列表，无需发送 API 密钥：

{
  "name": "smspva_email_get_providers",
  "arguments": {}
}

读取一条新收到的短信可能触发扣费。以下调用仅在关闭只读模式时可用。请使用账户中已有订单的 orderid，并仅在确定要获取该结果时调用：

{
  "name": "smspva_activation_receive_sms",
  "arguments": {
    "orderid": 12345
  }
}

每次工具调用只发送一次 API 请求。服务不会自行创建订单、重试请求或在后台轮询。若要在客户端重复查询短信，请先阅读 Activation 流程。

结果、错误与费用复制链接

调用成功时，工具会在 structuredContent 中返回原始 API 数据。HTTP 202 和 SMS_NOT_YET_RECEIVED 仍表示正常的等待结果。创建 Email 订单时的 status=2 仍表示正常的无库存结果。HTTP 方法、参数名、响应码和响应值类型均遵循文档中的接口约定。

MCP 客户端还可以通过 smspva://contracts/activation、smspva://contracts/rental 和 smspva://contracts/email 读取随版本提供的 OpenAPI 接口定义，其中包含参数、响应结构和响应码。当前价格与余量应通过 API 工具查询。

工具错误使用 isError: true 和 structuredContent.error。API 错误保留 HTTP 状态、API 错误码和响应正文，但会隐藏其中出现的已配置账户密钥。SMSPVA_TIMEOUT_MS 默认为 30000，覆盖整个 HTTP 请求及响应正文的读取。

创建、延期、恢复或取消订单可能修改账户状态或产生费用，读取新的 Activation 短信也可能触发扣费。其中部分操作使用 GET。工具注解会将这些操作标记为会改变状态、可能具有破坏性的操作。注解只是提供给 MCP 客户端的提示，不是付款确认或访问控制。请在客户端中为账户配置合适的审批规则。

如果付费操作或修改状态的请求超时，其结果可能无法确定。重试前请先检查当前订单。返回的短信、邮件文本和 HTML 都是外部数据，不应当作指令执行。

以 Markdown 阅读文档复制链接

无需 HTML 也可以读取本站内容：

• 文档索引
• 完整文档
• 各文档页面的 Copy Markdown 按钮。

上述文档 MCP 支持在客户端中搜索这些页面。也可以直接使用 HTTP 示例和 SDK。