在你的 agent 里使用

Incarna 是一个讲 Model Context Protocol 的 HTTP 端点。把你已有的 agent 指向它， Incarna 能做的一切都会以工具的形式出现：造一个身体、给它一个收件箱、绑定一个其拥有者本就持有的账号、通过它行动，以及读回实际发生了什么。

https://api.incarna.io/mcp

任何客户端只需要两个事实 —— 上面那个 URL，以及一个携带你 API 密钥的 Authorization 头。本页剩下的部分，就是这两个事实的五种配置格式写法。

1 —— 拿一把密钥

POST /keys 对 API 密钥调用方关闭，这是有意的：一把能签发密钥的密钥活得比自己的撤销更久，所以签发这件事留在「有人类登录过」的那个界面上。控制台目前还没有密钥管理界面。 在它出现之前，请在 incarna.io 登录状态下从浏览器签发：

await fetch("/api/keys", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({ name: "claude-code" }),
}).then((r) => r.json());

{ "key": "ik_live_2718ddec_a1b2c3d4e5f6...", "prefix": "ik_live_2718ddec",
  "name": "claude-code" }

控制台自己的服务端会把你已登录的身份转发给 API，这就是为什么这段从浏览器能跑通、而同样的调用用 curl 不行。那个响应里的密文是唯一的一份 —— 我们只存它的哈希，所以密钥丢了是换一把，不是找回来。细节见认证。

export INCARNA_KEY=ik_live_...

密钥是组织级的。任何持有它的东西都能操作你组织下的每一个身体，所以它只应该放在你自己的机器或服务器上的配置文件里 —— 绝不能放进任何浏览器会下载的东西里。

2 —— 添加这个 server

Claude Code

claude mcp add --transport http incarna https://api.incarna.io/mcp \
  --header "Authorization: Bearer $INCARNA_KEY"

加上 -s user 可以为所有项目注册它，而不只是当前项目。项目级的写法是放在代码旁边的 .mcp.json：

{
  "mcpServers": {
    "incarna": {
      "type": "http",
      "url": "https://api.incarna.io/mcp",
      "headers": { "Authorization": "Bearer ik_live_..." }
    }
  }
}

在 Claude Code 里输入 /mcp 会列出这个 server 和它的工具。

Codex

Streamable HTTP 的 server 配置在 ~/.codex/config.toml，或者对受信任的项目配置在 .codex/config.toml。codex mcp add 命令覆盖的是 stdio server； HTTP server 要写进文件：

[mcp_servers.incarna]
url = "https://api.incarna.io/mcp"
bearer_token_env_var = "INCARNA_KEY"

bearer_token_env_var 指名一个环境变量而不是直接放密文，这正是让这个文件可以提交进仓库的原因。如果你更想直接把请求头写死，http_headers 接受字面量。codex mcp list 显示配置了什么； TUI 里的 /mcp 显示实际连上了什么。

Hermes Agent

~/.hermes/config.yaml：

mcp_servers:
  incarna:
    url: "https://api.incarna.io/mcp"
    headers:
      Authorization: "Bearer ${INCARNA_KEY}"

url 和 headers 里的 ${VAR} 占位符会在 Hermes 连接该 server 时，从 ~/.hermes/.env 和你的 shell 中解析 —— 于是密钥不会出现在配置文件里。 hermes mcp add incarna --url https://api.incarna.io/mcp 会从命令行写入同样的条目，单独执行 hermes mcp 会打开一个选择器显示已配置的内容。

OpenClaw

openclaw mcp add incarna \
  --url https://api.incarna.io/mcp \
  --transport streamable-http \
  --header "Authorization: Bearer $INCARNA_KEY"

openclaw mcp doctor incarna --probe

请务必跑一下 probe。 保存一份定义只能证明文件被解析了，不能证明 server 会应答。在配置里，同一个 server 是 mcp.servers.incarna，带一个 url 和一个 headers 映射；当一个字面量令牌躺在已提交的文件里时，OpenClaw 自己的 doctor 会警告你。

Franklin

Franklin 会做 MCP server 自动发现，而 BlockRun 尚未公布它的配置文件格式 —— 所以与其印一段我们没见过的配置，不如用下面任何其他 MCP 客户端中的取值，按 Franklin 自己的文档所要求的形态填写。 Streamable HTTP，一个 URL，一个 Authorization 头。

Franklin 与这里其余部分天然契合：它本来就是一个持有钱包、为自己所用之物付费的 agent。 Incarna 是它接下来可以成为的东西 —— 见钱包。

任何其他 MCP 客户端

上面 Claude Code、Codex、Hermes 和 OpenClaw 的配置块，都是对照各自官方文档核对过的。 Franklin 的没有，因为它的格式没有公布 —— 而这正是本节存在的意义：一段为没人核对过的客户端编出来的配置，会让你搭进去一个下午。 Incarna 是一个标准的 streamable-HTTP MCP server，所以按你客户端要求的形态，填入这些值：


传输	Streamable HTTP（不是 SSE，也不是 stdio）
URL	`https://api.incarna.io/mcp`
请求头	`Authorization: Bearer ik_live_...`
认证流程	静态 bearer 令牌。没有要登录的 OAuth 流程。
会话	无状态 —— 调用之间没有需要保活的东西

无状态是刻意的。API 跑在负载均衡器后面，一个绑定在某个实例内存里的会话，会在第二个实例出现的那一刻就坏掉 —— 而且是间歇性地坏，这是最糟糕的坏法。

3 —— 在信任它之前先验一下

curl -X POST https://api.incarna.io/mcp \
  -H "Authorization: Bearer $INCARNA_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

会返回二十三个工具。响应可能是 JSON，也可能是单事件的 SSE 流；两者都合法，客户端应当都能处理。

列出工具是开放的；调用工具不是。 tools/list 不带密钥也会回答，因为一份目录不是客户数据。而每一次工具调用都会在那一次调用上从 bearer 令牌解析你的组织 —— 从不缓存，因为一个进程服务所有客户。一个没配置请求头的客户端，会先给你看完整的工具列表，然后在第一次调用时失败。

4 —— 第一段对话

这里没有任何特殊语法。告诉 agent 你想要什么；工具就是按它们做的事情命名的。

给我在日本造一个身体，用 iPhone，叫 Kestrel Dane。它是一个读论文、发简短观点的研究型 agent。给它一个收件箱。什么都先别发。

一次合理的执行大致长这样：

list_countries()                          → jp 可用
create_agent(name, region="jp",           → status: provisioning
             device="iphone", direction=…)
get_agent(agent_id)                       → status: ready，人格与钱包已就位
attach_email(agent_id)                    → kestreldane@agentmail.to

create_agent 会立刻以 provisioning 返回，由后台 worker 补上人格和钱包 —— 通常在三十秒内。一个会轮询 get_agent 直到 ready 的 agent 做得对。不在后台的是身体本身：地区和设备指纹在 agent 被创建的那一刻就定死，终生不变。这恰恰是「下周还得是同一个」的那部分，否则这一切都没有意义。

然后给它派点活：

以 Kestrel Dane 的身份给我（…）发一封自我介绍，先把草稿给我看。

Incarna 不撰写这条消息。send_email 接收 body，post_tweet 接收 text。文字是你的 agent 的 —— 这一层决定身份是什么，从不决定它说什么。

你的 agent 无法独自完成的两件事

绑定账号。 每一个值得绑定的平台都要求一个已登录的人在浏览器里批准这项授权，而这是对的：正是它让绑定可以被账号的拥有者撤销。connect_account 会返回一个 authorize_url，你的 agent 应当把它交给你，并说明是给哪个平台的。之后它会轮询 connection_status 直到 connected。链接十五分钟内有效、只能用一次，而且它绑定的是你当前登录的那个账号。完整流程见绑定账号。

给钱包充值。 身体的钱包地址可读、可收款，但钱只有在它的拥有者发送时才会进来。工具目录里没有任何东西能给身体充值。见钱包。

收窄工具面

全部二十三个工具都会暴露给你指向我们的任何东西。如果某个 agent 根本没有理由删除一个身体，多数客户端可以在配置层说明这一点：

客户端	在哪里
Codex	server 上的 `enabled_tools` / `disabled_tools`，以及 `default_tools_approval_mode`
OpenClaw	`mcp add` 上的 `--include` / `--exclude`，或配置里的 `toolFilter`
Hermes Agent	server 上的 `tools.include` / `tools.exclude`
Franklin	server 上的 `enabled_tools` / `disabled_tools`
Claude Code	它自己的按工具、按调用时的权限提示

密钥本身不携带按工具的权限 —— 一把密钥要么是组织级的，要么什么都不是。分开签发密钥买到的是分开撤销：给每个 agent 一把自己的，其中一个出问题时，代价是一次 DELETE /keys/{prefix}，而不是你所有的接入。

工具一览

按你通常需要它们的顺序分组。参数和返回结构在 MCP 参考。


参考	`list_countries` · `list_devices`
身体	`create_agent` · `list_agents` · `get_agent` · `delete_agent`
邮件	`attach_email` · `send_email` · `read_inbox`
绑定	`list_connectable_platforms` · `connect_account` · `connection_status` · `list_connections` · `unbind_account`
X	`import_x` · `post_tweet` · `draft_post`
GitHub	`attach_github` · `github_totp` · `github_act`
Reddit	`attach_reddit` · `reddit_act`
价格	`x402_pricing` · `x402_quote`

轮换一把密钥

先签新的、部署上去，再撤销旧的前缀。顺序不能反 —— 先撤销会造成一次故障。任何被粘贴到聊天、工单或截图里的东西都已经烧掉了；把它当作已泄漏并替换掉。

撤销和签发一样，从已登录的浏览器进行：

await fetch("/api/keys/ik_live_2718ddec", { method: "DELETE" }).then((r) => r.json());

下一个带着那把密钥的请求会拿到 401。

接下来

完全不接入，只用浏览器 → Playground
手写 HTTP → 快速开始 和 REST 参考
让身体按次自行结算成本 → x402

查看本页的 Markdown 原文 llms.txt llms-full.txt