# 快速开始

> 通过 MCP 接入 agent、授权，并用一次真实的工具调用验证连接。

URL: https://mcp-docs.opennomos.com/zh/docs/start/quickstart

最快的方式：给 agent 一行话，让它自己完成设置。

```text
set up https://service.opennomos.com/SKILL.md
```

这个文件里有各个宿主的命令、OAuth 步骤和下面的验证调用。你只需要登录并授权。本页其余内容是同一套流程的人类版。

## 1. 添加 MCP 服务

端点是 `https://mcp.opennomos.com/mcp`（无状态 Streamable HTTP,OAuth）。

<Tabs items={['Claude Code', 'Codex', 'Cursor 及其他宿主']}>
  <Tab value="Claude Code">
    ```sh
    claude mcp get opennomos || claude mcp add --transport http opennomos https://mcp.opennomos.com/mcp
    ```
    然后在 Claude Code 里运行 `/mcp`，选择 OpenNomos，在浏览器里完成认证。
  </Tab>
  <Tab value="Codex">
    ```sh
    codex mcp get opennomos || codex mcp add opennomos --url https://mcp.opennomos.com/mcp
    codex mcp login opennomos
    ```
    无界面环境：如果你的 Codex 版本支持，用 `codex mcp login opennomos --no-browser`。如果客户端注册失败，原因是服务端无法获取客户端的元数据文档，在该参数存在时加上 `--oauth-client-registration dcr` 重试。
  </Tab>
  <Tab value="Cursor 及其他宿主">
    把下面这段合并进宿主的 MCP 配置，保留已有条目：
    ```json
    {
      "mcpServers": {
        "opennomos": { "url": "https://mcp.opennomos.com/mcp" }
      }
    }
    ```
    然后使用宿主的认证操作。只有设置界面的宿主，需要在界面里添加这个 URL。
  </Tab>
</Tabs>

## 2. 授权

浏览器会打开登录页（邮箱验证码）和授权页，你在授权页选择工作区。凭据由客户端保存，这条路径下不需要你创建或粘贴 API 密钥。

OpenNomos 支持动态客户端注册（DCR）。托管服务没有启用 Client ID Metadata Documents（CIMD），所以只提供 CIMD 的宿主需要改用 DCR 模式。

## 3. 用一次真实调用验证

让 agent 用 `{}` 调用 `discover_tools`:

```json
{ "tools": [{ "name": "discover_tools", "summary": "…" }, "…"], "sources": { "web": true, "reddit": true }, "source_endpoints": { } }
```

调用成功，说明连接确实通到了你的工作区。它用的是 Core 工具包，不调用任何付费服务商，不创建项目，也不写入记忆。只保存了服务器 URL **不算**设置成功：如果宿主需要重新加载才会显示新工具，请重新加载后再调用一次。

## 4. 试一次有用的调用

```json
{ "query": "alternatives to Notion", "sources": ["reddit", "web"], "limit": 5 }
```

把它传给 [`search_signals`](https://mcp-docs.opennomos.com/zh/docs/tools/research/search_signals.md)。你会拿到来源条目，什么都不会被保存。想留下某些内容时，见[记忆与机会](https://mcp-docs.opennomos.com/zh/docs/growth-loop/memory-vs-opportunity.md)。

## 改用 API 密钥

不支持 OAuth 的宿主可以用控制台创建的密钥（`on_live_…`；只显示一次，服务端只存哈希）。把它放在宿主的凭据库或环境变量里：

```sh
curl --fail-with-body https://service.opennomos.com/v1/tools \
  -H "Authorization: Bearer $OPENNOMOS_API_KEY"
```

详见 [REST 与 CLI](https://mcp-docs.opennomos.com/zh/docs/reference/rest-and-cli.md)。

## 出问题时

| 现象 | 怎么办 |
| --- | --- |
| `401` | 完成 OAuth，或更换无效的密钥。被撤销的连接需要重新授权。 |
| `pack_required` | 该工具需要的工具包没有启用；响应里带有控制台 URL。 |
| `soft_limit` | 该工具包的每月上游成本上限已用完。 |
| 带 `reason` 和 `action` 的结果 | 某个上游来源出了问题。见[错误](https://mcp-docs.opennomos.com/zh/docs/reference/errors.md)。 |