Plug an external tool server into your agent — including the ones that need you to log in first把外部工具服务器接进你的 agent——包括那些需要你先登录的
MCP is a standard way for a program to expose its tools to an AI agent. Point the agent at a server, and that server's tools become callable — no adapter written per service.MCP 是一套「程序如何把自己的工具暴露给 AI agent」的标准。把 agent 指向一个服务器，它的工具就变得可调用——不需要为每个服务单独写适配器。
The practical difference: a company that ships an MCP server has integrated with every MCP-speaking agent at once, and you can connect to it without waiting for anyone to build support. Starchild speaks MCP as a client — your agent consumes those servers alongside its own native tools, and from the model's point of view they are the same thing.实际区别在于：一家公司只要发布了 MCP 服务器，就等于一次性接入了所有说 MCP 的 agent；而你连上它，不必等任何人来做支持。Starchild 作为 MCP 客户端——你的 agent 把这些服务器的工具与自己的原生工具并列使用，在模型眼里两者没有区别。
You describe where the server is; the transport follows from that. A command means a local process, a url means a network server.你只描述服务器在哪，传输方式随之确定。写 command 就是本地进程，写 url 就是网络服务器。
| Transport传输 | You write你写什么 | Use it for适用场景 |
|---|---|---|
| stdio | command + args | A server that runs as a local child process — filesystem access, local databases, CLI wrappers.以本地子进程运行的服务器——文件系统访问、本地数据库、CLI 封装。 |
| streamable-http | url | The default for a remote server. This is what most hosted MCP services expose today.远程服务器的默认选择。目前多数托管 MCP 服务用的就是它。 |
| sse | url + transport: sse | Older server-sent-events endpoints. Only needed when a server has not moved to streamable HTTP.较旧的 SSE 端点。只有当服务器还没迁到 streamable HTTP 时才需要。 |
Everything lives in workspace/config/agent.yaml under mcp_servers: — the one config location that survives platform updates. Credentials are never written there: they go in workspace/.env and are referenced as ${VAR}. Per-server timeout defaults to 60 seconds.所有配置都在 workspace/config/agent.yaml 的 mcp_servers: 下——这是唯一能扛住平台更新的配置位置。凭证绝不写在那里：它们放在 workspace/.env，以 ${VAR} 形式引用。每个服务器的 timeout 默认 60 秒。
For stdio servers the child process does not inherit your environment. It gets an allowlisted base plus exactly the extra variables you declared for that server — so a local MCP server cannot read credentials you never gave it.对 stdio 服务器，子进程不会继承你的环境变量。它拿到的是一份白名单基底，加上你为该服务器显式声明的那几个变量——所以本地 MCP 服务器读不到你没给它的凭证。
A static key and an OAuth login are different problems. The config keeps them apart on purpose.静态密钥和 OAuth 登录是两回事。配置刻意把它们分开。
| Situation情况 | Config配置 | What happens发生什么 |
|---|---|---|
| Server takes an API key服务器认 API key | headers: | The key is sent on every request. Nothing interactive; it works the moment the config is saved.每次请求都带上该密钥。没有交互步骤，配置保存即生效。 |
| Server requires you to log in服务器要求你登录 | auth: oauth | A full OAuth 2.1 flow with PKCE, discovery and dynamic client registration — you approve once in a browser.完整的 OAuth 2.1 流程，含 PKCE、元数据发现与动态客户端注册——你在浏览器里授权一次即可。 |
Asking for a scope, a custom redirect or a pre-registered client identity without turning OAuth on is rejected at config-parse time rather than failing later at connect time. Both redirect_uri and client_metadata_url must be HTTPS.在没开 OAuth 的情况下要求 scope、自定义回调或预注册的客户端身份，会在配置解析阶段就被拒绝，而不是等到连接时才失败。redirect_uri 与 client_metadata_url 都必须是 HTTPS。
The agent cannot log in as you. So the flow pauses, hands you a URL, and resumes when you come back.agent 不能代替你登录。所以流程会暂停、给你一个 URL，等你回来后继续。
Fig 1.图 1. Discovery and registration happen without you. The only human step is approving in a browser.发现与注册无需你参与。唯一的人工步骤是在浏览器里点同意。
When the agent first reaches a server that needs authorization, the connection does not simply fail — it raises a pending state carrying the authorize URL, and that URL is what you are shown. Approve it, and the callback lands on the standard Starchild handoff page; the code is exchanged for tokens and the connection completes on its own. A flow waits up to 5 minutes for you, and an unfinished attempt expires after 15.当 agent 首次连到需要授权的服务器，连接不会直接失败——它会抛出一个携带授权 URL 的待定状态，你看到的就是这个 URL。点同意后，回调落在 Starchild 标准的交接页；授权码自动换成 token，连接随即自行完成。一次流程最多等你 5 分钟，未完成的尝试 15 分钟后过期。
Three properties are worth naming, because each one closes a real hole:有三点值得点名，因为每一点都堵了一个真实的洞：
| Property性质 | Why it matters为什么重要 |
|---|---|
| Tokens are out of reachtoken 在 agent 够不到的地方 | Access and refresh tokens are written to a protected store the agent itself cannot read. It can use the connection without ever being able to print the credential.access 与 refresh token 写入 agent 自身读不到的保护区。它能使用这条连接，但永远无法打印出凭证本身。 |
| Only the owner can finish a flow只有 owner 能完成流程 | Completion is owner-gated, so a flow you started cannot be completed by anyone else who reaches the agent.完成动作有 owner 校验，你发起的流程不会被其他能触达该 agent 的人替你完成。 |
| One flow at a time, per server每个服务器同时只跑一个流程 | Starting a second authorization supersedes the first explicitly instead of two flows racing to write the same tokens.发起第二次授权会显式作废第一次，而不是让两个流程竞争写同一份 token。 |
Once a server is connected, each of its tools is registered under a namespaced name: mcp__<server>__<tool>. From there the model treats it exactly like a native tool.服务器连上后，它的每个工具都以带命名空间的名字注册：mcp__<server>__<tool>。此后模型对待它就跟原生工具完全一样。
Namespacing is not cosmetic. Two servers can legitimately both export search, and without a prefix the second one would silently shadow the first. The separator is also why server names may not contain a double underscore — the split has to stay unambiguous.命名空间不是装饰。两个服务器完全可能都导出 search，没有前缀时后者会静默覆盖前者。这个分隔符也解释了为什么服务器名不能含双下划线——拆分必须无歧义。
Config is hot-reloaded. Edit the server list and the change is applied as a diff — new servers connect, removed ones are dropped along with their tools, and a server whose settings did not actually change is left connected rather than being cycled. A server that announces its own tool list changed gets re-registered live, without a restart.配置支持热重载。改动服务器列表后按差异应用——新服务器连接、被删除的连同其工具一起下线，而设置没有实际变化的服务器保持连接、不做无谓重连。服务器若自己声明工具列表变了，会当场重新注册，无需重启。
An MCP server is someone else's code, and its tool descriptions go straight into your model's prompt. That is an injection surface, and it is treated as one.MCP 服务器是别人的代码，而它的工具描述会直接进入你模型的提示词。这是一个注入面，也被当作注入面对待。
Descriptions are scanned for injection patterns — "ignore previous instructions", fabricated tool-call blocks, instructions to call sensitive tools. A flagged description is not dropped: a clumsy-but-legitimate server should not silently lose its tools. Instead it is wrapped in an explicit untrusted-content banner, the same treatment given to any other untrusted tool output, so the model reads it as data.描述会被扫描注入特征——「忽略先前指令」、伪造的工具调用块、诱导调用敏感工具的指示。被标记的描述不会被丢弃：一个笨拙但合法的服务器不该无声无息地丢掉工具。取而代之的是包上明确的「不可信内容」标识——与其他不可信工具输出同等待遇——让模型把它当数据读。
| Limit限制 | Value取值 | Reason原因 |
|---|---|---|
| Description length描述长度 | 2,000 | An enormous description is both a red flag and a token sink.超长描述既是危险信号，也是 token 黑洞。 |
| Tools per server每服务器工具数 | 200 | A server exporting an absurd number of tools recreates the bloat the roster exists to prevent.导出过量工具的服务器会重新制造 roster 本来要防的膨胀。 |
| Roster charactersroster 字符数 | 8,000 | Enforced at registration, so every registered tool is always listed and reachable — never registered-but-invisible.在注册阶段就卡死，保证每个已注册工具都被列出且可达——不会出现「注册了但看不见」。 |
Server and tool names get stricter treatment than descriptions. They end up as bare identifiers in the prompt and as registry keys, so they cannot be banner-wrapped — a name containing a quote or a newline would break the prompt structure outright. Names are held to a strict allowlist and anything outside it is refused.服务器名与工具名比描述管得更严。它们会作为裸标识符进入提示词并充当注册表键，无法用标识包裹——名字里混入引号或换行会直接破坏提示词结构。名字被严格白名单约束，越界一律拒绝。
Remote dependencies fail. The design assumption is that a broken server degrades your agent slightly, never stalls it.远程依赖会挂。设计前提是：坏掉的服务器只让 agent 略微降级，绝不拖死它。
| Failure故障 | Behaviour行为 |
|---|---|
| Server permanently dead服务器彻底挂掉 | Reconnects back off exponentially, 15s → 300s, instead of retrying every 15s forever and paying a connect timeout each round.重连按指数退避，15 秒 → 300 秒，而不是永远每 15 秒重试一次、每轮都付一次连接超时。 |
| Token revokedtoken 被吊销 | Surfaces as an authorization-required state with a fresh authorize URL — you re-approve, you do not reconfigure.呈现为「需要授权」状态并附上新的授权 URL——你重新点同意即可，不必重配。 |
| Opaque transport error难解的传输错误 | Nested SDK errors are unwrapped to the innermost real cause, so the status view never shows a blank message.嵌套的 SDK 错误会被拆到最内层的真实原因，状态视图不会显示空白错误。 |
Both add capability, and they are not competitors — they solve different halves of the problem.两者都在增加能力，但不是竞争关系——它们解决的是问题的不同两半。
| MCP | SkillSkill | |
|---|---|---|
| What it is是什么 | A live connection to someone else's tool server到别人工具服务器的一条实时连接 | Instructions that teach the agent a workflow教会 agent 某套工作流的说明书 |
| Provides提供 | Callable tools, defined and hosted by the vendor由服务方定义并托管的可调用工具 | Know-how: which calls, in what order, with what gotchas诀窍：调什么、按什么顺序、有哪些坑 |
| Reach for it when什么时候用 | The service ships an MCP server and you want its tools as-is服务方发布了 MCP 服务器，你想直接用它的工具 | The task needs judgement, sequencing, or spans several services任务需要判断、编排，或跨多个服务 |
In practice they stack: an MCP server supplies the raw calls, a skill encodes the workflow that uses them well. See Skills for the other half, and Capability Discovery for how the agent decides which route a task should take.实践中两者叠加：MCP 服务器提供原始调用，skill 则沉淀出用好它们的工作流。另一半见 Skills，agent 如何决定走哪条路见能力发现。