@gaiventures/pilotfish-mcp-managed 0.1.21 → 0.1.22

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +173 -87
  2. package/cli.js +5 -5
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -2,50 +2,48 @@
2
2
 
3
3
  [![npm](https://img.shields.io/npm/v/@gaiventures/pilotfish-mcp-managed)](https://www.npmjs.com/package/@gaiventures/pilotfish-mcp-managed)
4
4
 
5
- Hand whole browser tasks to [pilotfish](https://pilotfish.gai.ventures) from any AI agent. Your agent says what
6
- it wants done ("download last month's invoices from our AWS billing console", "pull the risk factors from Apple's
7
- latest 10-K on SEC EDGAR"). pilotfish does it in a cloud browser, signed in as you, and returns the answer and any
8
- files.
5
+ Hand whole browser tasks to [pilotfish](https://pilotfish.gai.ventures) from any AI agent. Your agent says what it
6
+ wants done ("download last month's invoices from our AWS billing console", "pull the risk factors from Apple's latest
7
+ 10-K on SEC EDGAR"). pilotfish does it in a cloud browser and returns the answer and any files.
9
8
 
10
- Works with Claude Code, Claude.ai, Claude Desktop, Codex CLI, Cursor, VS Code and any other
11
- [MCP](https://modelcontextprotocol.io) client.
9
+ It works with Claude Code, Claude.ai, Claude Desktop, Codex CLI, Cursor, VS Code and any other
10
+ [MCP](https://modelcontextprotocol.io) client. Clients that take a URL connect to `https://pilotfish-be.gai.ventures/mcp`
11
+ directly. This package is a small relay for clients that can only start a local (stdio) server.
12
12
 
13
- > **You need a pilotfish account to use this.** [Sign up](https://pilotfish.gai.ventures/signup) and add credits
14
- > (from $10) to your organization. Then sign in from your client (OAuth: it acts as you, with your saved logins), or
15
- > use one of your organization's API keys, which its admins create under **Org settings → API keys**. See
16
- > [Get started](#get-started).
13
+ > **You need a pilotfish account.** [Sign up with Google](https://pilotfish.gai.ventures/signup): you name your
14
+ > organization and become its admin. Or accept an invitation to join someone else's. Tasks are paid from the
15
+ > organization's credits.
16
+
17
+ Want a browser on your own computer for free, driven by your agent's own model, with no account? Use the open
18
+ [`@gaiventures/pilotfish-mcp`](https://www.npmjs.com/package/@gaiventures/pilotfish-mcp) instead.
17
19
 
18
20
  ## Why managed
19
21
 
20
- - **One call per task.** pilotfish plans and runs the task on its own models and checks the answer.
21
- Your agent spends a tool call or two, not a context full of web pages.
22
- - **Signed in as you.** Save a login once in the app and every task can use it. Sessions are kept between runs,
23
- and two-factor codes, emailed codes and phone sign-in by code are handled.
22
+ - **One call per task.** pilotfish plans and runs the task on its own models and checks the answer. Your agent spends
23
+ a tool call or two, not a context full of web pages.
24
+ - **Signed in as you.** Save a login once in the app and every task can use it. Sessions are kept between runs, and
25
+ two-factor codes, emailed codes and phone sign-in by code are handled.
24
26
  - **Gets through where plain browsers stop.** Residential IPs in your country, stealth browsing and CAPTCHA solving
25
27
  are on by default, with per-site settings. When something truly needs you, you get a link.
26
- - **Always on.** Tasks run in the cloud, so they carry on while your laptop sleeps. Follow up on a session later
27
- and it picks up where it left off.
28
- - **You can see everything.** Watch any task live or take control, replay it afterwards, and see what each one
29
- cost.
30
- - **Safe with money and messages.** Payments, orders and messages wait for your approval unless you allow them up
31
- front, and your codes and passwords never pass through the agent.
32
-
33
- Prefer to drive a browser on your own computer, for free? Use the local
34
- [`@gaiventures/pilotfish-mcp`](https://www.npmjs.com/package/@gaiventures/pilotfish-mcp). It needs no account.
28
+ - **Always on.** Tasks run in the cloud, so they carry on while your laptop sleeps. A follow-up picks up the same
29
+ session where it left off.
30
+ - **You can see everything.** Watch any task live or take control, replay it afterwards, and see what each one cost.
31
+ - **Safe with money and messages.** Payments, orders and messages wait for a person's yes unless the task's own words
32
+ allow them, and codes and passwords never pass through the agent.
35
33
 
36
34
  ## Get started
37
35
 
38
- 1. **Sign up** at [pilotfish.gai.ventures/signup](https://pilotfish.gai.ventures/signup) with your Google account.
39
- 2. **Add credits.** Pay as you go, from $10, under **Usage → Credits**.
40
- 3. **Sign in, or get an API key.** Clients that sign in with OAuth (Claude.ai, Claude Desktop, Claude Code and most
41
- others) need no key. Otherwise ask an admin of your organization for one of its API keys: they create them under
42
- **Org settings → API keys** (`https://pilotfish.gai.ventures/org?view=keys`).
43
- 4. **Connect your agent** with the steps below.
36
+ 1. **Have an account.** [Sign up with Google](https://pilotfish.gai.ventures/signup) and name your organization (you
37
+ become its primary admin), or accept an emailed invitation to join an existing one as a member or an admin.
38
+ 2. **Make sure the organization has credits.** Admins add them under **Usage → Credits** in the app (pay as you go,
39
+ from $10, with optional auto reload). Members run tasks on the organization's credits within any allowance an
40
+ admin sets for them.
41
+ 3. **Connect your agent** (below). The simplest way is to sign in from your client, which then acts as you. Scripts,
42
+ servers and shared agents use one of the organization's API keys instead.
44
43
 
45
44
  ## Connect
46
45
 
47
- The endpoint is `https://pilotfish-be.gai.ventures/mcp`. Clients that take a URL connect to it directly and need
48
- no package. This package is a small relay for clients that can only start a local (stdio) server.
46
+ The endpoint is `https://pilotfish-be.gai.ventures/mcp` (Streamable HTTP).
49
47
 
50
48
  ### Claude Code
51
49
 
@@ -53,14 +51,15 @@ no package. This package is a small relay for clients that can only start a loca
53
51
  claude mcp add --transport http pilotfish https://pilotfish-be.gai.ventures/mcp
54
52
  ```
55
53
 
56
- Claude Code opens pilotfish's sign-in the first time. To use a key instead, add
57
- `--header "Authorization: Bearer pf_YOUR_KEY"`.
54
+ Then run `/mcp` in Claude Code, choose pilotfish and sign in with your pilotfish account. To use an API key instead,
55
+ add `--header "Authorization: Bearer pf_YOUR_KEY"` to the command.
58
56
 
59
57
  ### Claude.ai and Claude Desktop
60
58
 
61
- Settings → Connectors → Add custom connector → `https://pilotfish-be.gai.ventures/mcp`, then sign in.
59
+ **Settings → Connectors → Add custom connector**, paste `https://pilotfish-be.gai.ventures/mcp`, connect, and sign in.
60
+ No key is needed.
62
61
 
63
- ### Cursor, Windsurf, VS Code and other clients that take a URL
62
+ ### Cursor, Windsurf and other clients that take a URL
64
63
 
65
64
  ```json
66
65
  {
@@ -73,6 +72,24 @@ Settings → Connectors → Add custom connector → `https://pilotfish-be.gai.v
73
72
  }
74
73
  ```
75
74
 
75
+ A client that supports MCP sign-in (OAuth) can leave out `headers` and sign in instead.
76
+
77
+ ### VS Code
78
+
79
+ In `.vscode/mcp.json`:
80
+
81
+ ```json
82
+ {
83
+ "servers": {
84
+ "pilotfish": {
85
+ "type": "http",
86
+ "url": "https://pilotfish-be.gai.ventures/mcp",
87
+ "headers": { "Authorization": "Bearer pf_YOUR_KEY" }
88
+ }
89
+ }
90
+ }
91
+ ```
92
+
76
93
  ### Codex CLI
77
94
 
78
95
  In `~/.codex/config.toml`, through this package:
@@ -82,7 +99,7 @@ In `~/.codex/config.toml`, through this package:
82
99
  command = "npx"
83
100
  args = ["-y", "@gaiventures/pilotfish-mcp-managed"]
84
101
  env = { PILOTFISH_KEY = "pf_YOUR_KEY" }
85
- # browser_task waits up to 120 s for a result (the task carries on); Codex stops a call after 60 s by default.
102
+ # A call returns within 120 s (the task carries on); Codex stops a call after 60 s by default.
86
103
  tool_timeout_sec = 180
87
104
  ```
88
105
 
@@ -100,6 +117,10 @@ tool_timeout_sec = 180
100
117
  }
101
118
  ```
102
119
 
120
+ The relay needs Node.js 22 or newer. It only forwards messages to the endpoint with your key; the browser runs in
121
+ pilotfish's cloud. On native Windows, if your client cannot start `npx`, use `"command": "cmd"` with
122
+ `"args": ["/c", "npx", "-y", "@gaiventures/pilotfish-mcp-managed"]`.
123
+
103
124
  ### Check a key
104
125
 
105
126
  Prints the endpoint and the tools, or why the key was refused:
@@ -108,90 +129,155 @@ Prints the endpoint and the tools, or why the key was refused:
108
129
  PILOTFISH_KEY=pf_YOUR_KEY npx -y @gaiventures/pilotfish-mcp-managed --check
109
130
  ```
110
131
 
111
- In Windows PowerShell: `$env:PILOTFISH_KEY = "pf_YOUR_KEY"; npx -y @gaiventures/pilotfish-mcp-managed --check`.
132
+ In Windows PowerShell:
112
133
 
113
- ## API keys
134
+ ```powershell
135
+ $env:PILOTFISH_KEY = "pf_YOUR_KEY"; npx -y @gaiventures/pilotfish-mcp-managed --check
136
+ ```
137
+
138
+ `--version` prints the relay's version.
139
+
140
+ ## Signing in or an API key
141
+
142
+ | | **Signing in** (OAuth) | **An organization API key** (`pf_…`) |
143
+ | --- | --- | --- |
144
+ | Who it acts as | You | The organization, as no particular person |
145
+ | Who can use it | Only you | Anyone who has the key: keep it secret |
146
+ | Saved logins, site profiles, saved tasks | Yours | The organization's own set, apart from every person's |
147
+ | Tasks it sees | Your own; an admin can also open any of the organization's tasks by id | Only the tasks started with that key |
148
+ | Paid from | The organization's credits, within your allowance if you have one | The organization's credits, within the key's allowance if it has one |
149
+ | Who sets it up | You, from your client | The organization's admins, under **Org settings → API keys** |
150
+
151
+ **About keys.** Admins create, show again, copy, rotate and revoke keys under **Org settings → API keys**
152
+ (`https://pilotfish.gai.ventures/org?view=keys`). Rotating gives a new value under the same name, and the old one stops
153
+ working at once; rotate a key when someone who had it leaves. Each key has its own page with what it spent, its tasks
154
+ through the MCP and the API, and its sessions. An admin can give a key an allowance: a spending limit on the
155
+ organization's credits, with an optional automatic top-up.
156
+
157
+ ## Organizations, members and money
158
+
159
+ Everyone is in one organization, and its credits pay for every task its people and its keys run.
160
+
161
+ | | **Primary admin** | **Admins** | **Members** |
162
+ | --- | --- | --- | --- |
163
+ | Run tasks, connect agents, save logins | Yes | Yes | Yes |
164
+ | Add credits, card, auto reload | Yes | Yes | No |
165
+ | Monthly limit and overage | Yes | Yes | No |
166
+ | Invite people, change roles, set allowances | Yes | Yes | No |
167
+ | Create and manage API keys | Yes | Yes | No |
168
+ | See everyone's tasks and spending | Yes | Yes | No: their own, and their allowance |
169
+ | Hand the primary admin role to someone else | Yes | No | No |
170
+
171
+ - **Allowances.** An admin may give a member (or a key) a spending limit on the organization's credits. No limit is
172
+ the default. When it is used up, new tasks are refused and running ones pause until an admin raises it.
173
+ - **The monthly limit.** An admin may set one for the whole organization. The primary admin is emailed at 80% and at
174
+ 100%; at the limit, tasks pause and new ones are refused until an admin turns on overage or raises the limit.
175
+ - **One task at a time** per person and per key. Another task started meanwhile is refused until the first finishes
176
+ or is stopped.
177
+ - **Check-ins on long tasks.** A task that has spent a set amount ($1 by default) pauses and says what it found so
178
+ far; carry on with a follow-up, and it checks in again at the next step of that amount.
179
+ - **What your agent sees.** A refused task comes back with the reason and whom to ask:
180
+
181
+ | Reason | What it says | What to do |
182
+ | --- | --- | --- |
183
+ | `no_credits` | You're out of credits, or the balance is too low to start a task | An admin adds credits under **Usage → Credits**, or turns on auto reload |
184
+ | `allocation_used` | You've used your (or this key's) allowance, naming the admins to ask | An admin raises the allowance |
185
+ | `org_limit` | The organization has reached its monthly limit | An admin turns on overage or raises the limit |
186
+ | `one_session` | You already have a task running | Wait for it to finish, or stop it with `cancel_job` |
114
187
 
115
- API keys belong to your organization. Its admins create them under **Org settings → API keys** in the app
116
- (`https://pilotfish.gai.ventures/org?view=keys`), where each can be shown again, copied, rotated or revoked. A key runs
117
- tasks for the organization, paid from its credits, one task at a time, and with no one's saved logins; anyone given
118
- one can use it, so rotate a key when someone leaves. Admins can give a key an allowance (a spending limit, with an
119
- optional auto reload): once it is used, its tasks are refused (`allocation_used`) or pause until it is raised. Each
120
- key's page in the app shows what it spent, its tasks through the MCP and the API, and its sessions. To use your own saved logins, sign in from your client (OAuth)
121
- instead: no key needed.
188
+ `get_usage` shows where you stand: for an admin, the organization's balance and auto reload; for a member, their
189
+ allowance and whether the organization's credits are fine, low or out; for everyone, this month's spending against
190
+ the monthly limit and spending by category and by model.
122
191
 
123
192
  ## Tools
124
193
 
125
194
  | Tool | What it does |
126
195
  | --- | --- |
127
- | `browser_task` `{task, start_url?, region?, sites?, login?, stealth?, solve?, model?, quality?, max_steps?, pre_approved?, files?, wait?, wait_seconds?}` | Run a whole task as you. Waits for the result (up to `wait_seconds`, default 120; the task carries on after that, and `get_job` waits again), or with `wait: false` returns the job id at once. `model`: `auto` (Haiku does the task, Sonnet checks it), or one model for every step: `opus`, `sonnet`, `haiku`, `gpt-6-luna`, `gpt-5-mini` or `gpt-5-nano`. `region`: the country to browse from. `files`: up to 10 attachments (`{name, type?, data}` in base64, 25 MB each). |
128
- | `get_job` `{id, wait_seconds?}` | A job's status, open question and its answer link, result, cost so far, live-view link and files. Can wait for the job to finish or need you. A finished job reads `SUCCESS`, `PARTLY DONE` or `NOT DONE`; one that did not pass lists what of the task is done, what is not (with the evidence for each) and why it stopped. |
129
- | `get_file` `{id, file_id}` | One of the session's files, attached or downloaded. Up to 5 MB comes back in the result; larger files are linked. |
130
- | `list_jobs` `{status?, limit?}` | Your recent jobs with their cost; `[replay]` marks recorded ones. |
131
- | `follow_up` `{id, text, model?, region?, files?, wait?}` | Carry on in the same session: same browser while it is kept, same sign-ins, what earlier turns found. `region` runs the turn from another country (a site not reachable from the last one): it starts again in a new browser session there. |
132
- | `rerun_job` `{id, wait?}` | Run the same task with the same settings again. |
133
- | `answer_job` `{id, question_id, answer}` | Answer a job's question: yes, no, done, cancel or text. The id is in the job's `Question …` line, which also says what answer it takes. Codes and passwords go on the answer page, never here. |
134
- | `message_job` `{id, text}` | Pass on what the person says while a job runs ("take the cheaper one", a detail it asked for). It reads the message before its next step; the person's newest words win over the task; sent while the job waits on a question, it answers it. |
135
- | `take_control` `{id}` / `hand_back` `{id}` | Pause a job and get a link to drive its browser yourself, then let it carry on from there. |
196
+ | `browser_task` `{task, start_url?, region?, sites?, login?, stealth?, solve?, model?, quality?, max_steps?, pre_approved?, files?, wait?, wait_seconds?}` | Run a whole web task, however many sites and steps. Waits up to `wait_seconds` (default 120) and returns the result, or the job id if it is still running (it carries on; `get_job` waits again). `wait: false` returns the id at once. `model`: `gpt-6-luna` (the default), `auto` (Haiku does the task, Sonnet checks it), or one model for every step: `opus`, `sonnet`, `haiku`, `gpt-5-mini` or `gpt-5-nano`. `quality` (`auto`, `economy`, `accurate`) instead of one model; `model` wins. `region`: the country to browse from (`"us"`, `"in"`). `start_url`: the page to open first. `sites`: further sites whose saved logins the task may use. `login`: which of your accounts on those sites. `stealth` and `solve`: on by default; `false` turns them off for this run. `max_steps`: browser actions across the run. `pre_approved` (`{actions: [pay, delete, send, transfer, cancel], max_amount?, currency?}`): only with the person's say-so, final steps that run without asking. `files`: up to 10 attachments (`{name, type?, data}` in base64, 25 MB each). |
197
+ | `get_job` `{id, wait_seconds?}` | A job's status, its open question with the link to answer it, the result, the cost so far, the live-view link while it runs, and the session's files. `wait_seconds` waits for it to finish or need you first. |
198
+ | `get_file` `{id, file_id}` | One of the session's files, attached or downloaded. Up to 5 MB comes back in the result (an image as an image, text as text); larger files are linked in the app. |
199
+ | `list_jobs` `{status?, limit?}` | Your recent jobs, newest first, with their cost; `[replay]` marks recorded ones. `status`: `queued`, `running`, `needs_input`, `done`, `failed` or `cancelled`. |
200
+ | `follow_up` `{id, text, model?, region?, files?, wait?, wait_seconds?}` | Carry on in the same session: the same browser while it is kept, the same sign-ins, what earlier turns found ("now also…", "open the second one", "try again with…"). `model` changes this turn's model (`auto` routes again). `region` runs the turn from another country, in a new browser session there. |
201
+ | `rerun_job` `{id, wait?, wait_seconds?}` | Run the same task again with the same settings, as a new job. |
202
+ | `answer_job` `{id, question_id, answer}` | Answer a job's question: `yes`, `no`, `done` (handled in the browser), `cancel`, or text. The id is in the job's `Question …` line, which also says what answer it takes. Codes and passwords go on the answer page, never here. |
203
+ | `message_job` `{id, text}` | Pass on what the person says while a job runs ("take the cheaper one", a detail it asked for), in their words. It reads the message before its next step, and the person's newest words win over the task; sent while the job waits on a question, it answers it. |
204
+ | `take_control` `{id}` / `hand_back` `{id}` | Pause a running job and get a link to drive its browser yourself, then let it carry on from where you left it. |
136
205
  | `cancel_job` `{id}` | Stop a job. Cancelling a tool call that is waiting on a job stops the job too. |
137
- | `get_replay` `{id}` | The job's steps with timings and what got in the way, and a link to its replay video (valid for an hour). |
138
- | `list_saved_tasks` | Your saved tasks, their settings and how their last run went. |
139
- | `run_saved_task` `{id, extra_instructions?, start_url?, region?, sites?, stealth?, solve?, wait?}` | Run a saved task, with optional changes for this run only. |
140
- | `save_task` `{name, task? \| from_job?, …settings}` | Save a task, or a job's task with the settings it ran with. |
141
- | `update_saved_task` `{id, name?, task?, …settings}` | Rename a saved task or change its task or settings. |
206
+ | `get_replay` `{id}` | The job's steps with timings and what got in the way, and a link to its replay video (valid for an hour) when one was recorded. |
207
+ | `list_saved_tasks` | Your saved tasks: id, name, settings, how often and when they last ran, and what their last run needed. |
208
+ | `run_saved_task` `{id, extra_instructions?, start_url?, region?, sites?, stealth?, solve?, wait?, wait_seconds?}` | Run a saved task with its saved settings, with optional changes for this run only. |
209
+ | `save_task` `{name, task? \| from_job?, start_url?, region?, sites?, login?, stealth?, solve?, model?, quality?}` | Save a task to run again here or in the app: give the task and settings, or `from_job` to save a job's task with the settings it ran with. |
210
+ | `update_saved_task` `{id, name?, task?, …settings}` | Rename a saved task, change its task, or change only the settings given. |
142
211
  | `delete_saved_task` `{id}` | Delete a saved task. Its past runs stay in your history. |
143
- | `delete_session` `{id}` | Delete a session from your history: it no longer shows or opens anywhere; its record and cost are kept for billing. Logins, saved tasks and spending stay. |
144
- | `list_logins` | Sites you have saved logins for, with what is stored and each site's settings. Never a password or code. Logins are added in the app. |
145
- | `get_settings` / `update_site_settings` `{site, residential?, stealth?, solve?}` | Your sites and their settings: residential IP (auto, always or never), stealth and CAPTCHA solving. |
146
- | `get_usage` `{days?}` | Your organization's credits (your allowance and whether it is fine, low or out, for a member), this month's spending against its monthly limit, and spending by category and model. |
212
+ | `delete_session` `{id}` | Delete a session from your history: it no longer shows or opens anywhere; its record and cost are kept for billing. Logins, saved tasks and spending stay. Only with the person's say-so. |
213
+ | `list_logins` | Sites with saved logins: which accounts, whether a password and authenticator key are stored, what recent runs met there. Never a password or code. Logins are added in the app. |
214
+ | `get_settings` / `update_site_settings` `{site, residential?, stealth?, solve?}` | Your sites and their settings, and change one site's: residential IP (`auto`, `always` or `never`), stealth browsing, CAPTCHA solving. A change applies to every later task on that site. |
215
+ | `get_usage` `{days?}` | Your organization's credits as your role sees them (an admin: its balance and auto reload; a member: whether it is fine, low, out or at its limit), what is left of your allowance (or the key's), this month's spending against the organization's monthly limit, and the last `days` (default 30) of spending by category (model, residential IP, browser, CAPTCHA) and by model. |
216
+
217
+ ## What a job returns
218
+
219
+ A finished job starts with `SUCCESS`, `PARTLY DONE` or `NOT DONE`. One that did not fully pass lists what of the task
220
+ is done, what is not (each with its evidence) and why it stopped. A job still running says `Still running after
221
+ 120 s; the job carries on`, and your agent waits again with `get_job`. A job that needs a person shows the question,
222
+ a `Question <id>` line saying how to answer it, and the answer link.
223
+
224
+ ## Whole tasks or steps?
225
+
226
+ Send the whole web task in one `browser_task`, however many sites and steps it has: "find the cheapest return flight
227
+ on MakeMyTrip, then book a hotel near the beach for those dates on Booking.com", "read my last Swiggy order and add it
228
+ to my Splitwise group". pilotfish splits it into parts, asks for every sign-in it needs at the start, carries what
229
+ each site gives to the next and checks the end result. Split it yourself only where a step is not browser work (your
230
+ own code, files, an API) or needs your own decision between steps; then send each browser step with the values it
231
+ needs written in, or use `follow_up` to stay in the same browser and sign-ins. Say in the task what may be completed
232
+ without asking ("pay with my saved card", "go ahead and submit"); anything else that is final waits for a yes.
147
233
 
148
234
  ## Tasks that name no site
149
235
 
150
236
  Send them as they are: "the best free resource to learn linear algebra", "research Postgres vs MySQL for a startup".
151
- pilotfish searches the web first and answers from what it read, every fact linked to its page, in seconds and with
152
- no browser. When the answer needs a site (a fare for a date, a table to book, your own account), the browser starts
153
- on the site the search found, and a price or availability for particular dates is always read on the site itself.
237
+ pilotfish searches the web first and answers from what it read, every fact linked to its page, in seconds and with no
238
+ browser. When the answer needs a site (a fare for a date, a table to book, your own account), the browser starts on
239
+ the site the search found; a price or availability for particular dates is always read on the site itself.
154
240
 
155
241
  ## When the person says more mid-task
156
242
 
157
243
  Your agent reads what the person types only between tool calls, so `browser_task`, `follow_up` and `get_job` return
158
244
  within two minutes by default while the task carries on. Anything the person says meanwhile (a correction, a detail,
159
245
  the answer to the task's question) goes to the task with `message_job`, in their words, and the agent keeps waiting
160
- with `get_job`. The task reads it before its next step; sent while it waits on a question, it answers that question.
161
-
162
- ## Whole tasks or steps?
163
-
164
- Send the whole web task in one `browser_task`, however many sites and steps it has: "find the cheapest return
165
- flight on MakeMyTrip, then book a hotel near the beach for those dates on Booking.com", "read my last Swiggy
166
- order and add it to my Splitwise group". pilotfish splits it into parts, asks for every sign-in it needs at the
167
- start, carries what each site gives to the next (the flight's dates into the hotel search) and checks the end
168
- result. Split it yourself only where a step is not browser work (your own code, files, an API) or needs your own
169
- decision between steps; then send each browser step as its own `browser_task` with the values it needs written
170
- in, or use `follow_up` to stay in the same browser and sign-ins. Say what may be completed without asking ("pay
171
- with my saved card", "go ahead and submit"); anything else that is final waits for your yes.
246
+ with `get_job`.
172
247
 
173
- ## When a job needs you
248
+ ## When a job needs a person
174
249
 
175
- A one-time code, a CAPTCHA it could not clear, a sign-in or a payment to approve: clients that support it open
176
- pilotfish's answer page for you, and other clients get the link in the tool result. The answer page shows the
177
- browser live and lets you take over, so you can type a code or sign in right there.
250
+ A one-time code with no saved source, a CAPTCHA it could not clear, a sign-in or a payment to approve: clients that
251
+ support it open pilotfish's answer page, and other clients get the link in the tool result. The answer page shows the
252
+ browser live and lets the person take over, so they can type a code or sign in right there. Codes and passwords never
253
+ pass through the agent.
178
254
 
179
255
  ## Pricing
180
256
 
181
- Pay as you go from prepaid credit: the browser by the minute, residential traffic by the GB, models at their token
182
- price plus 20%, and CAPTCHAs per solve. Each task shows its cost as it runs. Full prices are on
183
- [pilotfish.gai.ventures/pricing](https://pilotfish.gai.ventures/pricing). For volume pricing or your own proxies,
184
- [talk to us](https://pilotfish.gai.ventures/contact).
257
+ Pay as you go from the organization's prepaid credit: browser time at $0.02 per browser-hour (billed in whole minutes),
258
+ residential traffic at $4 per GB, models at their token price plus 20%, and CAPTCHAs per solve. Each task shows its
259
+ cost as it runs. Full prices: [pilotfish.gai.ventures/pricing](https://pilotfish.gai.ventures/pricing). For volume
260
+ pricing or your own proxies, [talk to us](https://pilotfish.gai.ventures/contact).
185
261
 
186
262
  ## Settings
187
263
 
188
- Only for this package. Clients that connect to the URL need none.
264
+ Only for this package (the relay). Clients that connect to the URL need none.
189
265
 
190
266
  | Variable | Default | Meaning |
191
267
  | --- | --- | --- |
192
268
  | `PILOTFISH_KEY` | | One of your organization's API keys (`pf_…`). Required. |
193
269
  | `PILOTFISH_URL` | `https://pilotfish-be.gai.ventures` | The pilotfish API, or its `/mcp` URL. |
194
270
 
271
+ ## Troubleshooting
272
+
273
+ - **401 Unauthorized:** the key was revoked or rotated, or your organization was deleted. Ask an admin for a current
274
+ key (**Org settings → API keys**), or sign in from your client instead.
275
+ - **Codex stops the call after a minute:** keep `tool_timeout_sec = 180` as above; the task itself carries on.
276
+ - **`npx` fails, or the relay won't start:** check `node --version` is 22 or newer; on Windows, start it through
277
+ `cmd /c` as above.
278
+ - **A task is refused:** the reason and whom to ask are in the result; the table under "Organizations, members and
279
+ money" above lists each one.
280
+
195
281
  ## License
196
282
 
197
283
  This relay is MIT licensed. The pilotfish service is covered by its
package/cli.js CHANGED
@@ -10,7 +10,7 @@ import { Client } from "@modelcontextprotocol/sdk/client/index.js";
10
10
  import { isJSONRPCRequest, isJSONRPCResultResponse } from "@modelcontextprotocol/sdk/types.js";
11
11
 
12
12
  // packages/mcp-managed/dist/version.js
13
- var VERSION = true ? "0.1.21" : "0.0.0-dev";
13
+ var VERSION = true ? "0.1.22" : "0.0.0-dev";
14
14
 
15
15
  // packages/mcp-managed/dist/bridge.js
16
16
  var DEFAULT_URL = "https://pilotfish-be.gai.ventures";
@@ -23,9 +23,9 @@ function endpointOf(url = DEFAULT_URL) {
23
23
  function checkKey(key) {
24
24
  const k = (key ?? "").trim();
25
25
  if (!k)
26
- throw new Error("PILOTFISH_KEY is not set: create an MCP key in the pilotfish app (Settings \u2192 Connect an agent).");
26
+ throw new Error("PILOTFISH_KEY is not set: use one of your organization's API keys (an admin makes them in the pilotfish app: Org settings \u2192 API keys).");
27
27
  if (!/^pf_[A-Za-z0-9_-]{16,}$/.test(k))
28
- throw new Error("PILOTFISH_KEY does not look like a pilotfish MCP key (pf_...). Copy it again from Settings \u2192 Connect an agent.");
28
+ throw new Error("PILOTFISH_KEY does not look like a pilotfish API key (pf_...). Copy it again from Org settings \u2192 API keys.");
29
29
  return k;
30
30
  }
31
31
  function remoteTransport(o) {
@@ -34,7 +34,7 @@ function remoteTransport(o) {
34
34
  function explain(e) {
35
35
  const m = e instanceof Error ? e.message : String(e);
36
36
  if (/\b401\b|unauthori[sz]ed/i.test(m))
37
- return "pilotfish refused the MCP key (revoked, mistyped, or you left the workspace). Create a new one in the pilotfish app: Settings \u2192 Connect an agent.";
37
+ return "pilotfish refused the MCP key (revoked, rotated, mistyped, or its organization was deleted). Ask an admin of your organization for a current one (Org settings \u2192 API keys).";
38
38
  if (/fetch failed|ECONNREFUSED|ENOTFOUND|ETIMEDOUT/i.test(m))
39
39
  return `Cannot reach pilotfish (${m}). Check PILOTFISH_URL and your connection.`;
40
40
  return `pilotfish: ${m}`;
@@ -97,7 +97,7 @@ replays) as an MCP server over stdio.
97
97
  pilotfish-mcp-managed --version print the version
98
98
 
99
99
  Environment:
100
- PILOTFISH_KEY your MCP key (pf_...): pilotfish app \u2192 Settings \u2192 Connect an agent
100
+ PILOTFISH_KEY one of your organization's API keys (pf_...): pilotfish app \u2192 Org settings \u2192 API keys
101
101
  PILOTFISH_URL the pilotfish API (default ${DEFAULT_URL})`;
102
102
  async function main() {
103
103
  const { values } = parseArgs({
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@gaiventures/pilotfish-mcp-managed",
3
- "version": "0.1.21",
3
+ "version": "0.1.22",
4
4
  "description": "Whole browser tasks done in pilotfish's cloud for any MCP agent, signed in with your saved logins. mcprush.com-37c48d491684ec6011385ea5",
5
5
  "license": "MIT",
6
6
  "type": "module",