@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.
- package/README.md +271 -88
- package/cli.js +5 -5
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -2,50 +2,51 @@
|
|
|
2
2
|
|
|
3
3
|
[](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
|
-
|
|
7
|
-
|
|
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
|
-
|
|
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
|
|
14
|
-
>
|
|
15
|
-
>
|
|
16
|
-
|
|
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
|
-
|
|
22
|
-
- **Signed in as you.** Save a login once in the app and every task can use it
|
|
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.
|
|
27
|
-
|
|
28
|
-
- **You can see everything.** Watch any task live or take control, replay it afterwards, and see what each one
|
|
29
|
-
|
|
30
|
-
|
|
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
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
-
#
|
|
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:
|
|
135
|
+
In Windows PowerShell:
|
|
112
136
|
|
|
113
|
-
|
|
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
|
-
|
|
116
|
-
|
|
117
|
-
|
|
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
|
|
128
|
-
| `get_job` `{id, wait_seconds?}` | A job's status, open question
|
|
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. `
|
|
132
|
-
| `rerun_job` `{id, wait?}` | Run the same task with the same settings
|
|
133
|
-
| `answer_job` `{id, question_id, answer}` | Answer a job's question: yes
|
|
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
|
|
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
|
|
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,
|
|
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?,
|
|
141
|
-
| `update_saved_task` `{id, name?, task?, …settings}` | Rename a saved task
|
|
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
|
|
145
|
-
| `
|
|
146
|
-
| `
|
|
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
|
-
|
|
153
|
-
|
|
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`.
|
|
340
|
+
with `get_job`.
|
|
161
341
|
|
|
162
|
-
##
|
|
342
|
+
## When a job needs a person
|
|
163
343
|
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
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:
|
|
182
|
-
price plus 20%, and CAPTCHAs per solve. Each task shows its
|
|
183
|
-
[pilotfish.gai.ventures/pricing](https://pilotfish.gai.ventures/pricing). For volume
|
|
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` | |
|
|
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.
|
|
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:
|
|
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
|
|
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
|
|
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
|
|
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.
|
|
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",
|