@finchagentic/mcp 4.0.0 → 4.2.0
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/LICENSE +1 -1
- package/README.md +96 -249
- package/dist/agent-loop.js +139 -69
- package/dist/annotations.js +14 -13
- package/dist/cli.js +78 -21
- package/dist/config.js +16 -16
- package/dist/convex.js +15 -18
- package/dist/index.js +4 -5
- package/dist/llm.js +24 -49
- package/dist/local-memory-file.js +147 -0
- package/dist/local-memory.js +42 -9
- package/dist/output-schemas.js +71 -17
- package/dist/resources.js +8 -13
- package/dist/server.js +27 -13
- package/dist/token-gate.js +2 -2
- package/dist/tool-filter.js +13 -4
- package/dist/tools/agents.js +66 -394
- package/dist/tools/base-mcp.js +7 -19
- package/dist/tools/base.js +34 -20
- package/dist/tools/chronicle.js +4 -4
- package/dist/tools/deep-research.js +10 -5
- package/dist/tools/defi.js +36 -35
- package/dist/tools/equity.js +9 -1
- package/dist/tools/insight.js +25 -29
- package/dist/tools/memory.js +76 -108
- package/dist/tools/monitor.js +7 -7
- package/dist/tools/os.js +10 -6
- package/dist/tools/packets.js +5 -5
- package/dist/tools/research.js +2 -2
- package/dist/tools/rh-mcp.js +25 -2
- package/dist/tools/rh-orders.js +201 -123
- package/dist/tools/scanner.js +30 -0
- package/dist/tools/stake.js +329 -0
- package/dist/tools/vault.js +122 -42
- package/dist/wallet.js +212 -24
- package/package.json +9 -21
- package/dist/tools/framework.js +0 -150
package/LICENSE
CHANGED
package/README.md
CHANGED
|
@@ -1,159 +1,65 @@
|
|
|
1
1
|
<div align="center">
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
<img src="data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIxMjAwIiBoZWlnaHQ9IjMwMCIgdmlld0JveD0iMCAwIDEyMDAgMzAwIj4KICA8ZGVmcz4KICAgIDxsaW5lYXJHcmFkaWVudCBpZD0iYmciIHgxPSIwIiB5MT0iMCIgeDI9IjAiIHkyPSIxIj4KICAgICAgPHN0b3Agb2Zmc2V0PSIwIiBzdHlsZT0ic3RvcC1jb2xvcjojMGEwYTBhO3N0b3Atb3BhY2l0eToxIi8+CiAgICAgIDxzdG9wIG9mZnNldD0iMSIgc3R5bGU9InN0b3AtY29sb3I6IzFhMWEyNTtzdG9wLW9wYWNpdHk6MSIvPgogICAgPC9saW5lYXJHcmFkaWVudD4KICAgIDxyYWRpYWxHcmFkaWVudCBpZD0iZ2xvdyIgY3g9IjUwJSIgY3k9IjUwJSIgcj0iNTAlIj4KICAgICAgPHN0b3Agb2Zmc2V0PSIwIiBzdHlsZT0ic3RvcC1jb2xvcjojMjU2M0VCO3N0b3Atb3BhY2l0eTowLjMiLz4KICAgICAgPHN0b3Agb2Zmc2V0PSIxIiBzdHlsZT0ic3RvcC1jb2xvcjojMjU2M0VCO3N0b3Atb3BhY2l0eTowIi8+CiAgICA8L3JhZGlhbEdyYWRpZW50PgogIDwvZGVmcz4KICA8cmVjdCB3aWR0aD0iMTIwMCIgaGVpZ2h0PSIzMDAiIGZpbGw9InVybCgjYmcpIi8+CiAgPGNpcmNsZSBjeD0iNjAwIiBjeT0iMTUwIiByPSIyMDAiIGZpbGw9InVybCgjZ2xvdykiLz4KICA8dGV4dCB4PSI2MDAiIHk9IjEyMCIgZm9udC1mYW1pbHk9InN5c3RlbS11aSwgc2Fucy1zZXJpZiIgZm9udC1zaXplPSI1NiIgZm9udC13ZWlnaHQ9IjgwMCIgZmlsbD0iI2YwZjZmYyIgdGV4dC1hbmNob3I9Im1pZGRsZSIgbGV0dGVyLXNwYWNpbmc9Ii0wLjAzZW0iPk5vZWxDbGF3PC90ZXh0PgogIDx0ZXh0IHg9IjYwMCIgeT0iMTY1IiBmb250LWZhbWlseT0ic3lzdGVtLXVpLCBzYW5zLXNlcmlmIiBmb250LXNpemU9IjIwIiBmb250LXdlaWdodD0iNDAwIiBmaWxsPSIjOTNjNWZkIiB0ZXh0LWFuY2hvcj0ibWlkZGxlIj5UaGUgcnVudGltZSBsYXllciBmb3IgQWdlbnRpYyBBSTwvdGV4dD4KICA8dGV4dCB4PSI2MDAiIHk9IjE5NSIgZm9udC1mYW1pbHk9InN5c3RlbS11aSwgc2Fucy1zZXJpZiIgZm9udC1zaXplPSIxNCIgZm9udC13ZWlnaHQ9IjQwMCIgZmlsbD0iIzY0NzQ4YiIgdGV4dC1hbmNob3I9Im1pZGRsZSI+MTIxIHRvb2xzIOKAlCBwZXJzaXN0ZW50IG1lbW9yeSDigJQgYWdlbnRzIOKAlCB3b3JrZmxvd3Mg4oCUIERlRmkgb24gQmFzZTwvdGV4dD4KPC9zdmc+" alt="Finch" width="100%">
|
|
3
|
+
# Finch
|
|
5
4
|
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
---
|
|
5
|
+
**The runtime layer for Agentic AI.**
|
|
9
6
|
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
# The runtime layer for Agentic AI.
|
|
7
|
+
Persistent memory, autonomous agents, and workflows that survive every session.
|
|
13
8
|
|
|
14
|
-
|
|
9
|
+
[Docs](https://docs.finch.com) · [App](https://app.finchagentic.com) · [npm](https://www.npmjs.com/package/@finchagentic/mcp) · [GitHub](https://github.com/finchagentic/mcp) · [X](https://x.com/finchagentic)
|
|
15
10
|
|
|
16
11
|
</div>
|
|
17
12
|
|
|
18
13
|
---
|
|
19
14
|
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
## Table of Contents
|
|
23
|
-
|
|
24
|
-
- [What's New](#whats-new)
|
|
25
|
-
- [Three Pillars](#three-pillars)
|
|
26
|
-
- [Install](#install)
|
|
27
|
-
- [In Practice](#in-practice)
|
|
28
|
-
- [Configuration](#configuration)
|
|
29
|
-
- [Security](#security-boundaries)
|
|
30
|
-
- [Comparison](#why-this-is-different)
|
|
31
|
-
- [Troubleshooting](#troubleshooting)
|
|
32
|
-
- [Links](#links)
|
|
33
|
-
|
|
34
|
-
---
|
|
35
|
-
|
|
36
|
-
## What's New
|
|
37
|
-
|
|
38
|
-
| Feature | Description |
|
|
39
|
-
|---------|-------------|
|
|
40
|
-
| **🔒 Fully local** | Run the whole runtime on your own machine — **vault + memory on your own disk** (versioned, encrypted, no account), wallet keys local, your LLM does the thinking. Nothing phones home. `finch setup` to enable, `finch vault` to inspect. → [Run it fully local](#run-it-fully-local) |
|
|
41
|
-
| **Local Memory** | Run memory tools on a free, self-hosted [supermemory](https://github.com/supermemoryai/supermemory) server on your own machine — zero cost, private, no Finch account needed. `finch setup` to enable. |
|
|
42
|
-
| **OpenAI BYOK** | OpenAI joins Bankr/Anthropic/Grok as a direct LLM provider. `OPENAI_BASE_URL` also lets you point at any self-hosted OpenAI-compatible gateway (LiteLLM, vLLM, Ollama, OpenRouter, your own VPS). |
|
|
43
|
-
| **`finch setup`** | New guided CLI wizard — pick an LLM provider and/or enable local memory in one flow. |
|
|
44
|
-
| **Finch Terminal** | Tool calling from chat — spawn agents, save to vault, search memory, estimate + execute swaps, create automations. All from a single prompt. |
|
|
45
|
-
| **`execute_swap`** | Execute token swaps on Base mainnet from Finch Terminal. Enforces estimate → preview → confirm → execute flow. Routes via 0x Permit2. |
|
|
46
|
-
| **7 Agents** | Noel (AI OS), CoinGecko (market data), Sage (research), Forge (code), Quill (creative), Spectre (trading), Atlas (general) |
|
|
47
|
-
| **Multi-Provider Chat** | Bankr → Anthropic → OpenAI → Grok → Finch proxy fallback |
|
|
48
|
-
| **ConnectMcpModal** | Onboarding flow: auto-generate API key + copy install command from webapp |
|
|
49
|
-
| **Security Hardened** | 8 security boundaries, wallet decrypt-failure protection, 4 other vulnerability fixes (auth, OTP, private key) |
|
|
50
|
-
| **Knowledge Graph** | Vault entries link into a typed graph (`references`, `derived_from`, `supersedes`, `related`, `continues`) — auto-built from `[[wikilinks]]` + `#tags`, with backlinks. Data layer only for now; visual graph is planned. |
|
|
51
|
-
| **Ecosystem** | CI/CD, CodeQL, Dependabot, Husky, Dockerfile, coverage reporting, semantic release, TypeDoc |
|
|
52
|
-
|
|
53
|
-
---
|
|
15
|
+
Most AI assistants disappear when the conversation ends. **Finch** gives them lasting state — memory that accumulates, agents that keep running, vaults that version knowledge, and workflows that continue after you close the chat.
|
|
54
16
|
|
|
55
|
-
##
|
|
17
|
+
## Why Finch
|
|
56
18
|
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
Your AI remembers what you told it last week, last month, in a different session — and ranks recent context above stale notes via 90-day half-life decay. Run `finch setup` to switch to a free, self-hosted local backend instead of the Finch-hosted proxy.
|
|
65
|
-
|
|
66
|
-
```bash
|
|
67
|
-
remember: I prefer conservative DeFi strategies, max 5% APY
|
|
68
|
-
→ ✓ saved to memory
|
|
69
|
-
auto-loaded in future sessions
|
|
70
|
-
```
|
|
71
|
-
|
|
72
|
-
</td>
|
|
73
|
-
<td width="33%" valign="top">
|
|
74
|
-
|
|
75
|
-
### Agents
|
|
76
|
-
Named, persistent, identity-bound.
|
|
77
|
-
|
|
78
|
-
Spawn an agent with a goal, recall it weeks later, audit every state change. Each agent can hold its own Base wallet address.
|
|
79
|
-
|
|
80
|
-
```bash
|
|
81
|
-
spawn an agent called market-researcher
|
|
82
|
-
goal: track Base chain protocols weekly
|
|
83
|
-
→ 🤖 agent spawned
|
|
84
|
-
recall anytime with agent_recall
|
|
85
|
-
```
|
|
86
|
-
|
|
87
|
-
</td>
|
|
88
|
-
<td width="33%" valign="top">
|
|
89
|
-
|
|
90
|
-
### Workflows
|
|
91
|
-
Packets, automations, monitors, deep research.
|
|
92
|
-
|
|
93
|
-
Anything that runs on a schedule or continues after the chat ends.
|
|
94
|
-
|
|
95
|
-
```bash
|
|
96
|
-
set up a daily monitor for
|
|
97
|
-
AI agent infrastructure news
|
|
98
|
-
→ ✓ monitor created
|
|
99
|
-
runs daily 08:00 UTC
|
|
100
|
-
findings auto-saved to vault
|
|
101
|
-
```
|
|
102
|
-
|
|
103
|
-
</td>
|
|
104
|
-
</tr>
|
|
105
|
-
</table>
|
|
106
|
-
|
|
107
|
-
---
|
|
19
|
+
| | Without Finch | With Finch |
|
|
20
|
+
|--|---------------|------------|
|
|
21
|
+
| **Memory** | Resets every session | Full-text searchable + versioned vault, decays stale notes |
|
|
22
|
+
| **Agents** | One-shot tool calls | Named agents with state and audit history |
|
|
23
|
+
| **Workflows** | Manual chaining | Automations, monitors, packets, deep research |
|
|
24
|
+
| **Local** | Cloud-only | Vault + memory can run fully on your machine |
|
|
108
25
|
|
|
109
26
|
## Install
|
|
110
27
|
|
|
111
|
-
|
|
28
|
+
Always pin the version. Never use `@latest`.
|
|
29
|
+
|
|
112
30
|
```bash
|
|
113
|
-
|
|
31
|
+
# One-command installer (detects common MCP clients)
|
|
32
|
+
npx -y -p @finchagentic/mcp@4.2.0 finch install
|
|
114
33
|
```
|
|
115
|
-
> Detects Claude Desktop, Cursor, Windsurf, VS Code, and Zed, and configures each automatically. **Claude Code** is configured with the dedicated `claude mcp add` command below (its config lives outside the desktop-app path this scan checks).
|
|
116
34
|
|
|
117
35
|
### Claude Code
|
|
36
|
+
|
|
118
37
|
```bash
|
|
119
|
-
claude mcp add finch -s user -- npx -y -p @finchagentic/mcp@4.
|
|
38
|
+
claude mcp add finch -s user -- npx -y -p @finchagentic/mcp@4.2.0 finch-mcp
|
|
120
39
|
```
|
|
121
40
|
|
|
122
41
|
### Cursor / Windsurf / Claude Desktop
|
|
42
|
+
|
|
123
43
|
```json
|
|
124
44
|
{
|
|
125
45
|
"mcpServers": {
|
|
126
46
|
"finch": {
|
|
127
47
|
"command": "npx",
|
|
128
|
-
"args": ["-y", "-p", "@finchagentic/mcp@4.
|
|
48
|
+
"args": ["-y", "-p", "@finchagentic/mcp@4.2.0", "finch-mcp"]
|
|
129
49
|
}
|
|
130
50
|
}
|
|
131
51
|
}
|
|
132
52
|
```
|
|
133
53
|
|
|
134
54
|
### VS Code
|
|
135
|
-
|
|
55
|
+
|
|
136
56
|
```json
|
|
137
57
|
{
|
|
138
58
|
"servers": {
|
|
139
59
|
"finch": {
|
|
140
60
|
"type": "stdio",
|
|
141
61
|
"command": "npx",
|
|
142
|
-
"args": ["-y", "-p", "@finchagentic/mcp@4.
|
|
143
|
-
}
|
|
144
|
-
}
|
|
145
|
-
}
|
|
146
|
-
```
|
|
147
|
-
|
|
148
|
-
### Zed
|
|
149
|
-
In `settings.json` under `context_servers` (each entry needs `"source": "custom"`):
|
|
150
|
-
```json
|
|
151
|
-
{
|
|
152
|
-
"context_servers": {
|
|
153
|
-
"finch": {
|
|
154
|
-
"source": "custom",
|
|
155
|
-
"command": "npx",
|
|
156
|
-
"args": ["-y", "-p", "@finchagentic/mcp@4.0.0", "finch-mcp"]
|
|
62
|
+
"args": ["-y", "-p", "@finchagentic/mcp@4.2.0", "finch-mcp"]
|
|
157
63
|
}
|
|
158
64
|
}
|
|
159
65
|
}
|
|
@@ -168,178 +74,119 @@ In `settings.json` under `context_servers` (each entry needs `"source": "custom"
|
|
|
168
74
|
| Claude Desktop (Windows) | `%APPDATA%\Claude\claude_desktop_config.json` |
|
|
169
75
|
| Cursor | `.cursor/mcp.json` |
|
|
170
76
|
| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
|
|
171
|
-
| Zed | `.config/zed/settings.json` |
|
|
172
77
|
| VS Code | `.vscode/mcp.json` |
|
|
78
|
+
| Zed | `.config/zed/settings.json` |
|
|
173
79
|
|
|
174
80
|
</details>
|
|
175
81
|
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
> **Always pin the version** (`@finchagentic/mcp@4.0.0`, never `@latest`) — this MCP has wallet, credential, and backend persistence capabilities. See [Security Boundaries](#security-boundaries).
|
|
179
|
-
|
|
180
|
-
---
|
|
181
|
-
|
|
182
|
-
## Run it fully local
|
|
82
|
+
No LLM API key is required to start — 108 of 113 tools are plain reads/writes/on-chain calls that your MCP client's own model already drives; only 5 (`ask_finch`, `deep_research`, and scheduled agent learning) do their own multi-step reasoning server-side and need a key (see [Configuration](#configuration)). Tools load on first use.
|
|
183
83
|
|
|
184
|
-
|
|
84
|
+
## Quick start
|
|
185
85
|
|
|
186
|
-
**Turn it on:**
|
|
187
86
|
```bash
|
|
188
|
-
|
|
189
|
-
#
|
|
87
|
+
finch doctor # health check
|
|
88
|
+
finch setup # local vault / memory / providers
|
|
89
|
+
finch vault # inspect local vault
|
|
190
90
|
```
|
|
191
91
|
|
|
192
|
-
|
|
92
|
+
Try in your MCP client:
|
|
193
93
|
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
| **Wallet** | `~/.finch/wallet.json` | Keys never leave your machine. |
|
|
199
|
-
| **The brain** | your MCP client's model | Claude Code, Cursor, etc. **No BYOK LLM key needed** — the model is already yours. |
|
|
200
|
-
| **Public-data tools** | direct API calls | Market, scanner, SEC, GitHub, Robinhood Chain reads — keyless from day one. |
|
|
201
|
-
|
|
202
|
-
**Your data is a plain folder.** Back it up with `cp`, version it with `git`, sync it however you like — it never syncs anywhere on its own.
|
|
203
|
-
|
|
204
|
-
```bash
|
|
205
|
-
finch vault # where it is, what's in it, how to back it up
|
|
206
|
-
finch doctor # confirm "Local vault: on" and everything else
|
|
94
|
+
```
|
|
95
|
+
remember: I prefer conservative DeFi strategies, max 5% risk
|
|
96
|
+
spawn an agent called research-bot to track AI agent news, update it after each session
|
|
97
|
+
save this thesis to vault
|
|
207
98
|
```
|
|
208
99
|
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
---
|
|
212
|
-
|
|
213
|
-
## In Practice
|
|
100
|
+
## What you get
|
|
214
101
|
|
|
215
|
-
|
|
216
|
-
> what have you found so far on AI agent infrastructure?
|
|
217
|
-
→ Pulls from vault: 3 reports across 7 days · summarizes key themes
|
|
102
|
+
**113 tools** across four pillars:
|
|
218
103
|
|
|
219
|
-
|
|
220
|
-
|
|
104
|
+
| Pillar | What it does |
|
|
105
|
+
|--------|----------------|
|
|
106
|
+
| **Memory** | Full-text searchable memory + versioned vault + chronicle |
|
|
107
|
+
| **Agents** | Spawn, recall, update named agents |
|
|
108
|
+
| **Workflows** | Automations, monitors, packets, deep research |
|
|
109
|
+
| **Execution** | Base DeFi, Robinhood Chain, market data, web, GitHub |
|
|
221
110
|
|
|
222
|
-
|
|
223
|
-
→ [estimate_swap] Quote: 0.027 ETH · slippage 0.5% · gas ~$0.03
|
|
224
|
-
→ Confirm swap? (yes/no)
|
|
225
|
-
→ [execute_swap confirmed=true]
|
|
226
|
-
→ ✅ Swap executed · tx 0xabc... · view on Basescan
|
|
111
|
+
Default palette is `core` (lighter context). Full set:
|
|
227
112
|
|
|
228
|
-
|
|
229
|
-
|
|
113
|
+
```json
|
|
114
|
+
"env": { "FINCH_TOOLS": "all" }
|
|
230
115
|
```
|
|
231
116
|
|
|
232
|
-
|
|
117
|
+
## Fully local
|
|
233
118
|
|
|
234
|
-
|
|
119
|
+
Finch is the runtime. **Your LLM is the brain. Your data stays yours.**
|
|
235
120
|
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
| Workflows | Automation · Monitors · Packets · Deep Research · Research Compare/Chain · OS | 19 |
|
|
241
|
-
| Execution | Base DeFi (base_mcp_*) · Robinhood Chain (rh_*) · Stocks (SEC) · Market · Scanner · Web · GitHub · Code Audit · Wallet | 61 |
|
|
121
|
+
```bash
|
|
122
|
+
npx -y -p @finchagentic/mcp@4.2.0 finch setup
|
|
123
|
+
# enable local vault (and optional local memory)
|
|
124
|
+
```
|
|
242
125
|
|
|
243
|
-
|
|
126
|
+
| Piece | Location |
|
|
127
|
+
|-------|----------|
|
|
128
|
+
| Vault | `~/.finch/vault/` |
|
|
129
|
+
| Wallet | `~/.finch/wallet.json` |
|
|
130
|
+
| Config | `~/.finch/config.json` |
|
|
131
|
+
| Brain | your MCP client’s model |
|
|
244
132
|
|
|
245
|
-
|
|
133
|
+
Scheduled/cloud features still need an account. Core memory, vault, and public-data tools work offline of Finch cloud.
|
|
246
134
|
|
|
247
135
|
## Configuration
|
|
248
136
|
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
- `deep_research mode:"report"` — opt-in server-written prose; the default `mode:"sources"` is keyless
|
|
137
|
+
| Variable | Purpose |
|
|
138
|
+
|----------|---------|
|
|
139
|
+
| `FINCH_SESSION_TOKEN` | Signed-in session (vault/memory/agents against your account) |
|
|
140
|
+
| `FINCH_API_KEY` | API key (`finch_sk_…`) |
|
|
141
|
+
| `FINCH_TOOLS` | `core` (default) · `all` · or palettes like `memory,defi` |
|
|
142
|
+
| `FINCH_PROVIDER` | Force `bankr` · `anthropic` · `openai` · `grok` |
|
|
143
|
+
| `FINCH_MODEL` | Model override for host-side loops |
|
|
144
|
+
| `BANKR_API_KEY` / `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` / `GROK_API_KEY` | Required for `ask_finch`, `deep_research`'s synthesis stages, and scheduled-agent learning extraction — these do their own multi-step reasoning server-side and there is no free hosted fallback (BYOK only, one key is enough) |
|
|
145
|
+
| `FIRECRAWL_API_KEY` | Better crawl quality (optional) |
|
|
146
|
+
| `GITHUB_TOKEN` | For `github_search_code` |
|
|
147
|
+
| `ALCHEMY_API_KEY` | Faster Base RPC (optional) |
|
|
261
148
|
|
|
262
|
-
|
|
263
|
-
|----------|---------|------------------|
|
|
264
|
-
| `FINCH_SESSION_TOKEN` | Session token from [app.finchagentic.com](https://app.finchagentic.com) | Recommended — vault, memory and agent tools persist against your account |
|
|
265
|
-
| `BANKR_API_KEY` | Use Bankr as your LLM gateway | Only to *be* a host: CLI loop, cron agents |
|
|
266
|
-
| `ANTHROPIC_API_KEY` | Use your own Anthropic quota | Same — never needed by a tool |
|
|
267
|
-
| `OPENAI_API_KEY` | Use OpenAI for chat/research | Same |
|
|
268
|
-
| `OPENAI_BASE_URL` | Route OpenAI-shaped calls to a self-hosted gateway instead (LiteLLM, vLLM, Ollama, OpenRouter) | Same |
|
|
269
|
-
| `GROK_API_KEY` | Use xAI Grok (`grok-4-fast-reasoning` by default) | Same |
|
|
270
|
-
| `FINCH_PROVIDER` | Force a specific provider: `bankr` \| `anthropic` \| `openai` \| `grok` | Optional |
|
|
271
|
-
| `FIRECRAWL_API_KEY` | Better crawl quality for `deep_research` and `web_search` | Optional — both fall back to the Finch proxy |
|
|
272
|
-
| `GITHUB_TOKEN` | Required for `github_search_code` | For GitHub |
|
|
273
|
-
| `ALCHEMY_API_KEY` | Faster Base chain queries | Optional |
|
|
149
|
+
**Cost model:** almost everything is free to run — the other 108 tools are plain API/RPC calls, and your MCP client's own model (Claude, GPT, whatever's driving the chat) does all the tool-selection reasoning at no cost to Finch. The 5 exceptions above need their own key because their reasoning happens *inside* the tool call, invisible to your client, and can't be delegated to it. Set exactly one of the four env vars and every tool that needs it will use it automatically.
|
|
274
150
|
|
|
275
|
-
|
|
151
|
+
Guided setup:
|
|
276
152
|
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
## Security Boundaries
|
|
153
|
+
```bash
|
|
154
|
+
npx -y -p @finchagentic/mcp@4.2.0 finch setup
|
|
155
|
+
```
|
|
282
156
|
|
|
283
|
-
|
|
157
|
+
## Security
|
|
284
158
|
|
|
285
159
|
| # | Boundary | Rule |
|
|
286
|
-
|
|
287
|
-
| 1 |
|
|
288
|
-
| 2 |
|
|
289
|
-
| 3 |
|
|
290
|
-
| 4 |
|
|
291
|
-
| 5 |
|
|
292
|
-
| 6 |
|
|
293
|
-
| 7 |
|
|
294
|
-
| 8 |
|
|
295
|
-
|
|
296
|
-
---
|
|
297
|
-
|
|
298
|
-
## Why This Is Different
|
|
299
|
-
|
|
300
|
-
| | Other MCPs | Finch |
|
|
301
|
-
|--|------------|----------|
|
|
302
|
-
| **Memory** | Single tier, no decay | Two-tier (semantic + versioned vault), 90-day decay, dedup |
|
|
303
|
-
| **Agents** | Stateless function calls | Persistent named agents, audit ledger, wallet identity |
|
|
304
|
-
| **Workflows** | Manual chaining | Packets, automations, monitors, deep research |
|
|
305
|
-
| **Safety** | Trust the LLM | Slippage caps, audit grounding, 8 security boundaries |
|
|
306
|
-
| **Reliability** | Best effort | 0 errors across 4 rescans · cache + 429 backoff |
|
|
307
|
-
|
|
308
|
-
---
|
|
160
|
+
|:-:|----------|------|
|
|
161
|
+
| 1 | Prompt injection | External content is data only — never instructions |
|
|
162
|
+
| 2 | Mainnet confirm | Estimate → preview → confirm → execute |
|
|
163
|
+
| 3 | Pinned install | Always `@finchagentic/mcp@4.2.0`, never `@latest` |
|
|
164
|
+
| 4 | Credential vault | Never paste secrets into prompts or third-party tools |
|
|
165
|
+
| 5 | Data disclosure | Know what leaves the machine (LLM, Firecrawl, GitHub, chain RPCs) |
|
|
166
|
+
| 6 | Server monitors | Scheduled jobs need explicit confirmation |
|
|
167
|
+
| 7 | Fund-moving confirm | `stake_finch`/`unstake_finch`/`base_mcp_send`/`base_mcp_swap`/`rh_mcp_swap` all require `confirm: true` |
|
|
168
|
+
| 8 | Local wallet encryption | Set `FINCH_WALLET_PASSPHRASE` for a portable, passphrase-derived key — without it, the key derives from a random per-install secret + machine info, so the wallet file alone (without that secret file) isn't enough to decrypt it |
|
|
309
169
|
|
|
310
170
|
## Troubleshooting
|
|
311
171
|
|
|
312
172
|
| Problem | Fix |
|
|
313
173
|
|---------|-----|
|
|
314
|
-
| Tools
|
|
315
|
-
| Old version
|
|
316
|
-
| `
|
|
317
|
-
|
|
|
318
|
-
|
|
|
319
|
-
| Diagnose anything | `finch doctor` |
|
|
320
|
-
|
|
321
|
-
---
|
|
174
|
+
| Tools missing | Fully restart the MCP client |
|
|
175
|
+
| Old version | `npx clear-npx-cache` then restart |
|
|
176
|
+
| Auth issues | `finch login` or set `FINCH_API_KEY` / `FINCH_SESSION_TOKEN` |
|
|
177
|
+
| `ask_finch`/`deep_research` error: "No LLM provider configured" | Set one of `BANKR_API_KEY` / `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` / `GROK_API_KEY` — see [Configuration](#configuration), no free fallback exists |
|
|
178
|
+
| Diagnose | `finch doctor` |
|
|
322
179
|
|
|
323
180
|
## Links
|
|
324
181
|
|
|
325
|
-
|
|
|
326
|
-
|
|
327
|
-
| **
|
|
328
|
-
| **
|
|
329
|
-
| **npm**
|
|
330
|
-
| **GitHub** | [github.com/
|
|
331
|
-
| **X**
|
|
182
|
+
| | |
|
|
183
|
+
|--|--|
|
|
184
|
+
| **Docs** | [docs.finch.com](https://docs.finch.com) |
|
|
185
|
+
| **App** | [app.finchagentic.com](https://app.finchagentic.com) |
|
|
186
|
+
| **npm** | [@finchagentic/mcp](https://www.npmjs.com/package/@finchagentic/mcp) |
|
|
187
|
+
| **GitHub** | [github.com/finchagentic/mcp](https://github.com/finchagentic/mcp) |
|
|
188
|
+
| **X** | [@finchagentic](https://x.com/finchagentic) |
|
|
332
189
|
|
|
333
190
|
---
|
|
334
191
|
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
### Star History
|
|
338
|
-
|
|
339
|
-
[](https://star-history.com/#finch/mcp&Date)
|
|
340
|
-
|
|
341
|
-
---
|
|
342
|
-
|
|
343
|
-
**MIT License** · Built with by the Finch team
|
|
344
|
-
|
|
345
|
-
</div>
|
|
192
|
+
MIT License · Finch
|