@gaiventures/pilotfish-mcp-managed 0.1.20 → 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 +174 -82
  2. package/cli.js +5 -5
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -2,48 +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), add credits
14
- > (from $10), and create an MCP key under **Connect an agent**. Claude.ai, Claude Desktop and Claude Code can sign
15
- > in with OAuth instead of a key. See [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.
16
19
 
17
20
  ## Why managed
18
21
 
19
- - **One call per task.** pilotfish plans and runs the task on its own models and checks the answer.
20
- Your agent spends a tool call or two, not a context full of web pages.
21
- - **Signed in as you.** Save a login once in the app and every task can use it. Sessions are kept between runs,
22
- 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.
23
26
  - **Gets through where plain browsers stop.** Residential IPs in your country, stealth browsing and CAPTCHA solving
24
27
  are on by default, with per-site settings. When something truly needs you, you get a link.
25
- - **Always on.** Tasks run in the cloud, so they carry on while your laptop sleeps. Follow up on a session later
26
- and it picks up where it left off.
27
- - **You can see everything.** Watch any task live or take control, replay it afterwards, and see what each one
28
- cost.
29
- - **Safe with money and messages.** Payments, orders and messages wait for your approval unless you allow them up
30
- front, and your codes and passwords never pass through the agent.
31
-
32
- Prefer to drive a browser on your own computer, for free? Use the local
33
- [`@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.
34
33
 
35
34
  ## Get started
36
35
 
37
- 1. **Sign up** at [pilotfish.gai.ventures/signup](https://pilotfish.gai.ventures/signup) with your Google account.
38
- 2. **Add credits.** Pay as you go, from $10, under **Usage → Credits**.
39
- 3. **Create an MCP key** under **Connect an agent** in the app (`https://pilotfish.gai.ventures/connect`). Skip
40
- this if your client signs in with OAuth (Claude.ai, Claude Desktop, Claude Code).
41
- 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.
42
43
 
43
44
  ## Connect
44
45
 
45
- The endpoint is `https://pilotfish-be.gai.ventures/mcp`. Clients that take a URL connect to it directly and need
46
- 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).
47
47
 
48
48
  ### Claude Code
49
49
 
@@ -51,14 +51,15 @@ no package. This package is a small relay for clients that can only start a loca
51
51
  claude mcp add --transport http pilotfish https://pilotfish-be.gai.ventures/mcp
52
52
  ```
53
53
 
54
- Claude Code opens pilotfish's sign-in the first time. To use a key instead, add
55
- `--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.
56
56
 
57
57
  ### Claude.ai and Claude Desktop
58
58
 
59
- 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.
60
61
 
61
- ### Cursor, Windsurf, VS Code and other clients that take a URL
62
+ ### Cursor, Windsurf and other clients that take a URL
62
63
 
63
64
  ```json
64
65
  {
@@ -71,6 +72,24 @@ Settings → Connectors → Add custom connector → `https://pilotfish-be.gai.v
71
72
  }
72
73
  ```
73
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
+
74
93
  ### Codex CLI
75
94
 
76
95
  In `~/.codex/config.toml`, through this package:
@@ -80,7 +99,7 @@ In `~/.codex/config.toml`, through this package:
80
99
  command = "npx"
81
100
  args = ["-y", "@gaiventures/pilotfish-mcp-managed"]
82
101
  env = { PILOTFISH_KEY = "pf_YOUR_KEY" }
83
- # 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.
84
103
  tool_timeout_sec = 180
85
104
  ```
86
105
 
@@ -98,6 +117,10 @@ tool_timeout_sec = 180
98
117
  }
99
118
  ```
100
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
+
101
124
  ### Check a key
102
125
 
103
126
  Prints the endpoint and the tools, or why the key was refused:
@@ -106,86 +129,155 @@ Prints the endpoint and the tools, or why the key was refused:
106
129
  PILOTFISH_KEY=pf_YOUR_KEY npx -y @gaiventures/pilotfish-mcp-managed --check
107
130
  ```
108
131
 
109
- In Windows PowerShell: `$env:PILOTFISH_KEY = "pf_YOUR_KEY"; npx -y @gaiventures/pilotfish-mcp-managed --check`.
132
+ In Windows PowerShell:
110
133
 
111
- ## MCP 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` |
112
187
 
113
- Create keys under **Connect an agent** in the app (`https://pilotfish.gai.ventures/connect`). Make one per agent;
114
- each can be shown again, copied, rotated or revoked there. A key acts as you and stops working if you leave your
115
- organization. Clients that sign in with OAuth (Claude.ai, Claude Desktop, Claude Code) need no key.
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.
116
191
 
117
192
  ## Tools
118
193
 
119
194
  | Tool | What it does |
120
195
  | --- | --- |
121
- | `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). |
122
- | `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. |
123
- | `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. |
124
- | `list_jobs` `{status?, limit?}` | Your recent jobs with their cost; `[replay]` marks recorded ones. |
125
- | `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. |
126
- | `rerun_job` `{id, wait?}` | Run the same task with the same settings again. |
127
- | `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. |
128
- | `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. |
129
- | `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. |
130
205
  | `cancel_job` `{id}` | Stop a job. Cancelling a tool call that is waiting on a job stops the job too. |
131
- | `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). |
132
- | `list_saved_tasks` | Your saved tasks, their settings and how their last run went. |
133
- | `run_saved_task` `{id, extra_instructions?, start_url?, region?, sites?, stealth?, solve?, wait?}` | Run a saved task, with optional changes for this run only. |
134
- | `save_task` `{name, task? \| from_job?, …settings}` | Save a task, or a job's task with the settings it ran with. |
135
- | `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. |
136
211
  | `delete_saved_task` `{id}` | Delete a saved task. Its past runs stay in your history. |
137
- | `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. |
138
- | `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. |
139
- | `get_settings` / `update_site_settings` `{site, residential?, stealth?, solve?}` | Your sites and their settings: residential IP (auto, always or never), stealth and CAPTCHA solving. |
140
- | `get_usage` `{days?}` | Your credit balance, this month's spending against your limits, 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.
141
233
 
142
234
  ## Tasks that name no site
143
235
 
144
236
  Send them as they are: "the best free resource to learn linear algebra", "research Postgres vs MySQL for a startup".
145
- pilotfish searches the web first and answers from what it read, every fact linked to its page, in seconds and with
146
- no browser. When the answer needs a site (a fare for a date, a table to book, your own account), the browser starts
147
- 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.
148
240
 
149
241
  ## When the person says more mid-task
150
242
 
151
243
  Your agent reads what the person types only between tool calls, so `browser_task`, `follow_up` and `get_job` return
152
244
  within two minutes by default while the task carries on. Anything the person says meanwhile (a correction, a detail,
153
245
  the answer to the task's question) goes to the task with `message_job`, in their words, and the agent keeps waiting
154
- with `get_job`. The task reads it before its next step; sent while it waits on a question, it answers that question.
155
-
156
- ## Whole tasks or steps?
157
-
158
- Send the whole web task in one `browser_task`, however many sites and steps it has: "find the cheapest return
159
- flight on MakeMyTrip, then book a hotel near the beach for those dates on Booking.com", "read my last Swiggy
160
- order and add it to my Splitwise group". pilotfish splits it into parts, asks for every sign-in it needs at the
161
- start, carries what each site gives to the next (the flight's dates into the hotel search) and checks the end
162
- result. Split it yourself only where a step is not browser work (your own code, files, an API) or needs your own
163
- decision between steps; then send each browser step as its own `browser_task` with the values it needs written
164
- in, or use `follow_up` to stay in the same browser and sign-ins. Say what may be completed without asking ("pay
165
- with my saved card", "go ahead and submit"); anything else that is final waits for your yes.
246
+ with `get_job`.
166
247
 
167
- ## When a job needs you
248
+ ## When a job needs a person
168
249
 
169
- A one-time code, a CAPTCHA it could not clear, a sign-in or a payment to approve: clients that support it open
170
- pilotfish's answer page for you, and other clients get the link in the tool result. The answer page shows the
171
- 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.
172
254
 
173
255
  ## Pricing
174
256
 
175
- Pay as you go from prepaid credit: the browser by the minute, residential traffic by the GB, models at their token
176
- price plus 20%, and CAPTCHAs per solve. Each task shows its cost as it runs. Full prices are on
177
- [pilotfish.gai.ventures/pricing](https://pilotfish.gai.ventures/pricing). For volume pricing or your own proxies,
178
- [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).
179
261
 
180
262
  ## Settings
181
263
 
182
- 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.
183
265
 
184
266
  | Variable | Default | Meaning |
185
267
  | --- | --- | --- |
186
- | `PILOTFISH_KEY` | | Your MCP key (`pf_…`). Required. |
268
+ | `PILOTFISH_KEY` | | One of your organization's API keys (`pf_…`). Required. |
187
269
  | `PILOTFISH_URL` | `https://pilotfish-be.gai.ventures` | The pilotfish API, or its `/mcp` URL. |
188
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
+
189
281
  ## License
190
282
 
191
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.20" : "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.20",
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",