@one-source/mcp 5.1.1 → 5.2.1

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 (9) hide show
  1. package/LICENSE +41 -15
  2. package/README.md +8 -2
  3. package/README.npm.md +8 -2
  4. package/README.repo.md +8 -2
  5. package/dist/cli.js +1 -1
  6. package/dist/create-server.d.ts +2 -2
  7. package/dist/create-server.js +2 -2
  8. package/package.json +4 -4
  9. package/skills/onesource-mcp-setup/SKILL.md +308 -308
package/LICENSE CHANGED
@@ -1,3 +1,11 @@
1
+ The MCP project is undergoing a licensing transition from the MIT License to the Apache License, Version 2.0 ("Apache-2.0"). All new code and specification contributions to the project are licensed under Apache-2.0. Documentation contributions (excluding specifications) are licensed under CC-BY-4.0.
2
+
3
+ Contributions for which relicensing consent has been obtained are licensed under Apache-2.0. Contributions made by authors who originally licensed their work under the MIT License and who have not yet granted explicit permission to relicense remain licensed under the MIT License.
4
+
5
+ No rights beyond those granted by the applicable original license are conveyed for such contributions.
6
+
7
+ ---
8
+
1
9
  Apache License
2
10
  Version 2.0, January 2004
3
11
  http://www.apache.org/licenses/
@@ -48,9 +56,9 @@
48
56
  "Contribution" shall mean any work of authorship, including
49
57
  the original version of the Work and any modifications or additions
50
58
  to that Work or Derivative Works thereof, that is intentionally
51
- submitted to the Licensor for inclusion in the Work by the copyright owner
52
- or by an individual or Legal Entity authorized to submit on behalf of
53
- the copyright owner. For the purposes of this definition, "submitted"
59
+ submitted to the Licensor for inclusion in the Work by the copyright
60
+ owner or by an individual or Legal Entity authorized to submit on behalf
61
+ of the copyright owner. For the purposes of this definition, "submitted"
54
62
  means any form of electronic, verbal, or written communication sent
55
63
  to the Licensor or its representatives, including but not limited to
56
64
  communication on electronic mailing lists, source code control systems,
@@ -60,7 +68,7 @@
60
68
  designated in writing by the copyright owner as "Not a Contribution."
61
69
 
62
70
  "Contributor" shall mean Licensor and any individual or Legal Entity
63
- on behalf of whom a Contribution has been received by the Licensor and
71
+ on behalf of whom a Contribution has been received by Licensor and
64
72
  subsequently incorporated within the Work.
65
73
 
66
74
  2. Grant of Copyright License. Subject to the terms and conditions of
@@ -106,7 +114,7 @@
106
114
  (d) If the Work includes a "NOTICE" text file as part of its
107
115
  distribution, then any Derivative Works that You distribute must
108
116
  include a readable copy of the attribution notices contained
109
- within such NOTICE file, excluding any notices that do not
117
+ within such NOTICE file, excluding those notices that do not
110
118
  pertain to any part of the Derivative Works, in at least one
111
119
  of the following places: within a NOTICE text file distributed
112
120
  as part of the Derivative Works; within the Source form or
@@ -175,16 +183,34 @@
175
183
 
176
184
  END OF TERMS AND CONDITIONS
177
185
 
178
- Copyright 2026 BlockParty
186
+ ---
187
+
188
+ MIT License
189
+
190
+ Copyright (c) 2024-2025 Model Context Protocol a Series of LF Projects, LLC.
191
+
192
+ Permission is hereby granted, free of charge, to any person obtaining a copy
193
+ of this software and associated documentation files (the "Software"), to deal
194
+ in the Software without restriction, including without limitation the rights
195
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
196
+ copies of the Software, and to permit persons to whom the Software is
197
+ furnished to do so, subject to the following conditions:
198
+
199
+ The above copyright notice and this permission notice shall be included in all
200
+ copies or substantial portions of the Software.
201
+
202
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
203
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
204
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
205
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
206
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
207
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
208
+ SOFTWARE.
179
209
 
180
- Licensed under the Apache License, Version 2.0 (the "License");
181
- you may not use this file except in compliance with the License.
182
- You may obtain a copy of the License at
210
+ ---
183
211
 
184
- http://www.apache.org/licenses/LICENSE-2.0
212
+ Creative Commons Attribution 4.0 International (CC-BY-4.0)
185
213
 
186
- Unless required by applicable law or agreed to in writing, software
187
- distributed under the License is distributed on an "AS IS" BASIS,
188
- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
189
- See the License for the specific language governing permissions and
190
- limitations under the License.
214
+ Documentation in this project (excluding specifications) is licensed under
215
+ CC-BY-4.0. See https://creativecommons.org/licenses/by/4.0/legalcode for
216
+ the full license text.
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # @one-source/mcp
2
2
 
3
- Unified MCP server for [OneSource](https://docs.onesource.io) — 27 tools for blockchain data and live chain queries in a single server.
3
+ Unified MCP server for [OneSource](https://docs.onesource.io) — 28 tools for blockchain data and live chain queries in a single server.
4
4
 
5
5
  > **What is MCP?** The [Model Context Protocol](https://modelcontextprotocol.io) lets AI assistants call tools and access data sources. This server exposes both the OneSource blockchain API and its documentation as tools.
6
6
 
@@ -44,7 +44,7 @@ Then connect your MCP client to `http://localhost:3000/`.
44
44
 
45
45
  Health check: `GET http://localhost:3000/health`
46
46
 
47
- ## Tools (27)
47
+ ## Tools (28)
48
48
 
49
49
  ### Blockchain API — Live Chain (12 tools)
50
50
 
@@ -83,6 +83,12 @@ RPC only.
83
83
  | `1s_storage_read` | Read storage slot |
84
84
  | `1s_tx_receipt` | Transaction receipt |
85
85
 
86
+ ### Payments (1 tool)
87
+
88
+ | Tool | Description |
89
+ |------|-------------|
90
+ | `1s_payment_mode` | View or switch the x402 payment scheme — `exact` (per-call) vs `batch` (payment channel: one deposit funds many off-chain calls, settled with a single claim) |
91
+
86
92
  ### Setup & Ops (2 tools)
87
93
 
88
94
  No authentication required.
package/README.npm.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # @one-source/mcp
2
2
 
3
- Unified MCP server for [OneSource](https://docs.onesource.io) — 27 tools for blockchain data and live chain queries in a single server.
3
+ Unified MCP server for [OneSource](https://docs.onesource.io) — 28 tools for blockchain data and live chain queries in a single server.
4
4
 
5
5
  > **What is MCP?** The [Model Context Protocol](https://modelcontextprotocol.io) lets AI assistants call tools and access data sources. This server exposes both the OneSource blockchain API and its documentation as tools.
6
6
 
@@ -44,7 +44,7 @@ Then connect your MCP client to `http://localhost:3000/`.
44
44
 
45
45
  Health check: `GET http://localhost:3000/health`
46
46
 
47
- ## Tools (27)
47
+ ## Tools (28)
48
48
 
49
49
  ### Blockchain API — Live Chain (12 tools)
50
50
 
@@ -83,6 +83,12 @@ RPC only.
83
83
  | `1s_storage_read` | Read storage slot |
84
84
  | `1s_tx_receipt` | Transaction receipt |
85
85
 
86
+ ### Payments (1 tool)
87
+
88
+ | Tool | Description |
89
+ |------|-------------|
90
+ | `1s_payment_mode` | View or switch the x402 payment scheme — `exact` (per-call) vs `batch` (payment channel: one deposit funds many off-chain calls, settled with a single claim) |
91
+
86
92
  ### Setup & Ops (2 tools)
87
93
 
88
94
  No authentication required.
package/README.repo.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # @one-source/mcp
2
2
 
3
- Unified MCP server for [OneSource](https://docs.onesource.io) — 27 tools for blockchain data and live chain queries in a single server.
3
+ Unified MCP server for [OneSource](https://docs.onesource.io) — 28 tools for blockchain data and live chain queries in a single server.
4
4
 
5
5
  > **What is MCP?** The [Model Context Protocol](https://modelcontextprotocol.io) lets AI assistants call tools and access data sources. This server exposes both the OneSource blockchain API and its documentation as tools.
6
6
 
@@ -44,7 +44,7 @@ Then connect your MCP client to `http://localhost:3000/`.
44
44
 
45
45
  Health check: `GET http://localhost:3000/health`
46
46
 
47
- ## Tools (27)
47
+ ## Tools (28)
48
48
 
49
49
  ### Blockchain API — Live Chain (12 tools)
50
50
 
@@ -83,6 +83,12 @@ RPC only.
83
83
  | `1s_storage_read` | Read storage slot |
84
84
  | `1s_tx_receipt` | Transaction receipt |
85
85
 
86
+ ### Payments (1 tool)
87
+
88
+ | Tool | Description |
89
+ |------|-------------|
90
+ | `1s_payment_mode` | View or switch the x402 payment scheme — `exact` (per-call) vs `batch` (payment channel: one deposit funds many off-chain calls, settled with a single claim) |
91
+
86
92
  ### Setup & Ops (2 tools)
87
93
 
88
94
  No authentication required.
package/dist/cli.js CHANGED
@@ -31,7 +31,7 @@ function buildInstructions(currentVersion, latestVersion, authMethod) {
31
31
  ? 'Blockchain API tools require x402 payment (USDC on Base). If a tool returns a 402 error, the user needs to configure X402_PRIVATE_KEY. Call 1s_setup_check for diagnostics and setup instructions.'
32
32
  : 'Blockchain API tools require authentication. Set ONESOURCE_API_KEY (API key) or X402_PRIVATE_KEY (x402 micropayments) to access them. Call 1s_setup_check for setup instructions.';
33
33
  const baseline = [
34
- 'OneSource MCP — 27 tools for blockchain data.',
34
+ 'OneSource MCP — 28 tools for blockchain data.',
35
35
  '',
36
36
  authLine,
37
37
  '',
package/dist/create-server.d.ts CHANGED
@@ -1,8 +1,8 @@
1
1
  /**
2
2
  * Unified MCP Server Factory
3
3
  *
4
- * Creates a single McpServer named 'onesource' with all 27 tools
5
- * (25 API + 1 setup check + 1 bug report) by delegating to the register modules.
4
+ * Creates a single McpServer named 'onesource' with all 28 tools
5
+ * (26 API incl. payment-mode + 1 setup check + 1 bug report) by delegating to the register modules.
6
6
  */
7
7
  import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
8
8
  import type { OneSourceClient } from '@one-source/api-mcp/client';
package/dist/create-server.js CHANGED
@@ -1,8 +1,8 @@
1
1
  /**
2
2
  * Unified MCP Server Factory
3
3
  *
4
- * Creates a single McpServer named 'onesource' with all 27 tools
5
- * (25 API + 1 setup check + 1 bug report) by delegating to the register modules.
4
+ * Creates a single McpServer named 'onesource' with all 28 tools
5
+ * (26 API incl. payment-mode + 1 setup check + 1 bug report) by delegating to the register modules.
6
6
  */
7
7
  import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
8
8
  import { registerApiTools } from './register-api-tools.js';
package/package.json CHANGED
@@ -1,9 +1,9 @@
1
1
  {
2
2
  "name": "@one-source/mcp",
3
3
  "mcpName": "io.onesource/mcp",
4
- "version": "5.1.1",
4
+ "version": "5.2.1",
5
5
  "type": "module",
6
- "description": "Unified MCP server for OneSource — 27 tools for blockchain data",
6
+ "description": "Unified MCP server for OneSource — 28 tools for blockchain data",
7
7
  "bin": {
8
8
  "onesource-mcp": "./dist/cli.js"
9
9
  },
@@ -25,11 +25,11 @@
25
25
  "build": "tsc",
26
26
  "prepack": "node -e \"fs=require('fs');fs.copyFileSync('README.md','README.repo.md');fs.copyFileSync('README.npm.md','README.md')\"",
27
27
  "postpack": "node -e \"fs=require('fs');fs.renameSync('README.repo.md','README.md')\"",
28
- "prepublishOnly": "npm run build"
28
+ "prepare": "npm run build"
29
29
  },
30
30
  "dependencies": {
31
31
  "@modelcontextprotocol/sdk": "^1.27.1",
32
- "@one-source/api-mcp": "^5.1.0",
32
+ "@one-source/api-mcp": "^5.2.1",
33
33
  "@one-source/docs-mcp": "^4.0.3",
34
34
  "zod": "^3.24.0"
35
35
  },
package/skills/onesource-mcp-setup/SKILL.md CHANGED
@@ -1,308 +1,308 @@
1
- ---
2
- name: onesource-mcp-setup
3
- description: >-
4
- Guide for installing and configuring the OneSource MCP server. Covers both
5
- authentication options (API key and x402 micropayments), wallet setup, USDC
6
- funding on Base, and verification. Use when a user needs help setting up
7
- OneSource MCP or configuring either auth method.
8
- ---
9
-
10
- # OneSource MCP Setup Guide
11
-
12
- OneSource MCP provides 27 tools for blockchain data and live chain queries. Blockchain API tools require authentication — either an API key (`ONESOURCE_API_KEY`) or x402 micropayments in USDC on the Base network (`X402_PRIVATE_KEY`). If both are set, API key takes priority.
13
-
14
- ## Before You Start
15
-
16
- **Always call `1s_setup_check` before using any other OneSource tools.** This checks the installed version against the latest release and reports authentication status.
17
-
18
- - **If an update is available:** Tell the user and help them update before proceeding. Run `npx -y @one-source/mcp@latest` to get the latest version. The update takes effect on the next session — the user will need to restart their MCP client.
19
- - **If `1s_setup_check` is not available:** The MCP is either not installed or running a version before this tool existed. Help the user install or update using the instructions in Step 2 below.
20
- - **If auth is not configured:** The tool will include setup instructions. Walk the user through them before attempting API calls.
21
-
22
- Do not skip this step — outdated versions may be missing tools, fixes, or protocol changes.
23
-
24
- ## Step 1: Check Current Installation
25
-
26
- Call the `1s_setup_check` tool. It reports:
27
- - Server version (current vs latest)
28
- - Which auth method is active (API key, x402), or whether auth is not yet configured
29
- - Wallet address (if x402 is configured)
30
- - API backend connectivity
31
-
32
- If the tool is not available, the MCP is not installed — go to Step 2.
33
-
34
- ## Step 2: Install or Update
35
-
36
- ### Claude Code
37
-
38
- ```bash
39
- claude mcp add onesource -- npx -y @one-source/mcp@latest
40
- ```
41
-
42
- ### Claude Desktop / Cursor
43
-
44
- Add to your MCP configuration file:
45
-
46
- ```json
47
- {
48
- "mcpServers": {
49
- "onesource": {
50
- "command": "npx",
51
- "args": ["-y", "@one-source/mcp@latest"]
52
- }
53
- }
54
- }
55
- ```
56
-
57
- ### Any MCP Client (stdio)
58
-
59
- ```bash
60
- npx -y @one-source/mcp@latest
61
- ```
62
-
63
- ### Check for Updates
64
-
65
- Compare the installed version (shown in `1s_setup_check` output) against the latest:
66
-
67
- ```bash
68
- npm view @one-source/mcp version
69
- ```
70
-
71
- To update, reinstall with `@latest` or clear the npx cache: `npx -y @one-source/mcp@latest`.
72
-
73
- ## Step 3: Configure Authentication
74
-
75
- Choose one option. If both are set, API key takes priority.
76
-
77
- ### Option A: API Key
78
-
79
- 1. Go to [app.onesource.io](https://app.onesource.io) and create an account.
80
- 2. Subscribe to a developer plan (Stripe checkout).
81
- 3. Navigate to **API Keys** and generate a key.
82
- 4. Copy the key — it starts with `sk_`.
83
-
84
- #### Claude Code
85
-
86
- ```bash
87
- claude mcp remove onesource
88
- claude mcp add onesource -e ONESOURCE_API_KEY=<key> -- npx -y @one-source/mcp@latest
89
- ```
90
-
91
- #### Claude Desktop / Cursor
92
-
93
- Add the `env` block to your MCP config:
94
-
95
- ```json
96
- {
97
- "mcpServers": {
98
- "onesource": {
99
- "command": "npx",
100
- "args": ["-y", "@one-source/mcp@latest"],
101
- "env": {
102
- "ONESOURCE_API_KEY": "<key>"
103
- }
104
- }
105
- }
106
- }
107
- ```
108
-
109
- #### Any MCP Client (stdio)
110
-
111
- ```bash
112
- ONESOURCE_API_KEY=<key> npx -y @one-source/mcp@latest
113
- ```
114
-
115
- After adding the key, reload the MCP server (run `/reload-plugins` in Claude Code, or restart Claude Desktop / Cursor), then call `1s_setup_check`. It should show `Status: Configured (API key)`. You're done — skip to Step 7 to verify a live tool call.
116
-
117
- ---
118
-
119
- ### Option B: x402 Micropayments
120
-
121
- Pay-per-call using USDC on Base. No account required — just an EVM wallet funded with USDC. The server handles payments transparently. Continue with Steps 3B through 6 below.
122
-
123
- ## Step 3B: Get an EVM Private Key
124
-
125
- The `X402_PRIVATE_KEY` is an EVM wallet private key — the same kind used by MetaMask, Coinbase Wallet, or Foundry. It is a 64-character hex string. The `0x` prefix is optional — both formats are accepted.
126
-
127
- ### Option A: Export from MetaMask
128
-
129
- 1. Open MetaMask
130
- 2. Click the three dots next to the account name
131
- 3. Go to **Account details** > **Show private key**
132
- 4. Enter your MetaMask password
133
- 5. Copy the key
134
-
135
- ### Option B: Export from Coinbase Wallet
136
-
137
- 1. Open Coinbase Wallet > Settings > Developer settings
138
- 2. Export your private key
139
-
140
- ### Option C: Generate a New Wallet
141
-
142
- ```bash
143
- # Using OpenSSL (macOS/Linux, or Git Bash on Windows)
144
- openssl rand -hex 32
145
-
146
- # Using Foundry (if installed)
147
- cast wallet new
148
- ```
149
-
150
- ```powershell
151
- # PowerShell (Windows)
152
- -join ((1..32) | ForEach-Object { "{0:x2}" -f (Get-Random -Max 256) })
153
- ```
154
-
155
- **Important:** Use a dedicated wallet for MCP payments — do not use your primary wallet with large holdings. Transfer only what you need.
156
-
157
- ## Step 4: Set the Private Key (x402)
158
-
159
- ### Claude Code
160
-
161
- ```bash
162
- claude mcp remove onesource
163
- claude mcp add onesource -e X402_PRIVATE_KEY=0x... -- npx -y @one-source/mcp@latest
164
- ```
165
-
166
- > **Scope tip:** Claude Code stores MCP configs at three levels — `user`, `project`, and `local`. Use `local` scope (the default for `claude mcp add`) for faster debugging and testing. You can check which scope your config is in by looking at `.claude/settings.local.json` (local), `.claude/settings.json` (project), or `~/.claude/settings.json` (user).
167
-
168
- ### Claude Desktop / Cursor
169
-
170
- Add the `env` block to your MCP config:
171
-
172
- ```json
173
- {
174
- "mcpServers": {
175
- "onesource": {
176
- "command": "npx",
177
- "args": ["-y", "@one-source/mcp@latest"],
178
- "env": {
179
- "X402_PRIVATE_KEY": "0x..."
180
- }
181
- }
182
- }
183
- }
184
- ```
185
-
186
- ### Any MCP Client (stdio)
187
-
188
- ```bash
189
- X402_PRIVATE_KEY=0x... npx -y @one-source/mcp@latest
190
- ```
191
-
192
- ### Manual Setup (Editing the Config File Directly)
193
-
194
- The CLI commands above write to a JSON config file. You can also edit this file directly — this is useful for debugging or if you want to understand what the setup actually does.
195
-
196
- **Claude Code** — Find which file your config is in by running `claude mcp get onesource`. Depending on the scope:
197
- - **Local:** `.claude/settings.local.json` in your project directory
198
- - **Project:** `.claude/settings.json` in your project directory
199
- - **User:** `~/.claude/settings.json` (macOS/Linux) or `%USERPROFILE%\.claude\settings.json` (Windows)
200
-
201
- **Claude Desktop:**
202
- - **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
203
- - **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
204
-
205
- **Cursor:**
206
- - **macOS:** `~/.cursor/mcp.json`
207
- - **Windows:** `%USERPROFILE%\.cursor\mcp.json`
208
-
209
- Open the config file and add (or update) the `onesource` entry inside `"mcpServers"`:
210
-
211
- ```json
212
- {
213
- "mcpServers": {
214
- "onesource": {
215
- "command": "npx",
216
- "args": ["-y", "@one-source/mcp@latest"],
217
- "env": {
218
- "X402_PRIVATE_KEY": "0xYOUR_PRIVATE_KEY_HERE"
219
- }
220
- }
221
- }
222
- }
223
- ```
224
-
225
- Save the file, then reload (see below).
226
-
227
- ### Important: Reload After Config Changes
228
-
229
- Changing the config file (via `claude mcp add` or manual edit) does **not** automatically restart the running MCP server. You must reload:
230
-
231
- - **Claude Code:** Run `/reload-plugins` (preferred — no restart needed), or restart Claude Code entirely.
232
- - **Claude Desktop / Cursor:** Restart the app — close it completely and reopen.
233
-
234
- Without reloading, the old server process keeps running with the old config, and `1s_setup_check` will still show "Not configured" even though the key is in the file.
235
-
236
- ### Alternative: Set the Key as an Environment Variable
237
-
238
- If the `env` block in the config isn't reaching the server after reloading, you can set the key as an environment variable directly instead:
239
-
240
- **bash / zsh (macOS / Linux):**
241
-
242
- ```bash
243
- export X402_PRIVATE_KEY=0x...
244
- ```
245
-
246
- To make it persistent, add the line to your `~/.bashrc`, `~/.zshrc`, or `~/.profile`.
247
-
248
- **PowerShell (Windows):**
249
-
250
- ```powershell
251
- $env:X402_PRIVATE_KEY = "0x..."
252
- ```
253
-
254
- This only lasts for the current session. To make it persistent, either:
255
- - Add it to your PowerShell profile (`notepad $PROFILE`, add the line, restart PowerShell)
256
- - Or set it as a system environment variable: **Settings > System > About > Advanced system settings > Environment Variables > User variables > New** — name: `X402_PRIVATE_KEY`, value: `0x...`
257
-
258
- After setting the variable, restart your MCP client and run `1s_setup_check` to confirm.
259
-
260
- > **Windows note:** Claude Code's `/doctor` command may warn that Windows requires a `cmd /c` wrapper to execute `npx`. If you encounter issues, update the config to use `"command": "cmd"` with `"args": ["/c", "npx", "-y", "@one-source/mcp@latest"]`.
261
-
262
- ### Security
263
-
264
- - **Never** commit your private key to source control.
265
- - Use environment variables, a `.env` file (excluded from git), or a secrets manager.
266
- - Use a dedicated wallet with minimal funds — only what you need for API calls.
267
-
268
- ## Step 5: Find Your Wallet Address (x402)
269
-
270
- After setting the key and reloading the MCP server:
271
-
272
- 1. Call `1s_setup_check` — it shows the wallet address derived from your key under "Wallet address". This is the address you need to fund.
273
- 2. Alternatively, import the key into MetaMask to see the address.
274
-
275
- ## Step 6: Fund the Wallet with USDC on Base (x402)
276
-
277
- The wallet must hold **USDC on the Base network** (not Ethereum mainnet, not other tokens).
278
-
279
- 1. Send USDC to the wallet address from Step 5 **on the Base network**.
280
- 2. A few dollars ($1–5 USDC) is enough for hundreds of API calls.
281
-
282
- If your USDC is on Ethereum mainnet, bridge it to Base using the [Base Bridge](https://bridge.base.org) or any cross-chain bridge that supports Base.
283
-
284
- ## Step 7: Verify
285
-
286
- After setting your auth (either option) and reloading:
287
-
288
- 1. **Check MCP connection** — Run `/mcp` to confirm the `onesource` server is connected.
289
- 2. **Run `1s_setup_check`** — You should see:
290
- - **Authentication:** `Configured (API key)` or `Configured (x402)` — not "Not configured"
291
- - **Wallet address:** Your wallet address (x402 only)
292
- - **API backend:** Reachable
293
- 3. **Test a live tool** — Call `1s_network_info` for ethereum. If it returns a block number and gas price, auth is working end-to-end.
294
-
295
- > **Tip:** If you edited the config file manually (instead of using `claude mcp add`), you must run `/reload-plugins` for changes to take effect. Restarting Claude Code also works.
296
-
297
- ## Troubleshooting
298
-
299
- | Problem | Solution |
300
- |---------|----------|
301
- | `1s_setup_check` shows "Not configured" | Most common cause: config was changed but the MCP server wasn't reloaded. Run `/reload-plugins` in Claude Code, or restart Claude Desktop / Cursor. If the key still isn't reaching the server, try setting it as an environment variable directly — see **Alternative: Set the Key as an Environment Variable** above. |
302
- | `1s_setup_check` shows API key configured but tools return 402 | The key may be invalid or the account may not have a developer plan. Verify the key at app.onesource.io. |
303
- | "MCP server onesource already exists" error | Run `claude mcp remove onesource` first, then re-add it with your updated config. |
304
- | Config changed but nothing happened | Run `/reload-plugins` in Claude Code to reload MCP servers, then `/mcp` to check connection status. |
305
- | Tool returns HTTP 402 error (x402 path) | x402 is not configured, or the wallet has insufficient USDC on Base. Check `1s_setup_check` for wallet address and balance. |
306
- | "x402 setup failed" in server logs | The private key format is wrong. It must be a 64-character hex string (with or without `0x` prefix). |
307
- | Key is set but wallet shows 0 USDC | Make sure USDC is on the **Base** network, not Ethereum mainnet or another chain. |
308
- | Tools work but results seem stale | Check `1s_setup_check` for version — you may need to update to the latest. |
1
+ ---
2
+ name: onesource-mcp-setup
3
+ description: >-
4
+ Guide for installing and configuring the OneSource MCP server. Covers both
5
+ authentication options (API key and x402 micropayments), wallet setup, USDC
6
+ funding on Base, and verification. Use when a user needs help setting up
7
+ OneSource MCP or configuring either auth method.
8
+ ---
9
+
10
+ # OneSource MCP Setup Guide
11
+
12
+ OneSource MCP provides 27 tools for blockchain data and live chain queries. Blockchain API tools require authentication — either an API key (`ONESOURCE_API_KEY`) or x402 micropayments in USDC on the Base network (`X402_PRIVATE_KEY`). If both are set, API key takes priority.
13
+
14
+ ## Before You Start
15
+
16
+ **Always call `1s_setup_check` before using any other OneSource tools.** This checks the installed version against the latest release and reports authentication status.
17
+
18
+ - **If an update is available:** Tell the user and help them update before proceeding. Run `npx -y @one-source/mcp@latest` to get the latest version. The update takes effect on the next session — the user will need to restart their MCP client.
19
+ - **If `1s_setup_check` is not available:** The MCP is either not installed or running a version before this tool existed. Help the user install or update using the instructions in Step 2 below.
20
+ - **If auth is not configured:** The tool will include setup instructions. Walk the user through them before attempting API calls.
21
+
22
+ Do not skip this step — outdated versions may be missing tools, fixes, or protocol changes.
23
+
24
+ ## Step 1: Check Current Installation
25
+
26
+ Call the `1s_setup_check` tool. It reports:
27
+ - Server version (current vs latest)
28
+ - Which auth method is active (API key, x402), or whether auth is not yet configured
29
+ - Wallet address (if x402 is configured)
30
+ - API backend connectivity
31
+
32
+ If the tool is not available, the MCP is not installed — go to Step 2.
33
+
34
+ ## Step 2: Install or Update
35
+
36
+ ### Claude Code
37
+
38
+ ```bash
39
+ claude mcp add onesource -- npx -y @one-source/mcp@latest
40
+ ```
41
+
42
+ ### Claude Desktop / Cursor
43
+
44
+ Add to your MCP configuration file:
45
+
46
+ ```json
47
+ {
48
+ "mcpServers": {
49
+ "onesource": {
50
+ "command": "npx",
51
+ "args": ["-y", "@one-source/mcp@latest"]
52
+ }
53
+ }
54
+ }
55
+ ```
56
+
57
+ ### Any MCP Client (stdio)
58
+
59
+ ```bash
60
+ npx -y @one-source/mcp@latest
61
+ ```
62
+
63
+ ### Check for Updates
64
+
65
+ Compare the installed version (shown in `1s_setup_check` output) against the latest:
66
+
67
+ ```bash
68
+ npm view @one-source/mcp version
69
+ ```
70
+
71
+ To update, reinstall with `@latest` or clear the npx cache: `npx -y @one-source/mcp@latest`.
72
+
73
+ ## Step 3: Configure Authentication
74
+
75
+ Choose one option. If both are set, API key takes priority.
76
+
77
+ ### Option A: API Key
78
+
79
+ 1. Go to [app.onesource.io](https://app.onesource.io) and create an account.
80
+ 2. Subscribe to a developer plan (Stripe checkout).
81
+ 3. Navigate to **API Keys** and generate a key.
82
+ 4. Copy the key — it starts with `sk_`.
83
+
84
+ #### Claude Code
85
+
86
+ ```bash
87
+ claude mcp remove onesource
88
+ claude mcp add onesource -e ONESOURCE_API_KEY=<key> -- npx -y @one-source/mcp@latest
89
+ ```
90
+
91
+ #### Claude Desktop / Cursor
92
+
93
+ Add the `env` block to your MCP config:
94
+
95
+ ```json
96
+ {
97
+ "mcpServers": {
98
+ "onesource": {
99
+ "command": "npx",
100
+ "args": ["-y", "@one-source/mcp@latest"],
101
+ "env": {
102
+ "ONESOURCE_API_KEY": "<key>"
103
+ }
104
+ }
105
+ }
106
+ }
107
+ ```
108
+
109
+ #### Any MCP Client (stdio)
110
+
111
+ ```bash
112
+ ONESOURCE_API_KEY=<key> npx -y @one-source/mcp@latest
113
+ ```
114
+
115
+ After adding the key, reload the MCP server (run `/reload-plugins` in Claude Code, or restart Claude Desktop / Cursor), then call `1s_setup_check`. It should show `Status: Configured (API key)`. You're done — skip to Step 7 to verify a live tool call.
116
+
117
+ ---
118
+
119
+ ### Option B: x402 Micropayments
120
+
121
+ Pay-per-call using USDC on Base. No account required — just an EVM wallet funded with USDC. The server handles payments transparently. Continue with Steps 3B through 6 below.
122
+
123
+ ## Step 3B: Get an EVM Private Key
124
+
125
+ The `X402_PRIVATE_KEY` is an EVM wallet private key — the same kind used by MetaMask, Coinbase Wallet, or Foundry. It is a 64-character hex string. The `0x` prefix is optional — both formats are accepted.
126
+
127
+ ### Option A: Export from MetaMask
128
+
129
+ 1. Open MetaMask
130
+ 2. Click the three dots next to the account name
131
+ 3. Go to **Account details** > **Show private key**
132
+ 4. Enter your MetaMask password
133
+ 5. Copy the key
134
+
135
+ ### Option B: Export from Coinbase Wallet
136
+
137
+ 1. Open Coinbase Wallet > Settings > Developer settings
138
+ 2. Export your private key
139
+
140
+ ### Option C: Generate a New Wallet
141
+
142
+ ```bash
143
+ # Using OpenSSL (macOS/Linux, or Git Bash on Windows)
144
+ openssl rand -hex 32
145
+
146
+ # Using Foundry (if installed)
147
+ cast wallet new
148
+ ```
149
+
150
+ ```powershell
151
+ # PowerShell (Windows)
152
+ -join ((1..32) | ForEach-Object { "{0:x2}" -f (Get-Random -Max 256) })
153
+ ```
154
+
155
+ **Important:** Use a dedicated wallet for MCP payments — do not use your primary wallet with large holdings. Transfer only what you need.
156
+
157
+ ## Step 4: Set the Private Key (x402)
158
+
159
+ ### Claude Code
160
+
161
+ ```bash
162
+ claude mcp remove onesource
163
+ claude mcp add onesource -e X402_PRIVATE_KEY=0x... -- npx -y @one-source/mcp@latest
164
+ ```
165
+
166
+ > **Scope tip:** Claude Code stores MCP configs at three levels — `user`, `project`, and `local`. Use `local` scope (the default for `claude mcp add`) for faster debugging and testing. You can check which scope your config is in by looking at `.claude/settings.local.json` (local), `.claude/settings.json` (project), or `~/.claude/settings.json` (user).
167
+
168
+ ### Claude Desktop / Cursor
169
+
170
+ Add the `env` block to your MCP config:
171
+
172
+ ```json
173
+ {
174
+ "mcpServers": {
175
+ "onesource": {
176
+ "command": "npx",
177
+ "args": ["-y", "@one-source/mcp@latest"],
178
+ "env": {
179
+ "X402_PRIVATE_KEY": "0x..."
180
+ }
181
+ }
182
+ }
183
+ }
184
+ ```
185
+
186
+ ### Any MCP Client (stdio)
187
+
188
+ ```bash
189
+ X402_PRIVATE_KEY=0x... npx -y @one-source/mcp@latest
190
+ ```
191
+
192
+ ### Manual Setup (Editing the Config File Directly)
193
+
194
+ The CLI commands above write to a JSON config file. You can also edit this file directly — this is useful for debugging or if you want to understand what the setup actually does.
195
+
196
+ **Claude Code** — Find which file your config is in by running `claude mcp get onesource`. Depending on the scope:
197
+ - **Local:** `.claude/settings.local.json` in your project directory
198
+ - **Project:** `.claude/settings.json` in your project directory
199
+ - **User:** `~/.claude/settings.json` (macOS/Linux) or `%USERPROFILE%\.claude\settings.json` (Windows)
200
+
201
+ **Claude Desktop:**
202
+ - **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
203
+ - **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
204
+
205
+ **Cursor:**
206
+ - **macOS:** `~/.cursor/mcp.json`
207
+ - **Windows:** `%USERPROFILE%\.cursor\mcp.json`
208
+
209
+ Open the config file and add (or update) the `onesource` entry inside `"mcpServers"`:
210
+
211
+ ```json
212
+ {
213
+ "mcpServers": {
214
+ "onesource": {
215
+ "command": "npx",
216
+ "args": ["-y", "@one-source/mcp@latest"],
217
+ "env": {
218
+ "X402_PRIVATE_KEY": "0xYOUR_PRIVATE_KEY_HERE"
219
+ }
220
+ }
221
+ }
222
+ }
223
+ ```
224
+
225
+ Save the file, then reload (see below).
226
+
227
+ ### Important: Reload After Config Changes
228
+
229
+ Changing the config file (via `claude mcp add` or manual edit) does **not** automatically restart the running MCP server. You must reload:
230
+
231
+ - **Claude Code:** Run `/reload-plugins` (preferred — no restart needed), or restart Claude Code entirely.
232
+ - **Claude Desktop / Cursor:** Restart the app — close it completely and reopen.
233
+
234
+ Without reloading, the old server process keeps running with the old config, and `1s_setup_check` will still show "Not configured" even though the key is in the file.
235
+
236
+ ### Alternative: Set the Key as an Environment Variable
237
+
238
+ If the `env` block in the config isn't reaching the server after reloading, you can set the key as an environment variable directly instead:
239
+
240
+ **bash / zsh (macOS / Linux):**
241
+
242
+ ```bash
243
+ export X402_PRIVATE_KEY=0x...
244
+ ```
245
+
246
+ To make it persistent, add the line to your `~/.bashrc`, `~/.zshrc`, or `~/.profile`.
247
+
248
+ **PowerShell (Windows):**
249
+
250
+ ```powershell
251
+ $env:X402_PRIVATE_KEY = "0x..."
252
+ ```
253
+
254
+ This only lasts for the current session. To make it persistent, either:
255
+ - Add it to your PowerShell profile (`notepad $PROFILE`, add the line, restart PowerShell)
256
+ - Or set it as a system environment variable: **Settings > System > About > Advanced system settings > Environment Variables > User variables > New** — name: `X402_PRIVATE_KEY`, value: `0x...`
257
+
258
+ After setting the variable, restart your MCP client and run `1s_setup_check` to confirm.
259
+
260
+ > **Windows note:** Claude Code's `/doctor` command may warn that Windows requires a `cmd /c` wrapper to execute `npx`. If you encounter issues, update the config to use `"command": "cmd"` with `"args": ["/c", "npx", "-y", "@one-source/mcp@latest"]`.
261
+
262
+ ### Security
263
+
264
+ - **Never** commit your private key to source control.
265
+ - Use environment variables, a `.env` file (excluded from git), or a secrets manager.
266
+ - Use a dedicated wallet with minimal funds — only what you need for API calls.
267
+
268
+ ## Step 5: Find Your Wallet Address (x402)
269
+
270
+ After setting the key and reloading the MCP server:
271
+
272
+ 1. Call `1s_setup_check` — it shows the wallet address derived from your key under "Wallet address". This is the address you need to fund.
273
+ 2. Alternatively, import the key into MetaMask to see the address.
274
+
275
+ ## Step 6: Fund the Wallet with USDC on Base (x402)
276
+
277
+ The wallet must hold **USDC on the Base network** (not Ethereum mainnet, not other tokens).
278
+
279
+ 1. Send USDC to the wallet address from Step 5 **on the Base network**.
280
+ 2. A few dollars ($1–5 USDC) is enough for hundreds of API calls.
281
+
282
+ If your USDC is on Ethereum mainnet, bridge it to Base using the [Base Bridge](https://bridge.base.org) or any cross-chain bridge that supports Base.
283
+
284
+ ## Step 7: Verify
285
+
286
+ After setting your auth (either option) and reloading:
287
+
288
+ 1. **Check MCP connection** — Run `/mcp` to confirm the `onesource` server is connected.
289
+ 2. **Run `1s_setup_check`** — You should see:
290
+ - **Authentication:** `Configured (API key)` or `Configured (x402)` — not "Not configured"
291
+ - **Wallet address:** Your wallet address (x402 only)
292
+ - **API backend:** Reachable
293
+ 3. **Test a live tool** — Call `1s_network_info` for ethereum. If it returns a block number and gas price, auth is working end-to-end.
294
+
295
+ > **Tip:** If you edited the config file manually (instead of using `claude mcp add`), you must run `/reload-plugins` for changes to take effect. Restarting Claude Code also works.
296
+
297
+ ## Troubleshooting
298
+
299
+ | Problem | Solution |
300
+ |---------|----------|
301
+ | `1s_setup_check` shows "Not configured" | Most common cause: config was changed but the MCP server wasn't reloaded. Run `/reload-plugins` in Claude Code, or restart Claude Desktop / Cursor. If the key still isn't reaching the server, try setting it as an environment variable directly — see **Alternative: Set the Key as an Environment Variable** above. |
302
+ | `1s_setup_check` shows API key configured but tools return 402 | The key may be invalid or the account may not have a developer plan. Verify the key at app.onesource.io. |
303
+ | "MCP server onesource already exists" error | Run `claude mcp remove onesource` first, then re-add it with your updated config. |
304
+ | Config changed but nothing happened | Run `/reload-plugins` in Claude Code to reload MCP servers, then `/mcp` to check connection status. |
305
+ | Tool returns HTTP 402 error (x402 path) | x402 is not configured, or the wallet has insufficient USDC on Base. Check `1s_setup_check` for wallet address and balance. |
306
+ | "x402 setup failed" in server logs | The private key format is wrong. It must be a 64-character hex string (with or without `0x` prefix). |
307
+ | Key is set but wallet shows 0 USDC | Make sure USDC is on the **Base** network, not Ethereum mainnet or another chain. |
308
+ | Tools work but results seem stale | Check `1s_setup_check` for version — you may need to update to the latest. |