@gaiventures/pilotfish-mcp-managed 0.1.21 → 0.1.23

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 +271 -88
  2. package/cli.js +5 -5
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -2,50 +2,51 @@
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, several accounts a site if you have
25
+ them. Sessions are kept between runs, and two-factor codes, emailed codes and phone sign-in by code are handled.
26
+ - **Or as each of your own users.** Building a product? Run tasks for your end users in a shared project, each as an
27
+ identity with their own logins, sessions, residential IP and device, and see what each one's tasks cost.
24
28
  - **Gets through where plain browsers stop.** Residential IPs in your country, stealth browsing and CAPTCHA solving
25
29
  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.
30
+ - **Always on.** Tasks run in the cloud, so they carry on while your laptop sleeps. A follow-up picks up the same
31
+ session where it left off.
32
+ - **You can see everything.** Watch any task live or take control, replay it afterwards, and see what each one cost.
33
+ - **Safe with money and messages.** Payments, orders and messages wait for a person's yes unless the task's own words
34
+ allow them, and codes and passwords never pass through the agent.
35
35
 
36
36
  ## Get started
37
37
 
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.
38
+ 1. **Have an account.** [Sign up with Google](https://pilotfish.gai.ventures/signup) and name your organization (you
39
+ become its primary admin), or accept an emailed invitation to join an existing one as a member or an admin.
40
+ 2. **Make sure the organization has credits.** Admins add them under **Usage → Credits** in the app (pay as you go,
41
+ from $10, with optional auto reload). Members run tasks on the organization's credits within any allowance an
42
+ admin sets for them.
43
+ 3. **Connect your agent** (below). The simplest way is to sign in from your client, which then acts as you. Scripts,
44
+ servers and shared agents use one of the organization's API keys instead. The app's **API & MCP** page
45
+ (`https://pilotfish.gai.ventures/connect`) has the endpoint and every client's setup.
44
46
 
45
47
  ## Connect
46
48
 
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.
49
+ The endpoint is `https://pilotfish-be.gai.ventures/mcp` (Streamable HTTP).
49
50
 
50
51
  ### Claude Code
51
52
 
@@ -53,14 +54,15 @@ no package. This package is a small relay for clients that can only start a loca
53
54
  claude mcp add --transport http pilotfish https://pilotfish-be.gai.ventures/mcp
54
55
  ```
55
56
 
56
- Claude Code opens pilotfish's sign-in the first time. To use a key instead, add
57
- `--header "Authorization: Bearer pf_YOUR_KEY"`.
57
+ Then run `/mcp` in Claude Code, choose pilotfish and sign in with your pilotfish account. To use an API key instead,
58
+ add `--header "Authorization: Bearer pf_YOUR_KEY"` to the command.
58
59
 
59
60
  ### Claude.ai and Claude Desktop
60
61
 
61
- Settings → Connectors → Add custom connector → `https://pilotfish-be.gai.ventures/mcp`, then sign in.
62
+ **Settings → Connectors → Add custom connector**, paste `https://pilotfish-be.gai.ventures/mcp`, connect, and sign in.
63
+ No key is needed.
62
64
 
63
- ### Cursor, Windsurf, VS Code and other clients that take a URL
65
+ ### Cursor, Windsurf and other clients that take a URL
64
66
 
65
67
  ```json
66
68
  {
@@ -73,6 +75,24 @@ Settings → Connectors → Add custom connector → `https://pilotfish-be.gai.v
73
75
  }
74
76
  ```
75
77
 
78
+ A client that supports MCP sign-in (OAuth) can leave out `headers` and sign in instead.
79
+
80
+ ### VS Code
81
+
82
+ In `.vscode/mcp.json`:
83
+
84
+ ```json
85
+ {
86
+ "servers": {
87
+ "pilotfish": {
88
+ "type": "http",
89
+ "url": "https://pilotfish-be.gai.ventures/mcp",
90
+ "headers": { "Authorization": "Bearer pf_YOUR_KEY" }
91
+ }
92
+ }
93
+ }
94
+ ```
95
+
76
96
  ### Codex CLI
77
97
 
78
98
  In `~/.codex/config.toml`, through this package:
@@ -82,7 +102,7 @@ In `~/.codex/config.toml`, through this package:
82
102
  command = "npx"
83
103
  args = ["-y", "@gaiventures/pilotfish-mcp-managed"]
84
104
  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.
105
+ # A call returns within 120 s (the task carries on); Codex stops a call after 60 s by default.
86
106
  tool_timeout_sec = 180
87
107
  ```
88
108
 
@@ -100,6 +120,10 @@ tool_timeout_sec = 180
100
120
  }
101
121
  ```
102
122
 
123
+ The relay needs Node.js 22 or newer. It only forwards messages to the endpoint with your key; the browser runs in
124
+ pilotfish's cloud. On native Windows, if your client cannot start `npx`, use `"command": "cmd"` with
125
+ `"args": ["/c", "npx", "-y", "@gaiventures/pilotfish-mcp-managed"]`.
126
+
103
127
  ### Check a key
104
128
 
105
129
  Prints the endpoint and the tools, or why the key was refused:
@@ -108,90 +132,249 @@ Prints the endpoint and the tools, or why the key was refused:
108
132
  PILOTFISH_KEY=pf_YOUR_KEY npx -y @gaiventures/pilotfish-mcp-managed --check
109
133
  ```
110
134
 
111
- In Windows PowerShell: `$env:PILOTFISH_KEY = "pf_YOUR_KEY"; npx -y @gaiventures/pilotfish-mcp-managed --check`.
135
+ In Windows PowerShell:
112
136
 
113
- ## API keys
137
+ ```powershell
138
+ $env:PILOTFISH_KEY = "pf_YOUR_KEY"; npx -y @gaiventures/pilotfish-mcp-managed --check
139
+ ```
140
+
141
+ `--version` prints the relay's version.
142
+
143
+ ## Signing in or an API key
144
+
145
+ | | **Signing in** (OAuth) | **An organization API key** (`pf_…`) |
146
+ | --- | --- | --- |
147
+ | Who it acts as | You | The organization, as no particular person |
148
+ | Who can use it | Only you | Anyone who has the key: keep it secret |
149
+ | Project | Personal, until you `switch_project` | The one shared project it belongs to |
150
+ | Saved logins, site profiles, saved tasks | Yours (in Personal) | No one's: each end user's logins belong to an identity |
151
+ | 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 |
152
+ | 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 |
153
+ | Who sets it up | You, from your client | The organization's admins, under **Org settings → API keys** |
154
+
155
+ **About keys.** Admins create, show again, copy, rotate and revoke keys under **Org settings → API keys**
156
+ (`https://pilotfish.gai.ventures/org?view=keys`). Each key belongs to one shared project, picked when it is made
157
+ (Default unless chosen) and movable later. Rotating gives a new value under the same name, and the old one stops
158
+ working at once; rotate a key when someone who had it leaves. Each key has its own page with what it spent, its tasks
159
+ through the MCP and the API, and its sessions. An admin can give a key an allowance: a spending limit on the
160
+ organization's credits, with an optional automatic top-up.
161
+
162
+ **Personal API keys.** Admins (the primary admin included) can also make a key of their own on the app's **API & MCP**
163
+ page: it acts as them, in their Personal project, for their own scripts. A member who asks for one is told to contact
164
+ their admins, and connects their AI tool by signing in instead (no key needed). Admins see each person's key usage.
165
+
166
+ ## Projects
167
+
168
+ Every task runs in a project.
169
+
170
+ - **Personal** is your own: your saved logins (several accounts a site, one of them the default), saved and scheduled
171
+ tasks, connected inbox and site settings. It is where you are when you sign in, in the app or from an AI tool.
172
+ - **Shared projects** (Default, and any an admin creates) are for product companies running tasks for their own end
173
+ users. They hold no one's personal logins and no saved or scheduled tasks: each end user is an **identity** there. A
174
+ task with no identity gets a fresh browser of its own, and nothing of it is kept for other sessions.
175
+
176
+ Switch in the app's project switcher, or with `switch_project` (no argument lists your projects); the MCP remembers
177
+ your choice for your next connections. An organization API key always works in its own project.
178
+
179
+ ## Identities: tasks for your own users
180
+
181
+ An identity (`idn_…`) is one of your end users. pilotfish keeps, on its servers, everything that makes them look like
182
+ the same person to a site: their logins for any number of sites (several accounts a site), their signed-in sessions,
183
+ a residential IP in their country (the same region every time, kept sticky) and their device fingerprint. None of it
184
+ is ever handed back. You only see its id, label, your own user id for it (`external_user_id`), its country and device
185
+ OS, which sites it has logins for (usernames masked), its credential ids, and what its tasks cost.
186
+
187
+ - **Manage them** with the `identities` tool (`list`, `create`, `get`, `update`, `delete`) or the REST API
188
+ (`/identities`). Creating one with an `external_user_id` you already used gives the existing one back.
189
+ - **Run a task as one** with `browser_task {identity: "idn_…"}`. A `follow_up` keeps the session's identity. Each
190
+ identity runs one task at a time.
191
+ - **Delete** wipes its logins, sessions and device for good. Its tasks and their costs stay, for your billing.
192
+
193
+ ### Getting a user's logins in, without an AI seeing them
194
+
195
+ Each saved login gets a credential id (`cred_…`). A password never passes through the MCP. There are three ways in:
196
+
197
+ 1. **A login link.** `identities {action: "login_link", id, sites: ["linkedin.com"]}` (or `POST /identities/:id/link`)
198
+ returns a one-time page, valid for 30 minutes (over REST, `ttlMinutes` sets 5 to 1440). Send it to your end user; they type their own login
199
+ there, and it is saved sealed to their identity.
200
+ 2. **Your own server.** `POST /identities/:id/credentials {site, username, password?, totp?, account?, default?}`
201
+ with your API key, from your backend. The MCP refuses this route.
202
+ 3. **Sign-ins during a task.** With `save_logins: true` on the identity, a sign-in typed during one of its tasks is
203
+ kept once it works. Off by default; the signed-in session is kept either way.
204
+
205
+ Use them in a task with `credentials: ["cred_…"]`, or name the account per site with
206
+ `accounts: {"linkedin.com": "work"}`.
207
+
208
+ ### Which account a task uses
209
+
210
+ When a site has several saved accounts (yours in Personal, or an identity's), a task takes, in order: the one the
211
+ request names (`accounts`, `credentials` or `login`), the one the session already chose, the one the person's own
212
+ words name (its name, or its username or email), the site's default, or the only one saved. Otherwise it asks once, at
213
+ the start: each saved account, **Use another login**, **Create a new account** or **Go without signing in**. A
214
+ scheduled run never asks: it takes the default, else the main account. Set a default with `manage_login {action: "set_default"}` (Personal)
215
+ or `identities {action: "set_default", credential}`.
216
+
217
+ ### What each task cost
218
+
219
+ Every `browser_task` and `follow_up` result ends with the task's cost by kind and where it ran:
220
+
221
+ ```text
222
+ Cost: $0.0213 (model $0.0081, residential IP $0.0104, browser $0.0020, CAPTCHA $0.0008)
223
+ Project: prj_acme; identity: idn_7Hq2…
224
+ ```
225
+
226
+ `identities {action: "get"}` and `GET /identities/:id/usage?since=` give an identity's totals (tasks; model,
227
+ residential IP, browser and CAPTCHA cost) and each task's cost, so you can bill your own users.
228
+
229
+ ### An example: Acme HR
230
+
231
+ Acme HR runs LinkedIn tasks for its users Priya (in India) and Rahul (in the US). An admin creates the shared project
232
+ "Acme HR" and an API key in it, and Acme's server connects with that key.
233
+
234
+ 1. One identity per user:
235
+ `identities {action: "create", external_user_id: "u_1042", label: "Priya", country: "in"}` and
236
+ `identities {action: "create", external_user_id: "u_2077", label: "Rahul", country: "us"}`.
237
+ 2. A login link for each: `identities {action: "login_link", id: "idn_priya…", sites: ["linkedin.com"]}`. Acme shows
238
+ the link in its own app; Priya signs in to LinkedIn there. Rahul does the same with his.
239
+ 3. Tasks by identity: `browser_task {identity: "idn_priya…", task: "Read my new LinkedIn messages and list who wrote"}`.
240
+ It runs on Priya's LinkedIn session, from an Indian residential IP on her own device; Rahul's runs from the US on his.
241
+ 4. The cost: each result ends with `Cost: …` and `identity: idn_priya…`; at month end Acme reads
242
+ `GET /identities/idn_priya…/usage?since=…` for each user and bills them.
243
+ 5. Priya leaves: `identities {action: "delete", id: "idn_priya…"}` wipes her LinkedIn login, session and device. Her
244
+ past tasks and their costs stay in Acme's usage.
245
+
246
+ ## Organizations, members and money
247
+
248
+ Everyone is in one organization, and its credits pay for every task its people and its keys run.
249
+
250
+ | | **Primary admin** | **Admins** | **Members** |
251
+ | --- | --- | --- | --- |
252
+ | Run tasks, connect agents, save logins | Yes | Yes | Yes |
253
+ | Add credits, card, auto reload | Yes | Yes | No |
254
+ | Monthly limit and overage | Yes | Yes | No |
255
+ | Invite people, change roles, set allowances | Yes | Yes | No |
256
+ | Create and manage API keys, and shared projects | Yes | Yes | No |
257
+ | A personal API key | Yes | Yes | No: they sign in from their client, or ask an admin |
258
+ | See everyone's tasks and spending | Yes | Yes | No: their own, and their allowance |
259
+ | Hand the primary admin role to someone else | Yes | No | No |
260
+
261
+ - **Allowances.** An admin may give a member (or a key) a spending limit on the organization's credits. No limit is
262
+ the default. When it is used up, new tasks are refused and running ones pause until an admin raises it.
263
+ - **The monthly limit.** An admin may set one for the whole organization. The primary admin is emailed at 80% and at
264
+ 100%; at the limit, tasks pause and new ones are refused until an admin turns on overage or raises the limit.
265
+ - **One task at a time** per person, per key and per identity. Another task started meanwhile is refused until the
266
+ first finishes or is stopped.
267
+ - **Check-ins on long tasks.** A task that has spent a set amount ($1 by default) pauses and says what it found so
268
+ far; carry on with a follow-up, and it checks in again at the next step of that amount.
269
+ - **What your agent sees.** A refused task comes back with the reason and whom to ask:
270
+
271
+ | Reason | What it says | What to do |
272
+ | --- | --- | --- |
273
+ | `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 |
274
+ | `allocation_used` | You've used your (or this key's) allowance, naming the admins to ask | An admin raises the allowance |
275
+ | `org_limit` | The organization has reached its monthly limit | An admin turns on overage or raises the limit |
276
+ | `one_session` | You already have a task running | Wait for it to finish, or stop it with `cancel_job` |
114
277
 
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.
278
+ `get_usage` shows where you stand: for an admin, the organization's balance and auto reload; for a member, their
279
+ allowance and whether the organization's credits are fine, low or out; for everyone, this month's spending against
280
+ the monthly limit and spending by category and by model.
122
281
 
123
282
  ## Tools
124
283
 
125
284
  | Tool | What it does |
126
285
  | --- | --- |
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. |
286
+ | `browser_task` `{task, start_url?, region?, sites?, login?, accounts?, identity?, credentials?, 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 with its cost by kind and its project and identity, 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; `accounts` (`{"linkedin.com": "work"}`, `""` the main one): which account on each site. `identity` (`idn_…`, in a shared project): run as that end user; `credentials` (`["cred_…"]`): which of its saved logins. `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). |
287
+ | `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. |
288
+ | `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. |
289
+ | `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`. |
290
+ | `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. The session keeps its project and identity. |
291
+ | `rerun_job` `{id, wait?, wait_seconds?}` | Run the same task again with the same settings, as a new job. |
292
+ | `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. |
293
+ | `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. |
294
+ | `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
295
  | `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. |
296
+ | `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. |
297
+ | `list_saved_tasks` | Your saved tasks: id, name, settings, how often and when they last ran, and what their last run needed. |
298
+ | `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. |
299
+ | `save_task` `{name, task? \| from_job?, start_url?, region?, sites?, login?, accounts?, 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. |
300
+ | `update_saved_task` `{id, name?, task?, …settings}` | Rename a saved task, change its task, or change only the settings given. |
142
301
  | `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. |
302
+ | `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. |
303
+ | `list_logins` | Sites with saved logins in your Personal project: which accounts, whether a password and authenticator key are stored, what recent runs met there. Never a password or code. |
304
+ | `manage_login` `{action, site, account?}` | Your Personal logins. `add`: a link to the app where you type the login yourself (never in the chat). `set_default`: the account tasks use on a site with several when they don't say. `delete`: forget one. `save_offered` / `discard_offered`: a sign-in a run offered for saving. |
305
+ | `switch_project` `{project?}` | Which project your tasks run in: `personal`, `default` or a project's id or name. No argument lists them. Remembered for your next connections; an organization API key stays in its own. |
306
+ | `identities` `{action, id?, external_user_id?, label?, query?, country?, device_os?, email?, save_logins?, sites?, account?, credential?}` | Your end users in a shared project. `list` (by `external_user_id` or `query`), `create`, `get` (logins by credential id, masked; signed-in sites; cost so far), `update`, `delete` (wipes logins, sessions and device; costs stay), `login_link` (`sites`: a one-time page for the user to type their own login), `set_default` and `delete_login` (by `credential`). |
307
+ | `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. |
308
+ | `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. |
309
+
310
+ ## What a job returns
311
+
312
+ A finished job starts with `SUCCESS`, `PARTLY DONE` or `NOT DONE`. One that did not fully pass lists what of the task
313
+ is done, what is not (each with its evidence) and why it stopped. Every finished job ends with a `Cost:` line (model,
314
+ residential IP, browser, CAPTCHA) and a `Project:` line naming its project and identity. A job still running says `Still running after
315
+ 120 s; the job carries on`, and your agent waits again with `get_job`. A job that needs a person shows the question,
316
+ a `Question <id>` line saying how to answer it, and the answer link.
317
+
318
+ ## Whole tasks or steps?
319
+
320
+ Send the whole web task in one `browser_task`, however many sites and steps it has: "find the cheapest return flight
321
+ on MakeMyTrip, then book a hotel near the beach for those dates on Booking.com", "read my last Swiggy order and add it
322
+ to my Splitwise group". pilotfish splits it into parts, asks for every sign-in it needs at the start, carries what
323
+ each site gives to the next and checks the end result. Split it yourself only where a step is not browser work (your
324
+ own code, files, an API) or needs your own decision between steps; then send each browser step with the values it
325
+ needs written in, or use `follow_up` to stay in the same browser and sign-ins. Say in the task what may be completed
326
+ without asking ("pay with my saved card", "go ahead and submit"); anything else that is final waits for a yes.
147
327
 
148
328
  ## Tasks that name no site
149
329
 
150
330
  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.
331
+ pilotfish searches the web first and answers from what it read, every fact linked to its page, in seconds and with no
332
+ browser. When the answer needs a site (a fare for a date, a table to book, your own account), the browser starts on
333
+ the site the search found; a price or availability for particular dates is always read on the site itself.
154
334
 
155
335
  ## When the person says more mid-task
156
336
 
157
337
  Your agent reads what the person types only between tool calls, so `browser_task`, `follow_up` and `get_job` return
158
338
  within two minutes by default while the task carries on. Anything the person says meanwhile (a correction, a detail,
159
339
  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.
340
+ with `get_job`.
161
341
 
162
- ## Whole tasks or steps?
342
+ ## When a job needs a person
163
343
 
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.
172
-
173
- ## When a job needs you
174
-
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.
344
+ A one-time code with no saved source, a CAPTCHA it could not clear, a sign-in or a payment to approve: clients that
345
+ support it open pilotfish's answer page, and other clients get the link in the tool result. The answer page shows the
346
+ browser live and lets the person take over, so they can type a code or sign in right there. Codes and passwords never
347
+ pass through the agent.
178
348
 
179
349
  ## Pricing
180
350
 
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).
351
+ Pay as you go from the organization's prepaid credit: browser time at $0.02 per browser-hour (billed in whole minutes),
352
+ residential traffic at $4 per GB, models at their token price plus 20%, and CAPTCHAs per solve. Each task shows its
353
+ cost as it runs. Full prices: [pilotfish.gai.ventures/pricing](https://pilotfish.gai.ventures/pricing). For volume
354
+ pricing or your own proxies, [talk to us](https://pilotfish.gai.ventures/contact).
185
355
 
186
356
  ## Settings
187
357
 
188
- Only for this package. Clients that connect to the URL need none.
358
+ Only for this package (the relay). Clients that connect to the URL need none.
189
359
 
190
360
  | Variable | Default | Meaning |
191
361
  | --- | --- | --- |
192
- | `PILOTFISH_KEY` | | One of your organization's API keys (`pf_…`). Required. |
362
+ | `PILOTFISH_KEY` | | An API key (`pf_…`): one of your organization's, or an admin's personal key. Required. |
193
363
  | `PILOTFISH_URL` | `https://pilotfish-be.gai.ventures` | The pilotfish API, or its `/mcp` URL. |
194
364
 
365
+ ## Troubleshooting
366
+
367
+ - **401 Unauthorized:** the key was revoked or rotated, or your organization was deleted. Ask an admin for a current
368
+ key (**Org settings → API keys**), or sign in from your client instead.
369
+ - **Codex stops the call after a minute:** keep `tool_timeout_sec = 180` as above; the task itself carries on.
370
+ - **`npx` fails, or the relay won't start:** check `node --version` is 22 or newer; on Windows, start it through
371
+ `cmd /c` as above.
372
+ - **`shared_project` or `personal_project`:** saved logins and saved tasks are in Personal, identities in a shared
373
+ project: `switch_project` to the right one (an organization API key stays in its own).
374
+ - **`identity_busy`:** that identity already has a task running; wait for it or stop it.
375
+ - **A task is refused:** the reason and whom to ask are in the result; the table under "Organizations, members and
376
+ money" above lists each one.
377
+
195
378
  ## License
196
379
 
197
380
  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.23" : "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.23",
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",