Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 5cf97d0

Browse files
georgeatparallellizhengfeng101
georgeatparallel
and
lizhengfeng101
authored
docs(mcp): document remote setup with Parallel Search example (#1107)
* docs(mcp): document remote setup with Parallel Search example * docs(mcp): make the remote example vendor-neutral and sync translations Addresses review feedback on the remote MCP section: - Replace the Parallel Search example with a generic `search` server at https://mcp.example.com/mcp exposing ["search", "fetch"], matching the `@acme/docs-mcp-server` placeholder style used elsewhere on the page. Keeps the security guidance (user config applies across repositories, tool arguments leave your machine, no secrets or internal URLs) without the vendor-specific legal links. - Drop the duplicate `ocr config unset` block that sat directly above "Removing an MCP server", which already documents the same command. - Document the remaining remote failure modes in Troubleshooting: the missing-URL warning, the empty header expansion (a hard failure, now also stated in the `headers` row), and the dedicated 401/403 messages. Normalize the new bullets to the existing `message` — explanation form. - Mirror the whole section into the zh, ja, ko, and ru guides. --------- Co-authored-by: kite <[email protected]>
1 parent 24edcbd commit 5cf97d0

5 files changed

Lines changed: 273 additions & 25 deletions

File tree

‎pages/src/content/docs/en/mcp.md‎

Lines changed: 60 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ cover it — MCP is for reaching beyond the checkout.
2626

2727
## Configuration
2828

29-
#### Adding an MCP server
29+
#### Adding a local MCP server
3030

3131
The `ocr config set` command writes these fields non-interactively. Array
3232
fields (`args`, `env`, `tools`) take a JSON array string:
@@ -48,6 +48,36 @@ ocr config set mcp_servers.docs.setup "npm install -g @acme/docs-mcp-server"
4848
ocr config set mcp_servers.docs.env '["DOCS_TOKEN=secret", "DOCS_REGION=eu"]'
4949
```
5050

51+
#### Adding a remote MCP server
52+
53+
For servers that support **Streamable HTTP**, set `type` to `remote` and
54+
provide a `url` instead of a local command. Setting only `url` is not
55+
enough: the default type is `stdio`.
56+
57+
Use a new server name so these commands do not overwrite an existing
58+
connection:
59+
60+
```bash
61+
ocr config set mcp_servers.search.type remote
62+
ocr config set mcp_servers.search.url https://mcp.example.com/mcp
63+
ocr config set mcp_servers.search.tools '["search", "fetch"]'
64+
```
65+
66+
These commands save the connection in your user config. On the next
67+
review, OCR connects and makes `search` and `fetch` available to the
68+
agent alongside the built-in tools. The tool allowlist keeps any
69+
additional tools the server might offer out of the review. Other
70+
configured servers and your review settings are unchanged.
71+
72+
Once configured, the agent can call these tools during reviews without
73+
asking before each call. Tool arguments — search queries, requested URLs,
74+
and any context the agent includes — leave your machine and reach whoever
75+
operates the endpoint. Because this is user configuration, it applies
76+
across repositories: enable it only where external requests are allowed,
77+
and do not include secrets, private code, or internal URLs in requests.
78+
Review the operator's privacy policy and terms before connecting a
79+
third-party service.
80+
5181
#### Removing an MCP server
5282

5383
Remove a server with `unset`:
@@ -60,11 +90,20 @@ MCP servers live under the `mcp_servers` key in your user config file (`~/.openc
6090

6191
| Field | Type | Required | Description |
6292
|---|---|---|---|
63-
| `command` | string | ✓ | Executable that starts the MCP server (e.g. `npx`, `uvx`, an absolute path). |
64-
| `args` | string array | | Arguments passed to `command`. |
93+
| `type` | string | | `stdio` (default) for a local subprocess, or `remote` for Streamable HTTP. |
94+
| `command` | string | For `stdio` | Executable that starts the MCP server (e.g. `npx`, `uvx`, an absolute path). |
95+
| `args` | string array | | Arguments passed to `command` (`stdio` only). |
96+
| `url` | string | For `remote` | HTTP or HTTPS MCP endpoint. |
97+
| `headers` | object | | HTTP header names and string values (`remote` only). Values expand `$VAR` or `${VAR}` from OCR's environment at connection time; a value that expands to empty **fails the connection** rather than being sent empty or dropped. Omit for anonymous access. |
6598
| `tools` | string array | | Allowlist of tool names to register. Empty = register every tool the server offers. |
66-
| `setup` | string | | Shell command run once before the server starts (e.g. install deps). Runs in the repo root with a 5-minute timeout. |
67-
| `env` | string array | | Extra environment variables in `KEY=VALUE` form. |
99+
| `setup` | string | | Shell command run once before the server starts (`stdio` only, e.g. install deps). Runs in the repo root with a 5-minute timeout. |
100+
| `env` | string array | | Extra subprocess environment variables in `KEY=VALUE` form (`stdio` only). |
101+
102+
For remote servers that require authentication, follow that server's
103+
instructions for `headers`. Use single quotes around JSON passed to
104+
`ocr config set` when it contains environment variable references, so
105+
your shell does not expand them before OCR saves the configuration.
106+
Servers that allow anonymous access need no `headers` at all.
68107

69108
## Filtering tools
70109

@@ -104,11 +143,27 @@ pollute `--format json` output on stdout:
104143
- `Running setup for MCP server "x": …` — the setup command is executing.
105144
- `failed to start MCP server "x": …` — the subprocess didn't connect
106145
within the 30-second init timeout, or `command` isn't on `PATH`.
146+
- `remote MCP server "x" has no URL configured, skipping` — `type` is
147+
`remote` but `url` is unset; the mirror image of setting `url` without
148+
`type`.
149+
- `failed to connect to remote MCP server "x": …` — the endpoint didn't
150+
connect or list its tools within the 30-second init timeout. Check the
151+
URL, network access, and any required headers.
152+
- `MCP server "x" header "h" expanded to empty value` — a `$VAR` in
153+
`headers` isn't set in OCR's environment. This fails the connection; it
154+
is not treated as an absent header.
155+
- `remote MCP server "x" returned HTTP 401 Unauthorized` — check the token
156+
or header configuration.
157+
- `remote MCP server "x" returned HTTP 403 Forbidden` — the credentials
158+
reached the server but lack the required permissions.
107159
- `tool "y" conflicts with built-in tool, skipping` — rename the server's
108160
tool or drop it from `tools`.
109161
- `allowed tool "y" not found in server's tool list` — the name in `tools`
110162
doesn't match anything the server offers; check spelling.
111163

164+
A server that fails to start or connect is skipped; the review proceeds
165+
without its tools.
166+
112167
## See also
113168

114169
- [Tools](../tools/) — the six built-in tools MCP tools sit beside.

‎pages/src/content/docs/ja/mcp.md‎

Lines changed: 54 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@ OCR は **Model Context Protocol（MCP）クライアント**として動作で
2525

2626
## 設定
2727

28-
#### MCP server を追加する
28+
#### ローカル MCP server を追加する
2929

3030
`ocr config set` コマンドはこれらのフィールドを非対話的に書き込みます。配列
3131
フィールド（`args`、`env`、`tools`）は JSON 配列文字列を受け取ります：
@@ -47,6 +47,33 @@ ocr config set mcp_servers.docs.setup "npm install -g @acme/docs-mcp-server"
4747
ocr config set mcp_servers.docs.env '["DOCS_TOKEN=secret", "DOCS_REGION=eu"]'
4848
```
4949

50+
#### リモート MCP server を追加する
51+
52+
**Streamable HTTP** に対応した server では、`type` を `remote` にし、ローカル
53+
コマンドの代わりに `url` を指定します。`url` だけでは足りません：デフォルトの
54+
type は `stdio` です。
55+
56+
既存の接続を上書きしないよう、新しい server 名を使ってください：
57+
58+
```bash
59+
ocr config set mcp_servers.search.type remote
60+
ocr config set mcp_servers.search.url https://mcp.example.com/mcp
61+
ocr config set mcp_servers.search.tools '["search", "fetch"]'
62+
```
63+
64+
これらのコマンドは接続をユーザー設定に保存します。次回のレビューで OCR が接続し、
65+
`search` と `fetch` を組み込みツールと並べてエージェントに提供します。ツールの
66+
許可リストにより、server が提供しうるそれ以外のツールはレビューに入りません。
67+
他の設定済み server とレビュー設定は変更されません。
68+
69+
設定後、エージェントはレビュー中に呼び出しごとの確認なしでこれらのツールを
70+
使えます。ツール引数 —— 検索クエリ、要求する URL、エージェントが添える
71+
コンテキスト —— はあなたのマシンを離れ、そのエンドポイントの運営者に届きます。
72+
これはユーザー設定なのでリポジトリを跨いで適用されます：外部リクエストが許される
73+
場所でのみ有効にし、リクエストに秘密情報、非公開コード、社内 URL を含めないで
74+
ください。サードパーティのサービスに接続する前に、運営者のプライバシーポリシーと
75+
利用規約を確認してください。
76+
5077
#### MCP server を削除する
5178

5279
`unset` で server を削除します：
@@ -59,11 +86,19 @@ MCP server はユーザー設定ファイル（`~/.opencodereview/config.json`
5986

6087
| フィールド | 型 | 必須 | 説明 |
6188
|---|---|---|---|
62-
| `command` | string | ✓ | MCP server を起動する実行ファイル（`npx`、`uvx`、絶対パスなど）。 |
63-
| `args` | string 配列 | | `command` に渡す引数。 |
89+
| `type` | string | | ローカルのサブプロセスなら `stdio`（デフォルト）、Streamable HTTP なら `remote`。 |
90+
| `command` | string | `stdio` では必須 | MCP server を起動する実行ファイル（`npx`、`uvx`、絶対パスなど）。 |
91+
| `args` | string 配列 | | `command` に渡す引数（`stdio` のみ）。 |
92+
| `url` | string | `remote` では必須 | HTTP または HTTPS の MCP エンドポイント。 |
93+
| `headers` | object | | HTTP ヘッダー名と文字列値（`remote` のみ）。値は接続時に OCR の環境から `$VAR` または `${VAR}` を展開します。空文字列に展開された値は、空のまま送信されたり無視されたりせず、**接続を失敗させます**。匿名アクセスでは省略します。 |
6494
| `tools` | string 配列 | | 登録するツール名の許可リスト。空 = server が提供する全ツールを登録。 |
65-
| `setup` | string | | server 起動前に一度実行される shell コマンド（依存関係のインストールなど）。リポジトリのルートで実行、タイムアウト 5 分。 |
66-
| `env` | string 配列 | | 追加の環境変数、`KEY=VALUE` 形式。 |
95+
| `setup` | string | | server 起動前に一度実行される shell コマンド（`stdio` のみ、依存関係のインストールなど）。リポジトリのルートで実行、タイムアウト 5 分。 |
96+
| `env` | string 配列 | | サブプロセスへの追加の環境変数、`KEY=VALUE` 形式（`stdio` のみ）。 |
97+
98+
認証が必要なリモート server では、その server の指示に従って `headers` を設定して
99+
ください。`ocr config set` に渡す JSON に環境変数の参照が含まれる場合は、OCR が
100+
設定を保存する前に shell が展開してしまわないよう、シングルクォートで囲みます。
101+
匿名アクセスを許す server では `headers` は一切不要です。
67102

68103
## ツールのフィルタリング
69104

@@ -101,11 +136,25 @@ stdout の `--format json` 出力を汚染することはありません：
101136
- `Running setup for MCP server "x": …` —— setup コマンドを実行中。
102137
- `failed to start MCP server "x": …` —— サブプロセスが 30 秒の初期化タイムアウト内に
103138
接続できなかったか、`command` が `PATH` にない。
139+
- `remote MCP server "x" has no URL configured, skipping` —— `type` が `remote` なのに
140+
`url` が未設定。`url` だけ設定して `type` を忘れる場合の裏返し。
141+
- `failed to connect to remote MCP server "x": …` —— エンドポイントが 30 秒の初期化
142+
タイムアウト内に接続できなかった、またはツール一覧を返せなかった。URL、ネットワーク
143+
到達性、必要なヘッダーを確認。
144+
- `MCP server "x" header "h" expanded to empty value` —— `headers` の `$VAR` が OCR の
145+
環境に設定されていない。ヘッダーが無いものとして扱われるのではなく、接続が失敗する。
146+
- `remote MCP server "x" returned HTTP 401 Unauthorized` —— トークンやヘッダーの設定を
147+
確認。
148+
- `remote MCP server "x" returned HTTP 403 Forbidden` —— 認証情報は server に届いたが、
149+
必要な権限が不足している。
104150
- `tool "y" conflicts with built-in tool, skipping` —— server のツールを改名するか、
105151
`tools` から外す。
106152
- `allowed tool "y" not found in server's tool list` —— `tools` の名前が server の提供
107153
する何にも一致しない。スペルを確認。
108154

155+
起動または接続に失敗した server はスキップされ、そのツールなしでレビューが続行され
156+
ます。
157+
109158
## 関連項目
110159

111160
- [ツール](../tools/) —— MCP ツールが並ぶ 6 つの組み込みツール。

‎pages/src/content/docs/ko/mcp.md‎

Lines changed: 53 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@ diff 바깥에 있는 맥락이 리뷰에 도움이 될 때 MCP 서버를 붙입
2525

2626
## 설정 {#configuration}
2727

28-
#### MCP 서버 추가하기 {#adding-an-mcp-server}
28+
#### 로컬 MCP 서버 추가하기 {#adding-a-local-mcp-server}
2929

3030
`ocr config set` 명령이 아래 필드를 대화 없이 기록합니다. 배열 필드(`args`,
3131
`env`, `tools`)에는 JSON 배열 문자열을 넘깁니다.
@@ -47,6 +47,32 @@ ocr config set mcp_servers.docs.setup "npm install -g @acme/docs-mcp-server"
4747
ocr config set mcp_servers.docs.env '["DOCS_TOKEN=secret", "DOCS_REGION=eu"]'
4848
```
4949

50+
#### 원격 MCP 서버 추가하기 {#adding-a-remote-mcp-server}
51+
52+
**Streamable HTTP**를 지원하는 서버라면 `type`을 `remote`로 두고, 로컬 명령 대신
53+
`url`을 지정합니다. `url`만 설정하는 것으로는 부족합니다. 기본 type이
54+
`stdio`이기 때문입니다.
55+
56+
기존 연결을 덮어쓰지 않도록 새 서버 이름을 쓰세요.
57+
58+
```bash
59+
ocr config set mcp_servers.search.type remote
60+
ocr config set mcp_servers.search.url https://mcp.example.com/mcp
61+
ocr config set mcp_servers.search.tools '["search", "fetch"]'
62+
```
63+
64+
이 명령들은 연결을 사용자 설정에 저장합니다. 다음 리뷰에서 OCR이 서버에 접속해
65+
`search`와 `fetch`를 내장 도구와 나란히 Agent에게 넘깁니다. 도구 허용 목록이
66+
서버가 제공할 수 있는 나머지 도구를 리뷰 바깥에 남겨 둡니다. 이미 설정한 다른
67+
서버와 리뷰 설정은 그대로입니다.
68+
69+
설정을 마치면 Agent는 리뷰 중에 매번 묻지 않고 이 도구들을 부릅니다. 도구
70+
인자 — 검색어, 요청한 URL, Agent가 함께 실어 보내는 맥락 — 는 내 컴퓨터를 떠나
71+
그 엔드포인트를 운영하는 쪽에 닿습니다. 사용자 설정이므로 저장소를 가로질러
72+
적용됩니다. 외부 요청이 허용된 곳에서만 켜고, 요청에 비밀 값이나 비공개 코드,
73+
내부 URL을 담지 마세요. 서드파티 서비스에 연결하기 전에 운영자의 개인정보
74+
처리방침과 이용 약관을 확인하세요.
75+
5076
#### MCP 서버 제거하기 {#removing-an-mcp-server}
5177

5278
서버를 지울 때는 `unset`을 씁니다.
@@ -60,11 +86,19 @@ MCP 서버는 사용자 설정 파일(`~/.opencodereview/config.json`)의 `mcp_s
6086

6187
| 필드 | 타입 | 필수 | 설명 |
6288
|---|---|---|---|
63-
| `command` | 문자열 | ✓ | MCP 서버를 띄우는 실행 파일(예: `npx`, `uvx`, 절대 경로). |
64-
| `args` | 문자열 배열 | | `command`에 넘길 인자. |
89+
| `type` | 문자열 | | 로컬 하위 프로세스는 `stdio`(기본값), Streamable HTTP는 `remote`. |
90+
| `command` | 문자열 | `stdio`에 필수 | MCP 서버를 띄우는 실행 파일(예: `npx`, `uvx`, 절대 경로). |
91+
| `args` | 문자열 배열 | | `command`에 넘길 인자(`stdio` 전용). |
92+
| `url` | 문자열 | `remote`에 필수 | HTTP 또는 HTTPS MCP 엔드포인트. |
93+
| `headers` | 객체 | | HTTP 헤더 이름과 문자열 값(`remote` 전용). 값은 연결 시점에 OCR의 환경에서 `$VAR` 또는 `${VAR}`를 펼칩니다. 빈 문자열로 펼쳐진 값은 빈 채로 보내지거나 무시되지 않고 **연결을 실패시킵니다**. 익명 접근이면 생략합니다. |
6594
| `tools` | 문자열 배열 | | 등록할 도구 이름의 허용 목록. 비어 있으면 서버가 제공하는 모든 도구를 등록합니다. |
66-
| `setup` | 문자열 | | 서버가 뜨기 전에 한 번 실행하는 셸 명령(예: 의존성 설치). 저장소 루트에서 5분 제한으로 돕니다. |
67-
| `env` | 문자열 배열 | | `KEY=VALUE` 형태의 추가 환경 변수. |
95+
| `setup` | 문자열 | | 서버가 뜨기 전에 한 번 실행하는 셸 명령(`stdio` 전용, 예: 의존성 설치). 저장소 루트에서 5분 제한으로 돕니다. |
96+
| `env` | 문자열 배열 | | 하위 프로세스에 넘길 `KEY=VALUE` 형태의 추가 환경 변수(`stdio` 전용). |
97+
98+
인증이 필요한 원격 서버라면 그 서버의 안내에 따라 `headers`를 설정하세요.
99+
`ocr config set`에 넘기는 JSON에 환경 변수 참조가 들어 있으면, OCR이 설정을
100+
저장하기 전에 셸이 먼저 펼쳐 버리지 않도록 작은따옴표로 감싸세요. 익명 접근을
101+
허용하는 서버라면 `headers`는 아예 필요 없습니다.
68102

69103
## 도구 걸러 내기 {#filtering-tools}
70104

@@ -102,11 +136,25 @@ stdout의 `--format json` 출력을 더럽히지 않습니다.
102136
- `Running setup for MCP server "x": …` — setup 명령이 실행 중입니다.
103137
- `failed to start MCP server "x": …` — 하위 프로세스가 30초 초기화 제한 안에
104138
연결되지 않았거나, `command`가 `PATH`에 없습니다.
139+
- `remote MCP server "x" has no URL configured, skipping` — `type`은 `remote`인데
140+
`url`이 비어 있습니다. `url`만 넣고 `type`을 빠뜨리는 경우의 뒷면입니다.
141+
- `failed to connect to remote MCP server "x": …` — 엔드포인트가 30초 초기화 제한
142+
안에 연결되지 않았거나 도구 목록을 내주지 않았습니다. URL, 네트워크 접근,
143+
필요한 헤더를 확인하세요.
144+
- `MCP server "x" header "h" expanded to empty value` — `headers`에 쓴 `$VAR`가
145+
OCR의 환경에 없습니다. 헤더가 없는 것으로 넘어가지 않고 연결이 실패합니다.
146+
- `remote MCP server "x" returned HTTP 401 Unauthorized` — 토큰이나 헤더 설정을
147+
확인하세요.
148+
- `remote MCP server "x" returned HTTP 403 Forbidden` — 자격 증명은 서버에
149+
닿았지만 필요한 권한이 없습니다.
105150
- `tool "y" conflicts with built-in tool, skipping` — 서버 쪽 도구 이름을
106151
바꾸거나 `tools`에서 빼세요.
107152
- `allowed tool "y" not found in server's tool list` — `tools`에 적은 이름이
108153
서버가 제공하는 것과 맞지 않습니다. 철자를 확인하세요.
109154

155+
띄우거나 연결하는 데 실패한 서버는 건너뜁니다. 리뷰는 그 서버의 도구 없이
156+
이어집니다.
157+
110158
## 함께 보기 {#see-also}
111159

112160
- [도구](../tools/) — MCP 도구가 나란히 놓이는 내장 도구 여섯 가지.

0 commit comments

Comments
 (0)