Skip to main content
Ayrshare MCP Server 允许 AI 代理驱动 Ayrshare API。本页介绍如何连接到它以及身份认证的工作原理。

​
端点与传输方式

生产环境 MCP Server 地址为： https://api.ayrshare.com/mcp 它使用 Streamable HTTP 传输方式，并且是 无状态的（stateless） —— 各次调用之间无需维护会话。

​
支持的客户端

Action MCP Server 仅 通过静态的 Authorization: Bearer 请求头进行认证。这一条要求决定了下文的一切：能够在 Streamable HTTP 连接上设置自定义 HTTP 请求头的客户端就能完成认证，做不到的客户端则无法认证。开始配置之前，请先在下表中找到你的客户端。

​
个人连接器为何无法认证

Ayrshare 的 Action MCP 要求使用静态的 Authorization: Bearer 请求头。在 claude.ai、Claude Desktop 或 Claude mobile 上将其添加为个人自定义连接器是行不通的，因为 Ayrshare 未发布 OAuth 元数据，而请求头这一替代方案目前是仅向获批组织开放的 Beta 功能。 对于个人连接器，你这一侧的任何设置都无法解决这个问题：既没有可填写 Authorization 请求头的字段，也没有任何 API 密钥、配置文件或账户设置可以启用它。Ayrshare 不发布 OAuth 元数据，因此连接器的 OAuth 路径没有任何可连接的对象。 请改用上表中的客户端：Claude Code、Claude Code 插件，或任何允许你设置自定义 Authorization 请求头的客户端。如果你是已加入 Anthropic 请求头 Beta 的组织的管理员，请参见下文 Team 与 Enterprise 组织。
如果你的连接器看起来一切正常，但每一次工具调用都失败。 连接器可以正常添加，状态显示 健康（healthy），并列出 完整的工具目录 —— 然而 每一次 工具调用都会返回 Ayrshare 403 / code 102，“API Key not valid”。这正是上述限制所致，而不是密钥失效 —— 你的客户端无法发送该服务器要求的静态 Authorization: Bearer 请求头。initialize 和 tools/list 在认证之前即可访问（参见下文 身份认证），因此在第一次工具调用之前不会出现任何失败，直到那时才会暴露出从未发送过凭据这一事实。是客户端能力问题，还是密钥确实有问题？ 两者返回的错误完全相同，因此需要通过特征来区分。客户端能力问题的特征是：连接器状态健康 且 每一次工具调用都失败，而同一个密钥在其他地方可以正常使用。失效的密钥会产生相同的错误，但在连接器之外也能复现 —— 在 REST 调用中同样会失败。关于错误本身的语义，请参见下文 认证错误。

​
Team 与 Enterprise 组织

Anthropic 的 static_headers 机制允许自定义连接器以请求头形式发送固定凭据，而无需使用 OAuth。它 以 Beta 形式向少数组织的组织管理员开放，并且 不 向添加个人连接器的个人用户开放。 如果你的组织拥有访问权限，管理员必须将请求头的值填写为 Bearer 后接你的 Ayrshare API 密钥，且必须包含其中的空格 —— Claude 会原样发送所填写的值，不会自动为你补上该认证方案前缀。有关当前可用性与设置方法，请参见 Anthropic 的连接器认证文档。
该密钥由整个组织共享。 Anthropic 的请求头凭据由管理员填写一次，供组织中的每位成员使用，因此所有成员都会以该密钥所属的同一个 Ayrshare 账户身份进行操作 —— 在 Business 密钥下可以访问其名下的所有 User Profile，而且你的 Ayrshare 历史记录与分析数据中不会有按用户区分的归属。请将其视为共享的服务凭据，而非个人访问权限。

​
身份认证

身份认证由为 REST API 提供支持的同一条 Ayrshare API 处理链执行。
  • 必填： Authorization: Bearer YOUR_API_KEY —— 你的账户 API 密钥（涉及配置文件与子配置文件时，需要 Business 套餐的密钥）。
  • 可选： Profile-Key: YOUR_PROFILE_KEY —— 让该连接上的每一次调用都以该子配置文件为目标。
  • 每次调用可选： profileKey 工具参数 —— 仅让本次工具调用以某个子配置文件为目标。

​
优先级：参数优先于请求头

当一次工具调用同时包含 profileKey 参数 和 连接上的 Profile-Key 请求头时，本次调用的 profileKey 参数优先生效。只有在未提供有效参数时，才会使用请求头。 一个例外：在 get_platform_history 和 get_social_network_analytics 上，X/Twitter 的 userId / userName 查询必须仅使用账户 API 密钥；此时如果传入 profileKey 参数或 Profile-Key 请求头，会返回 400 错误。
MCP 的 initialize 和 tools/list 方法可以在 认证之前 访问 —— 它们只返回元数据，不会执行任何操作。所有工具调用都必须经过认证。

​
认证错误

在工具调用中使用未认证或无效的密钥，会返回 Ayrshare error 403 / code 102，错误信息为 “API Key not valid”。根据 MCP 规范，工具执行错误以带内（in-band）方式返回：工具结果携带 isError: true 及该错误信息，而 MCP 传输本身返回 HTTP 200。（403 / 102 是 Ayrshare 的应用层错误，而非传输层状态。）

​
连接

​
方式 A：Claude Code 插件

如果你使用 Claude Code，可以安装 Ayrshare 插件。该插件已内置 MCP Server 配置、初始化命令、代理、技能以及确认钩子。完整安装步骤请参见 Claude Code 插件 页面。

​
方式 B：任意 MCP 客户端

对于任何支持 Streamable HTTP 且允许你设置自定义请求头 的 MCP 客户端 —— 参见上文 支持的客户端 —— 可以直接注册服务器。在 Claude Code 中：
要让每次调用都以某个子配置文件为目标，请添加可选的 Profile-Key 请求头：
MCP 连接会在会话启动时初始化。安装服务器或修改密钥后，请 重启你的 MCP 客户端 以使新配置生效。

​
X/Twitter 自带（BYO）凭据

从 2026 年 3 月 31 日起，通过 Ayrshare 进行的 X/Twitter 操作要求使用你自己的 OAuth 1.0a 凭据。当工具调用目标是 X/Twitter 时，请在连接中随 Authorization（以及可选的 Profile-Key）请求头一起附加以下两个请求头： 这些请求头与 REST API 使用的相同 —— 每个 Ayrshare 账户对应一对 OAuth 1.0a 密钥，在每个以 X 为目标的请求中都需要发送（同一对密钥适用于所有子配置文件）。Ayrshare 在此处不使用 OAuth 2.0。有关设置、政策与故障排查，请参见 API 概览 和 X BYO Key 设置指南。
如果缺少这些请求头，X/Twitter 工具调用会返回错误 419（x_credentials_required）。

​
连接时同时配置 BYO 请求头

如需从一开始就配置 X/Twitter BYO 凭据，请在添加服务器时同时提供两个 OAuth 1.0a 请求头与 Authorization 请求头（如需每次调用都以某个子配置文件为目标，也请一并附上 Profile-Key）：

​
为已有连接补充 BYO 请求头

连接的请求头在添加服务器时就已固定，因此如果你之前连接时没有携带 BYO 请求头，需要先移除服务器，然后重新添加并提供完整的请求头集合（重新包含你之前已经使用的任何请求头，例如 Profile-Key）：
修改请求头后，请重启 MCP 客户端以使新配置生效。如果你使用的是 Claude Code 插件而非直接连接？请参见 Claude Code 插件 → X/Twitter BYO 凭据。

​
后续步骤

工具目录

按领域分组的 33 个工具，包含作用范围与用途。

Claude Code 插件

为 Claude Code 安装 Ayrshare 插件。