@gaiventures/pilotfish-mcp-managed 0.1.11 → 0.1.13
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 +116 -91
- package/cli.js +1 -1
- package/package.json +6 -3
package/README.md
CHANGED
|
@@ -1,80 +1,90 @@
|
|
|
1
1
|
# pilotfish MCP (managed)
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
**
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
[
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
(`https://pilotfish.gai.ventures/connect`):
|
|
43
|
-
|
|
44
|
-
- **No key (OAuth):** Claude.ai, Claude Desktop and Claude Code sign in by themselves. Give them the endpoint
|
|
45
|
-
URL; they open pilotfish's sign-in and a consent page.
|
|
46
|
-
- **An MCP key (`pf_…`):** *Create key*. Each key can be shown again, copied, rotated or revoked there. Make one
|
|
47
|
-
per agent. A key acts as you, and stops working if you leave your org.
|
|
3
|
+
[](https://www.npmjs.com/package/@gaiventures/pilotfish-mcp-managed)
|
|
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.
|
|
9
|
+
|
|
10
|
+
Works with Claude Code, Claude.ai, Claude Desktop, Codex CLI, Cursor, VS Code and any other
|
|
11
|
+
[MCP](https://modelcontextprotocol.io) client.
|
|
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).
|
|
16
|
+
|
|
17
|
+
## Why managed
|
|
18
|
+
|
|
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.
|
|
23
|
+
- **Gets through where plain browsers stop.** Residential IPs in your country, stealth browsing and CAPTCHA solving
|
|
24
|
+
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.
|
|
34
|
+
|
|
35
|
+
## Get started
|
|
36
|
+
|
|
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.
|
|
48
42
|
|
|
49
43
|
## Connect
|
|
50
44
|
|
|
51
|
-
|
|
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.
|
|
47
|
+
|
|
48
|
+
### Claude Code
|
|
52
49
|
|
|
53
50
|
```sh
|
|
54
|
-
claude mcp add --transport http pilotfish https://pilotfish-be.gai.ventures/mcp
|
|
51
|
+
claude mcp add --transport http pilotfish https://pilotfish-be.gai.ventures/mcp
|
|
55
52
|
```
|
|
56
53
|
|
|
57
|
-
|
|
58
|
-
|
|
54
|
+
Claude Code opens pilotfish's sign-in the first time. To use a key instead, add
|
|
55
|
+
`--header "Authorization: Bearer pf_YOUR_KEY"`.
|
|
56
|
+
|
|
57
|
+
### Claude.ai and Claude Desktop
|
|
59
58
|
|
|
60
|
-
|
|
59
|
+
Settings → Connectors → Add custom connector → `https://pilotfish-be.gai.ventures/mcp`, then sign in.
|
|
60
|
+
|
|
61
|
+
### Cursor, Windsurf, VS Code and other clients that take a URL
|
|
61
62
|
|
|
62
63
|
```json
|
|
63
|
-
{
|
|
64
|
+
{
|
|
65
|
+
"mcpServers": {
|
|
66
|
+
"pilotfish": {
|
|
67
|
+
"url": "https://pilotfish-be.gai.ventures/mcp",
|
|
68
|
+
"headers": { "Authorization": "Bearer pf_YOUR_KEY" }
|
|
69
|
+
}
|
|
70
|
+
}
|
|
71
|
+
}
|
|
64
72
|
```
|
|
65
73
|
|
|
66
|
-
|
|
74
|
+
### Codex CLI
|
|
75
|
+
|
|
76
|
+
In `~/.codex/config.toml`, through this package:
|
|
67
77
|
|
|
68
78
|
```toml
|
|
69
79
|
[mcp_servers.pilotfish]
|
|
70
80
|
command = "npx"
|
|
71
81
|
args = ["-y", "@gaiventures/pilotfish-mcp-managed"]
|
|
72
82
|
env = { PILOTFISH_KEY = "pf_YOUR_KEY" }
|
|
73
|
-
# browser_task waits up to 600 s for a result
|
|
83
|
+
# browser_task waits up to 600 s for a result; Codex stops a call after 60 s by default.
|
|
74
84
|
tool_timeout_sec = 660
|
|
75
85
|
```
|
|
76
86
|
|
|
77
|
-
|
|
87
|
+
### Any client that starts a local server
|
|
78
88
|
|
|
79
89
|
```json
|
|
80
90
|
{
|
|
@@ -88,55 +98,70 @@ tool_timeout_sec = 660
|
|
|
88
98
|
}
|
|
89
99
|
```
|
|
90
100
|
|
|
91
|
-
Check a key
|
|
101
|
+
### Check a key
|
|
102
|
+
|
|
103
|
+
Prints the endpoint and the tools, or why the key was refused:
|
|
92
104
|
|
|
93
105
|
```sh
|
|
94
|
-
PILOTFISH_KEY=pf_YOUR_KEY npx -y @gaiventures/pilotfish-mcp-managed --check
|
|
106
|
+
PILOTFISH_KEY=pf_YOUR_KEY npx -y @gaiventures/pilotfish-mcp-managed --check
|
|
95
107
|
```
|
|
96
108
|
|
|
97
|
-
|
|
98
|
-
$env:PILOTFISH_KEY = "pf_YOUR_KEY"; npx -y @gaiventures/pilotfish-mcp-managed --check # Windows PowerShell
|
|
99
|
-
```
|
|
109
|
+
In Windows PowerShell: `$env:PILOTFISH_KEY = "pf_YOUR_KEY"; npx -y @gaiventures/pilotfish-mcp-managed --check`.
|
|
100
110
|
|
|
101
|
-
##
|
|
111
|
+
## MCP keys
|
|
102
112
|
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
| --- | --- | --- |
|
|
107
|
-
| `PILOTFISH_KEY` | | Your MCP key (`pf_…`). Required for this package. |
|
|
108
|
-
| `PILOTFISH_URL` | `https://pilotfish-be.gai.ventures` | The pilotfish API (or its `/mcp` URL). |
|
|
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.
|
|
109
116
|
|
|
110
117
|
## Tools
|
|
111
118
|
|
|
112
119
|
| Tool | What it does |
|
|
113
120
|
| --- | --- |
|
|
114
|
-
| `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 600; the
|
|
115
|
-
| `get_job` `{id, wait_seconds?}` |
|
|
116
|
-
| `get_file` `{id, file_id}` | One of the session's files
|
|
117
|
-
| `list_jobs` `{status?, limit?}` | Your recent jobs with cost; `[replay]` marks recorded ones. |
|
|
118
|
-
| `follow_up` `{id, text, model?, files?, wait?}` | Carry on in the same session: same browser while it is kept, same sign-ins, what earlier turns found.
|
|
119
|
-
| `rerun_job` `{id, wait?}` |
|
|
120
|
-
| `answer_job` `{id, question_id, answer}` | yes
|
|
121
|
-
| `message_job` `{id, text}` | Steer a running job ("
|
|
122
|
-
| `take_control` `{id}` / `hand_back` `{id}` | Pause a
|
|
123
|
-
| `cancel_job` `{id}` | Stop a job. Cancelling a
|
|
124
|
-
| `get_replay` `{id}` | The job's
|
|
125
|
-
| `list_saved_tasks` | Your saved tasks
|
|
126
|
-
| `run_saved_task` `{id, extra_instructions?, start_url?, region?, sites?, stealth?, solve?, wait?}` | Run
|
|
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 600; the task carries on after that), 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. |
|
|
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?, files?, wait?}` | Carry on in the same session: same browser while it is kept, same sign-ins, what earlier turns found. |
|
|
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. Codes and passwords go on the answer page, never here. |
|
|
128
|
+
| `message_job` `{id, text}` | Steer a running job ("take the cheaper one"). It reads the message before its next step. |
|
|
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. |
|
|
130
|
+
| `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. |
|
|
127
134
|
| `save_task` `{name, task? \| from_job?, …settings}` | Save a task, or a job's task with the settings it ran with. |
|
|
128
|
-
| `update_saved_task` `{id, name?, task?, …settings}` | Rename a saved task
|
|
129
|
-
| `delete_saved_task` `{id}` | Delete a saved task
|
|
130
|
-
| `delete_session` `{id}` | Delete a session from history: its turns,
|
|
131
|
-
| `list_logins` | Sites
|
|
132
|
-
| `get_settings` / `update_site_settings` `{site, residential?, stealth?, solve?}` |
|
|
133
|
-
| `get_usage` `{days?}` | Your credit balance
|
|
134
|
-
|
|
135
|
-
When a job needs you
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
135
|
+
| `update_saved_task` `{id, name?, task?, …settings}` | Rename a saved task or change its task or settings. |
|
|
136
|
+
| `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: its turns, replay and files. 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. |
|
|
141
|
+
|
|
142
|
+
## When a job needs you
|
|
143
|
+
|
|
144
|
+
A one-time code, a CAPTCHA it could not clear, a sign-in or a payment to approve: clients that support it open
|
|
145
|
+
pilotfish's answer page for you, and other clients get the link in the tool result. The answer page shows the
|
|
146
|
+
browser live and lets you take over, so you can type a code or sign in right there.
|
|
147
|
+
|
|
148
|
+
## Pricing
|
|
149
|
+
|
|
150
|
+
Pay as you go from prepaid credit: the browser by the minute, residential traffic by the GB, models at their token
|
|
151
|
+
price plus 20%, and CAPTCHAs per solve. Each task shows its cost as it runs. Full prices are on
|
|
152
|
+
[pilotfish.gai.ventures/pricing](https://pilotfish.gai.ventures/pricing). For volume pricing or your own proxies,
|
|
153
|
+
[talk to us](https://pilotfish.gai.ventures/contact).
|
|
154
|
+
|
|
155
|
+
## Settings
|
|
156
|
+
|
|
157
|
+
Only for this package. Clients that connect to the URL need none.
|
|
158
|
+
|
|
159
|
+
| Variable | Default | Meaning |
|
|
160
|
+
| --- | --- | --- |
|
|
161
|
+
| `PILOTFISH_KEY` | | Your MCP key (`pf_…`). Required. |
|
|
162
|
+
| `PILOTFISH_URL` | `https://pilotfish-be.gai.ventures` | The pilotfish API, or its `/mcp` URL. |
|
|
139
163
|
|
|
140
164
|
## License
|
|
141
165
|
|
|
142
|
-
MIT
|
|
166
|
+
This relay is MIT licensed. The pilotfish service is covered by its
|
|
167
|
+
[terms](https://pilotfish.gai.ventures/terms).
|
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.13" : "0.0.0-dev";
|
|
14
14
|
|
|
15
15
|
// packages/mcp-managed/dist/bridge.js
|
|
16
16
|
var DEFAULT_URL = "https://pilotfish-be.gai.ventures";
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@gaiventures/pilotfish-mcp-managed",
|
|
3
|
-
"version": "0.1.
|
|
4
|
-
"description": "
|
|
3
|
+
"version": "0.1.13",
|
|
4
|
+
"description": "Whole browser tasks done in pilotfish's cloud for any MCP agent, signed in with your saved logins.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"type": "module",
|
|
7
7
|
"bin": {
|
|
@@ -29,9 +29,12 @@
|
|
|
29
29
|
"mcp",
|
|
30
30
|
"mcp-server",
|
|
31
31
|
"model-context-protocol",
|
|
32
|
+
"pilotfish",
|
|
32
33
|
"browser-automation",
|
|
34
|
+
"browser-agent",
|
|
35
|
+
"ai-agent",
|
|
33
36
|
"cloud-browser",
|
|
34
|
-
"
|
|
37
|
+
"web-automation",
|
|
35
38
|
"claude-code",
|
|
36
39
|
"codex",
|
|
37
40
|
"cursor"
|