50heads

50heads MCP

通过 Claude、ChatGPT、Cursor 或你自己的 Agent，向 50 位经过验证的人提出一个只需 5 秒回答的问题，看看他们的想法。Tier 1 的 50 个回答：1000 积分，按你账户的货币计价。

有两种接入方式，使用相同的工具：

• 托管版（推荐）：https://mcp.50heads.com/mcp。使用 Streamable HTTP，在浏览器中通过 OAuth 登录。无需安装。
• 本地版：npx -y @50heads/mcp，供通过命令启动服务的客户端使用的 stdio 服务。需要 Node 20 或更高版本，以及 API 密钥（或一次性运行 login）。

安装

选择下方的客户端。托管服务无需安装任何内容：添加 URL，并在浏览器中通过 OAuth 登录，同时设置该连接的每日消费上限。本地服务（npx -y @50heads/mcp）需要 Node 20 或更高版本，以及 API 密钥。

如果需要 API 密钥，请在控制面板的 Developers 页面创建：https://50heads.com/app/developers。密钥以 fh_live_ 开头，且只会显示一次。也可以运行一次 npx -y @50heads/mcp login，无需提供密钥。

运行 npx -y @50heads/mcp config [host] 可查看以下任一配置说明。相同的说明也见于 https://50heads.com/en-us/docs/mcp。

Claude（claude.ai 和 Claude Desktop）

托管版，通过 OAuth 登录。打开 Settings、Connectors、Add custom connector。粘贴 URL，并按提示登录。Team 和 Enterprise 计划需要由所有者先为组织添加此连接器。

https://mcp.50heads.com/mcp

也可以在 claude_desktop_config.json 中使用 API 密钥（macOS：~/Library/Application Support/Claude/，Windows：%APPDATA%\Claude\）。

{
  "mcpServers": {
    "50heads": {
      "command": "npx",
      "args": [
        "-y",
        "@50heads/mcp"
      ],
      "env": {
        "FIFTYHEADS_API_KEY": "fh_live_…"
      }
    }
  }
}

Claude Code

托管版，通过 OAuth 登录。在终端中运行，然后在 Claude Code 中运行 /mcp 并登录。

claude mcp add --transport http 50heads https://mcp.50heads.com/mcp

也可以使用 API 密钥（适用于 CI 和脚本）：

claude mcp add --transport http 50heads https://mcp.50heads.com/mcp --header "Authorization: Bearer fh_live_…"

Cursor

托管版，通过 OAuth 登录。使用 ~/.cursor/mcp.json（或项目中的 .cursor/mcp.json）。Cursor 会打开登录页面。

{
  "mcpServers": {
    "50heads": {
      "url": "https://mcp.50heads.com/mcp"
    }
  }
}

也可以使用 API 密钥：

{
  "mcpServers": {
    "50heads": {
      "url": "https://mcp.50heads.com/mcp",
      "headers": {
        "Authorization": "Bearer fh_live_…"
      }
    }
  }
}

ChatGPT

托管版，通过 OAuth 登录。打开 Settings、Apps and Connectors、Advanced settings，开启 Developer mode，然后选择 Create。粘贴 URL 并选择 OAuth。Business 和 Enterprise 计划需要管理员先开启 Developer mode。

https://mcp.50heads.com/mcp

VS Code

托管版，通过 OAuth 登录。在工作区的 .vscode/mcp.json 中配置，或从命令面板运行 MCP: Add Server。

{
  "servers": {
    "50heads": {
      "type": "http",
      "url": "https://mcp.50heads.com/mcp"
    }
  }
}

也可以从终端运行：

code --add-mcp '{"name":"50heads","type":"http","url":"https://mcp.50heads.com/mcp"}'

Windsurf

本地版，使用 API 密钥。配置文件位于 ~/.codeium/windsurf/mcp_config.json，也可以打开 Windsurf Settings、Cascade、MCP servers、View raw config。

{
  "mcpServers": {
    "50heads": {
      "command": "npx",
      "args": [
        "-y",
        "@50heads/mcp"
      ],
      "env": {
        "FIFTYHEADS_API_KEY": "fh_live_…"
      }
    }
  }
}

也可以使用带 API 密钥的托管服务：

{
  "mcpServers": {
    "50heads": {
      "serverUrl": "https://mcp.50heads.com/mcp",
      "headers": {
        "Authorization": "Bearer fh_live_…"
      }
    }
  }
}

其他客户端

本地版，使用 API 密钥。适用于通过命令启动服务的客户端。需要 Node 20 或更高版本，以及从控制面板获取的 API 密钥。

FIFTYHEADS_API_KEY=fh_live_… npx -y @50heads/mcp

支持 Streamable HTTP 的客户端：使用 https://mcp.50heads.com/mcp 和请求头 "Authorization: Bearer fh_live_…"，或使用 OAuth。

{
  "mcpServers": {
    "50heads": {
      "url": "https://mcp.50heads.com/mcp",
      "headers": {
        "Authorization": "Bearer fh_live_…"
      }
    }
  }
}

检查是否正常工作

让客户端“使用 50heads 估算询问 50 个人更喜欢两个名字中的哪一个”。estimate（操作 quote）免费，绝不会消耗积分。在 Claude Code 中，/mcp 会列出服务及其工具；在其他客户端中，请在工具或连接器列表中查找 50heads。

在命令行中登录

npx -y @50heads/mcp login     # opens the browser; the token goes in your keychain
npx -y @50heads/mcp status
npx -y @50heads/mcp logout

login 使用 OAuth 设备授权流程连接 https://auth.50heads.com。令牌保存在 macOS Keychain 或 Linux 上的 Secret Service 中，否则保存在 ~/.config/50heads/credentials.json（模式 600）中。如果两者都存在，FIFTYHEADS_API_KEY 中的 API 密钥优先。

--proxy 会将 stdio 转发到托管服务，而不是在本地运行工具。

变量	含义
FIFTYHEADS_API_KEY	用于 CI 和脚本的 API 密钥
FIFTYHEADS_API_URL	API 基础 URL，默认为 https://api.50heads.com
FIFTYHEADS_MCP_URL	--proxy 使用的托管端点
FIFTYHEADS_AUTH_URL	login 使用的登录服务
FIFTYHEADS_CREDENTIALS_STORE=file	将登录凭据保存在文件中，而不是钥匙串中
FIFTYHEADS_DEBUG=1	将每次调用记录到 stderr（绝不记录问题文本）

工具（9 个，每个都接受一个 action）

共有 9 个工具，数量不会超过 10 个。每个工具都接受一个 action 及该操作专属的参数，并按操作进行验证（输入是以 action 为判别字段的联合类型）；tools/list 会在工具描述中记录每个操作。权限范围属于操作，而非工具：连接若缺少某个操作所需的权限范围，只会针对该操作收到 insufficient_scope 拒绝；只读授权绝不会执行会更改内容的操作。工具注解适用于该工具的每个操作：estimate、results、organization 和 audit 均为只读（readOnlyHint: true）；questions、projects 和 webhooks 各自包含取消或删除操作，因此带有 destructiveHint: true；ask 和 help 会更改内容，但不会造成破坏。每个工具的 _meta["com.50heads/scopes"] 都列出了各个操作的权限范围。

工具	提示	操作	功能
estimate	只读	quote、balance、templates、audiences、targeting	为问题报价、检查额度，并查询可提问的内容。
ask	写入	ask、set、upload_image、build_link	向 heads 或自己的受众提问、上传图片，并创建供他人点击「Ask」的链接。
results	只读	get、wait、answers、export、list	读取结果、等待结果、读取单条回答、导出文件，以及列出你的问题。
questions	破坏性	cancel、add_heads、flag_answer、file	更改一个问题：取消问题、添加 heads、标记回答或归档问题。
projects	破坏性	list、create、update、delete、labels	管理项目和标签，以便查找问题。
webhooks	破坏性	list、create、update、rotate_secret、test、deliveries、events、replay、delete	管理 Webhook 端点、投递记录和近期事件。
organization	只读	get、domains、scim、member_sessions、service_accounts、apps	查看组织、其域名、SCIM、成员会话、服务账号和工作区应用。
audit	只读	list、export	查看组织审计日志。
help	写入	search、feedback、status、whoami	搜索帮助中心、发送反馈、检查 50heads 是否正常运行，以及查看连接所代表的身份。

操作和权限范围

工具	操作	范围	功能
estimate	quote	questions:write	为问题报价并检查问题。绝不会扣费。请先调用此项。
estimate	balance	account:read	积分、预留积分，以及连接每日限额内的剩余额度。
estimate	templates	none	固定价格的模板。无需登录即可使用。
estimate	audiences	none	可供选择、替代定向的兴趣受众，并按等级列出价格。
estimate	targeting	none	可定向的国家、语言、受众池范围和标签。
ask	ask	questions:write	向经过验证的受访者提问。需要一个新的 UUID 作为 idempotency_key。返回一个任务（旧版主机上则返回 question_id）。
ask	set	questions:write	为你自己的受众设置 2 到 10 个问题，通过一个共享链接按顺序作答。需要 idempotency_key。
ask	upload_image	questions:write	通过 base64 或 https 链接将图片上传到 50heads；返回可用于问题的 image_url。
ask	build_link	none	生成一个门户链接，其中已填入问题，供他人查看并提问。不扣费。
results	get	questions:read	获取当前结果，无需等待：各选项的占比；是/否问题相对于你设定的标准给出的通过或不通过判定；以及排名和两两比较问题中谁胜过谁，并附带范围。
results	wait	questions:read	在服务器上等待答案，最长 600 s（min_answers、timeout_seconds）。适用于不支持任务的主机。
results	answers	questions:read	分页获取单条答案，可按选项、等级、国家、年龄段或关键词筛选。
results	export	questions:read	将结果导出为文件：CSV、JSON 行（每行一条答案，含选项索引和群组哈希）、单页 PDF 报告或 PNG 图表。
results	list	questions:read	获取最近的问题，可按状态、项目、标签、引用、书签或问题集筛选。再次提问前请先检查。
questions	cancel	questions:write	停止正在进行的问题，并退还未作答受访者的费用。此操作具有破坏性。
questions	add_heads	questions:write	为同一个问题增加受访者，结果合并到一起。需要 idempotency_key。
questions	flag_answer	questions:write	使用答案的 attestation_ref 举报该答案以供审核；举报成立时会退款。
questions	file	questions:write	为问题归档：设置项目、标签、书签、归档状态，以及只设置一次的外部引用。
projects	list	questions:read	列出账户中的项目；使用 include_archived 也可包含已归档项目。
projects	create	questions:write	创建一个用于归档问题的新项目。
projects	update	questions:write	重命名、修改描述、归档或恢复项目。
projects	delete	questions:write	删除项目。其问题及答案仍会保留，但不再属于任何项目。此操作具有破坏性。
projects	labels	questions:read	列出正在使用的标签，按使用频率从高到低排序。
webhooks	list	webhooks:read	查看 Webhook 端点：地址、事件、筛选条件、启用或停用状态、最近一次投递记录。密钥会隐藏。
webhooks	create	webhooks:write	将选定事件签名后发送到你拥有的 https 地址；可按项目或标签筛选。密钥仅返回一次。
webhooks	update	webhooks:write	更改地址、事件、描述或筛选条件（null 会清除筛选条件）；暂停或恢复。
webhooks	rotate_secret	webhooks:write	生成新密钥，仅返回一次；旧密钥在 overlap_hours 期间仍可用于签名（默认 24，最多 168）。
webhooks	test	webhooks:write	立即发送已签名的 webhook.test 事件，并说明接收方的响应。
webhooks	deliveries	webhooks:read	查看最近 100 条投递记录，可按端点或状态筛选（failed 表示已用尽重试次数）。
webhooks	events	webhooks:read	查看某一类型的最近事件（最多 25 条），每条内容与投递时完全一致：示例载荷，或按事件 ID 补取事件。
webhooks	replay	webhooks:write	使用相同的事件 ID 再次发送某条投递中的事件。
webhooks	delete	webhooks:write	永久删除端点。此操作具有破坏性。
organization	get	organization:read	获取该密钥或应用所操作的工作区所属组织：工作区、已验证域名、单点登录、SCIM 和登录规则。
organization	domains	organization:read	获取组织的域名，以及每个域名的状态和用于验证域名所有权的 DNS TXT 记录。仅限管理员。
organization	scim	organization:read	SCIM 配置：基础 URL、已发送的人员和群组、默认角色、按标签和前缀列出的令牌。仅限管理员。
organization	member_sessions	members:read	获取一名成员的活动会话，以及每个会话的启动方式。仅限管理员。
organization	service_accounts	organization:read	获取组织的服务账户：工作区、范围、限额、今日支出和最近的令牌。绝不返回密钥。
organization	apps	apps:read	获取已添加 50heads 的 Slack 工作区和 Microsoft Teams 租户（由 provider 指明），以及 Zapier 连接：每日限额、今日支出、添加者，以及每个 Zapier 连接的钩子。
audit	list	audit:read	查看组织及其工作区中的操作记录，按时间倒序排列，可按时间、操作者、event_action 和工作区筛选。仅限管理员。
audit	export	audit:read	将相同事件导出为 JSON 行，按时间正序排列，并附带用于续传的游标。每次导出都会记录。仅限管理员。
help	search	none	搜索帮助中心并返回带链接的文章。
help	feedback	none	以工单形式向支持团队发送反馈或问题（未登录时请添加 email）。
help	status	none	查看 50heads 是否正常运行，以及提问、作答、通过 MCP 提问或购买积分是否已暂停。无需登录即可使用。只读。
help	whoami	account:read	查看此连接代表的身份（邮箱已隐藏）、其范围、限额和今日支出、所操作的账户和组织，以及速率限制和已用额度。只读。

前后对比

此版本用上面的 9 个工具替换了 44 个单一用途工具（决策 G12：工具最多 10 个，以便模型做出合适选择）。每个旧工具都是某个新工具的一项操作，参数保持不变；有两处细节变更：build_ask_link 现在将问题字段放在 draft 中；审计筛选器 action 改为 event_action（避免与 action 冲突）。wait_for_results 现在在所有主机上都改为 results，并使用 action: "wait"。

旧工具	新工具	操作
estimate	estimate	quote
ask	ask	ask
ask_set	ask	set
get_results	results	get
wait_for_results	results	wait
list_questions	results	list
cancel	questions	cancel
templates	estimate	templates
balance	estimate	balance
upload_image	ask	upload_image
get_answers	results	answers
add_heads	questions	add_heads
flag_answer	questions	flag_answer
export	results	export
build_ask_link	ask	build_link
list_audiences	estimate	audiences
list_targeting	estimate	targeting
search_help	help	search
send_feedback	help	feedback
whoami	help	whoami
service_status	help	status
list_webhooks	webhooks	list
create_webhook	webhooks	create
update_webhook	webhooks	update
rotate_webhook_secret	webhooks	rotate_secret
test_webhook	webhooks	test
list_webhook_deliveries	webhooks	deliveries
list_webhook_events	webhooks	events
replay_webhook_delivery	webhooks	replay
delete_webhook	webhooks	delete
list_projects	projects	list
create_project	projects	create
update_project	projects	update
delete_project	projects	delete
list_labels	projects	labels
file_question	questions	file
list_apps	organization	apps
get_organization	organization	get
list_domains	organization	domains
list_audit_events	audit	list
export_audit_events	audit	export
get_scim_status	organization	scim
list_member_sessions	organization	member_sessions
list_service_accounts	organization	service_accounts

除非用户提出请求，否则不会授予 webhook 和 app 权限范围：在授予这些权限范围之前建立的连接，或未请求这些权限范围的连接，会收到 insufficient_scope，并可重新连接以添加这些权限范围。

每个连接都有每日支出上限（默认 5,000 个点数）。超出上限的提问会返回 spend_cap_exceeded，并说明剩余额度及重置时间。

错误为 JSON-RPC 错误，包含 error.data.code（validation、not_found、insufficient_credits、spend_cap_exceeded、idempotency_conflict、content_refused、rate_limited、unavailable）和 retryable 提示。

资源：50heads://guide（技能）、50heads://templates、50heads://question-types、50heads://pricing、50heads://countries、50heads://webhook-events（事件类型、各类型包含的内容、JSON Schema 链接以及投递内容的签名方式）、50heads://results/{question_id}。提示词：ask_the_heads、read_results。显示 MCP Apps 的主机会以卡片形式展示估算结果和结果。

工具注解：只读工具带有 readOnlyHint: true；只有 questions（取消）、projects（删除）和 webhooks（删除）这几个工具标记了 destructiveHint: true；每个工具都带有 openWorldHint: true 和输出 schema（由其各项操作的输出组成的联合类型）。显示 MCP Apps 的主机会以卡片形式展示报价和结果：它们会显示在 estimate 和 results 中，且只会出现在为其生成的回复中。

隐私

隐私政策：https://50heads.com/en-gb/legal/privacy。我们不会用你的问题、你购买的答案或各位头脑写答案的原因来训练 AI 模型，也不会出售这些内容：https://50heads.com/en-gb/help/privacy/ai-and-your-data。答案绝不会透露任何头脑的身份。

查找位置

• 托管版：https://mcp.50heads.com/mcp。
• npm：@50heads/mcp。
• 官方 MCP Registry 中的 com.50heads/mcp，以及 MCP 目录：即将推出。

Agent Skill

此软件包附带 50heads Agent Skill，位于 skills/50heads（@50heads/mcp/skills/50heads/SKILL.md）：介绍何时提问、好问题的八条规则、如何阅读结果，以及有关问题类型和定价的参考信息。将该文件夹复制到宿主的 skills 目录，或让支持 com.50heads/skills 扩展的宿主从服务获取。

作为库使用

import { serveStdio } from "@modelcontextprotocol/server/stdio";
import { serverFactory } from "@50heads/mcp";

serveStdio(serverFactory({ apiKey: process.env.FIFTYHEADS_API_KEY }));

serveStdioServer(options) 会运行整个 stdio 服务，包括任务。configSnippets() 会返回上述安装代码片段。

版本

发行版采用日历版本号 YYYY.MDD.N：2026.924.1 是 2026 年 9 月 24 日的首个发行版，当天的第二个发行版为 2026.924.2。npm 软件包、托管服务（serverInfo.version）、registry 清单、--version 和 Agent Skill 均使用相同的版本号。请参阅 CHANGELOG.md。

server.json 已准备好以 com.50heads/mcp 的名称提交至官方 MCP Registry。目前 registry 尚无条目（搜索不到任何服务）。要发布，需要在发行工作流中设置 MCP_REGISTRY_ED25519_KEY。请参阅 docs/publishing.md。npm 软件包已发布。

开发

此软件包位于 50heads 单体仓库中。托管服务（apps/mcp）和 stdio 服务共用一个模块 src/server.ts，因此两者不会出现偏差。

pnpm --filter @50heads/mcp generate   # skill module, skill references, server.json, README install section
pnpm --filter @50heads/mcp test
pnpm --filter @50heads/mcp build      # dist/cli.js, dist/index.js, types, skills/ and skills/50heads.zip

有关发布流程（通过公共镜像并附带 provenance 发布到 npm、MCP Registry 和 GitHub Release），请参阅 docs/publishing.md。

MIT 许可证。

拼写

服务说出、接受和返回的所有内容均使用美式英语：工具名称、操作、描述、参数、输出和错误代码（organization、authorized、canceled）。有一个词的拼写不由我们决定：已停止的 MCP 任务状态为 cancelled，因为 MCP tasks 协议就是这样定义的，而且客户端会对其进行验证。通过 questions 并使用 action: "cancel" 停止的问题，状态为 canceled。