@one-source/mcp 5.1.1 → 5.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.
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 +99 -311
  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,365 +1,153 @@
1
- # @one-source/mcp
1
+ # MCP Registry
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
+ The MCP registry provides MCP clients with a list of MCP servers, like an app store for MCP servers.
4
4
 
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.
5
+ [**📤 Publish my MCP server**](docs/modelcontextprotocol-io/quickstart.mdx) | [**⚡️ Live API docs**](https://registry.modelcontextprotocol.io/docs) | [**👀 Ecosystem vision**](docs/design/ecosystem-vision.md) | 📖 **[Full documentation](./docs)**
6
6
 
7
- ## Quick Start
7
+ ## Development Status
8
8
 
9
- ### Claude Code
9
+ **2025-10-24 update**: The Registry API has entered an **API freeze (v0.1)** 🎉. For the next month or more, the API will remain stable with no breaking changes, allowing integrators to confidently implement support. This freeze applies to v0.1 while development continues on v0. We'll use this period to validate the API in real-world integrations and gather feedback to shape v1 for general availability. Thank you to everyone for your contributions and patience—your involvement has been key to getting us here!
10
10
 
11
- ```bash
12
- claude mcp add onesource -- npx -y @one-source/mcp@latest
13
- ```
14
-
15
- ### Claude Desktop / Cursor
16
-
17
- Add to your MCP config:
18
-
19
- ```json
20
- {
21
- "mcpServers": {
22
- "onesource": {
23
- "command": "npx",
24
- "args": ["-y", "@one-source/mcp@latest"]
25
- }
26
- }
27
- }
28
- ```
29
-
30
- ### Any MCP Client (stdio)
31
-
32
- ```bash
33
- npx -y @one-source/mcp@latest
34
- ```
35
-
36
- ### HTTP Server (self-hosted)
37
-
38
- ```bash
39
- npx -y @one-source/mcp@latest --http
40
- npx -y @one-source/mcp@latest --http --port=8080
41
- ```
42
-
43
- Then connect your MCP client to `http://localhost:3000/`.
44
-
45
- Health check: `GET http://localhost:3000/health`
11
+ **2025-09-08 update**: The registry has launched in preview 🎉 ([announcement blog post](https://blog.modelcontextprotocol.io/posts/2025-09-08-mcp-registry-preview/)). While the system is now more stable, this is still a preview release and breaking changes or data resets may occur. A general availability (GA) release will follow later. We'd love your feedback in [GitHub discussions](https://github.com/modelcontextprotocol/registry/discussions/new?category=ideas) or in the [#registry-dev Discord](https://discord.com/channels/1358869848138059966/1369487942862504016) ([joining details here](https://modelcontextprotocol.io/community/communication)).
46
12
 
47
- ## Tools (27)
13
+ Current key maintainers:
14
+ - **Adam Jones** (Anthropic) [@domdomegg](https://github.com/domdomegg)
15
+ - **Tadas Antanavicius** (PulseMCP) [@tadasant](https://github.com/tadasant)
16
+ - **Toby Padilla** (GitHub) [@toby](https://github.com/toby)
17
+ - **Radoslav (Rado) Dimitrov** (Stacklok) [@rdimitrov](https://github.com/rdimitrov)
48
18
 
49
- ### Blockchain API — Live Chain (12 tools)
19
+ ## Contributing
50
20
 
51
- | Tool | Description |
52
- |------|-------------|
53
- | `1s_allowance_live` | ERC20 allowance check |
54
- | `1s_contract_info_live` | Contract type detection via ERC165 |
55
- | `1s_erc1155_balance_live` | ERC1155 balance via RPC |
56
- | `1s_erc20_balance_live` | ERC20 balance via balanceOf |
57
- | `1s_erc20_transfers_live` | ERC20 Transfer logs via eth_getLogs |
58
- | `1s_erc721_tokens_live` | ERC721 token enumeration |
59
- | `1s_events_live` | Event logs via eth_getLogs |
60
- | `1s_multi_balance_live` | ETH + multiple ERC20 balances |
61
- | `1s_nft_metadata_live` | NFT metadata via tokenURI |
62
- | `1s_nft_owner_live` | NFT owner via ownerOf |
63
- | `1s_total_supply_live` | Token total supply |
64
- | `1s_tx_details_live` | Transaction + receipt via RPC |
21
+ We use multiple channels for collaboration - see [modelcontextprotocol.io/community/communication](https://modelcontextprotocol.io/community/communication).
65
22
 
66
- ### Blockchain API — Chain Utilities (13 tools)
23
+ Often (but not always) ideas flow through this pipeline:
67
24
 
68
- RPC only.
25
+ - **[Discord](https://modelcontextprotocol.io/community/communication)** - Real-time community discussions
26
+ - **[Discussions](https://github.com/modelcontextprotocol/registry/discussions)** - Propose and discuss product/technical requirements
27
+ - **[Issues](https://github.com/modelcontextprotocol/registry/issues)** - Track well-scoped technical work
28
+ - **[Pull Requests](https://github.com/modelcontextprotocol/registry/pulls)** - Contribute work towards issues
69
29
 
70
- | Tool | Description |
71
- |------|-------------|
72
- | `1s_block_by_number` | Block details by number via RPC |
73
- | `1s_block_number` | Latest block number |
74
- | `1s_chain_id` | EIP-155 chain ID |
75
- | `1s_contract_code` | Contract bytecode |
76
- | `1s_ens_resolve` | ENS name/address resolution |
77
- | `1s_estimate_gas` | Gas estimation |
78
- | `1s_network_info` | Chain ID, block number, gas price |
79
- | `1s_nonce` | Transaction count |
80
- | `1s_pending_block` | Pending block from mempool |
81
- | `1s_proxy_detect` | Proxy contract detection |
82
- | `1s_simulate_call` | Simulate eth_call |
83
- | `1s_storage_read` | Read storage slot |
84
- | `1s_tx_receipt` | Transaction receipt |
30
+ ### Quick start:
85
31
 
86
- ### Setup & Ops (2 tools)
32
+ #### Pre-requisites
87
33
 
88
- No authentication required.
34
+ - **Docker**
35
+ - **Go 1.24.x**
36
+ - **ko** - Container image builder for Go ([installation instructions](https://ko.build/install/))
37
+ - **golangci-lint v2.4.0**
89
38
 
90
- | Tool | Purpose | When to use |
91
- |------|---------|-------------|
92
- | `1s_setup_check` | Server health, version, auth status, setup instructions | First thing to call — checks if everything is configured |
93
- | `1s_report_bug` | Report bugs to Slack (or GitHub Issues fallback) | When a tool errors or user wants to report an issue |
94
-
95
- ## Networks
96
-
97
- All blockchain API tools accept an optional `network` parameter:
98
-
99
- | Network | Description |
100
- |---------|-------------|
101
- | `ethereum` | Ethereum mainnet (default) |
102
- | `sepolia` | Ethereum Sepolia testnet |
103
- | `avax` | Avalanche C-Chain |
104
-
105
- ## Authentication
106
-
107
- Blockchain API tools require authentication. Two options are available — if both are set, API key takes priority.
108
-
109
- | Method | Variable | Description |
110
- |--------|----------|-------------|
111
- | API key | `ONESOURCE_API_KEY` | Unlimited calls, no per-call cost |
112
- | x402 micropayments | `X402_PRIVATE_KEY` | Pay-per-call via USDC on Base, no account required |
113
-
114
- ### Option 1: API Key
115
-
116
- 1. Go to [app.onesource.io](https://app.onesource.io) and create an account.
117
- 2. Subscribe to a developer plan (Stripe checkout).
118
- 3. Navigate to **API Keys** and generate a key.
119
- 4. Copy the key — it starts with `sk_`.
120
-
121
- #### Claude Code
39
+ #### Running the server
122
40
 
123
41
  ```bash
124
- claude mcp add onesource -e ONESOURCE_API_KEY=<key> -- npx -y @one-source/mcp@latest
42
+ # Start full development environment
43
+ make dev-compose
125
44
  ```
126
45
 
127
- #### Claude Desktop / Cursor
128
-
129
- Add the `env` block to your MCP config:
130
-
131
- ```json
132
- {
133
- "mcpServers": {
134
- "onesource": {
135
- "command": "npx",
136
- "args": ["-y", "@one-source/mcp@latest"],
137
- "env": {
138
- "ONESOURCE_API_KEY": "<key>"
139
- }
140
- }
141
- }
142
- }
143
- ```
46
+ This starts the registry at [`localhost:8080`](http://localhost:8080) with PostgreSQL. The database uses ephemeral storage and is reset each time you restart the containers, ensuring a clean state for development and testing.
144
47
 
145
- #### Any MCP Client (stdio)
48
+ **Note:** The registry uses [ko](https://ko.build) to build container images. The `make dev-compose` command automatically builds the registry image with ko and loads it into your local Docker daemon before starting the services.
146
49
 
147
- ```bash
148
- ONESOURCE_API_KEY=<key> npx -y @one-source/mcp@latest
149
- ```
50
+ By default, the registry seeds from the production API with a filtered subset of servers (to keep startup fast). This ensures your local environment mirrors production behavior and all seed data passes validation. For offline development you can seed from a file without validation with `MCP_REGISTRY_SEED_FROM=data/seed.json MCP_REGISTRY_ENABLE_REGISTRY_VALIDATION=false make dev-compose`.
150
51
 
151
- After adding, reload the MCP server and call `1s_setup_check` — it should show `Status: Configured (API key)`.
52
+ The setup can be configured with environment variables in [docker-compose.yml](./docker-compose.yml) - see [.env.example](./.env.example) for a reference.
152
53
 
153
- ### Option 2: x402 Micropayments
54
+ <details>
55
+ <summary>Alternative: Running a pre-built Docker image</summary>
154
56
 
155
- Blockchain API endpoints are priced in USDC on Base via [x402](https://github.com/coinbase/x402). When you set `X402_PRIVATE_KEY`, the server automatically handles payments — tool calls are paid and retried transparently without any extra work from the agent.
156
-
157
- 1. **Get an EVM private key** — export one from MetaMask, Coinbase Wallet, or any EVM wallet, or generate a fresh one. The key is a 64-character hex string. The `0x` prefix is optional — both formats are accepted.
158
- 2. **Pass the key to the server** using one of the methods below.
159
- 3. **Reload and find your wallet address** — reload the MCP server, then call `1s_setup_check`. It will show the wallet address derived from your key under "Wallet address".
160
- 4. **Fund that address with USDC on Base** — send USDC to the address shown in `1s_setup_check`, on the [Base](https://base.org) network. A few dollars ($1–5 USDC) is enough for hundreds of calls. If your USDC is on Ethereum mainnet, bridge it using the [Base Bridge](https://bridge.base.org).
161
- 5. **Verify** — call `1s_network_info` for ethereum. If it returns chain data (block number, gas price), x402 payments are working end-to-end.
162
-
163
- #### Claude Code
57
+ Pre-built Docker images are automatically published to GitHub Container Registry:
164
58
 
165
59
  ```bash
166
- claude mcp add onesource -e X402_PRIVATE_KEY=<key> -- npx -y @one-source/mcp@latest
167
- ```
60
+ # Run latest stable release
61
+ docker run -p 8080:8080 ghcr.io/modelcontextprotocol/registry:latest
168
62
 
169
- #### Claude Desktop / Cursor
170
-
171
- Add the `env` block to your MCP config:
172
-
173
- ```json
174
- {
175
- "mcpServers": {
176
- "onesource": {
177
- "command": "npx",
178
- "args": ["-y", "@one-source/mcp@latest"],
179
- "env": {
180
- "X402_PRIVATE_KEY": "<key>"
181
- }
182
- }
183
- }
184
- }
185
- ```
63
+ # Run latest from main branch (continuous deployment)
64
+ docker run -p 8080:8080 ghcr.io/modelcontextprotocol/registry:main
186
65
 
187
- #### Any MCP Client (stdio)
66
+ # Run specific release version
67
+ docker run -p 8080:8080 ghcr.io/modelcontextprotocol/registry:v1.0.0
188
68
 
189
- ```bash
190
- X402_PRIVATE_KEY=<key> npx -y @one-source/mcp@latest
69
+ # Run development build from main branch
70
+ docker run -p 8080:8080 ghcr.io/modelcontextprotocol/registry:main-20250906-abc123d
191
71
  ```
192
72
 
193
- ### Config File Locations
194
-
195
- If you prefer editing the config file directly instead of using CLI commands:
196
-
197
- | Client | Config file path |
198
- |--------|-----------------|
199
- | Claude Code | Run `claude mcp get onesource` to see the file path |
200
- | Claude Desktop (macOS) | `~/Library/Application Support/Claude/claude_desktop_config.json` |
201
- | Claude Desktop (Windows) | `%APPDATA%\Claude\claude_desktop_config.json` |
202
- | Cursor (macOS) | `~/.cursor/mcp.json` |
203
- | Cursor (Windows) | `%USERPROFILE%\.cursor\mcp.json` |
204
-
205
- Add the `onesource` entry inside `"mcpServers"` using the JSON block shown above.
206
-
207
- ### Alternative: Set as an Environment Variable
208
-
209
- Instead of the `env` config block, you can set either variable as a shell or system environment variable: `export ONESOURCE_API_KEY=<key>` (bash/zsh) or `$env:ONESOURCE_API_KEY = "<key>"` (PowerShell). Set it at the OS level for persistence across sessions.
210
-
211
- ### Security
212
-
213
- Never commit keys to source control. Use environment variables, a `.env` file (excluded from git), or a secrets manager.
214
-
215
- > **After any config change:** Run `/reload-plugins` in Claude Code, or restart Claude Desktop / Cursor. The MCP server must be reloaded to pick up new environment variables.
216
-
217
- ## Environment Variables
218
-
219
- | Variable | Default | Description |
220
- |----------|---------|-------------|
221
- | `ONESOURCE_API_KEY` | — | OneSource API key for Bearer token auth. Takes priority over x402. |
222
- | `X402_PRIVATE_KEY` | — | EVM private key (64-char hex, `0x` prefix optional) for automatic x402 USDC payments on Base |
223
- | `ONESOURCE_BASE_URL` | `https://skills.onesource.io` | API base URL |
224
- | `ONESOURCE_ANALYTICS` | — | Set to `false` to disable analytics |
225
- | `ONESOURCE_ANALYTICS_URL` | — | Dashboard endpoint for analytics |
226
- | `X402_ANALYTICS_KEY` | — | API key for dashboard analytics |
227
-
228
- ## Troubleshooting
229
-
230
- **`1s_setup_check` shows "Not configured"**
231
- Set either `ONESOURCE_API_KEY` or `X402_PRIVATE_KEY`. Reload the MCP server after setting either variable (see note above). If the key still isn't reaching the server, set it as a shell environment variable directly.
232
-
233
- **Getting 403 / wrong key active despite correct setup**
234
- A key set in your shell profile (e.g. `~/.zshrc`, `~/.bash_profile`) is picked up by the MCP server process even if it isn't in your Claude MCP config. Run `echo $ONESOURCE_API_KEY` in your terminal to check. If it prints a value you didn't intend, unset it (`unset ONESOURCE_API_KEY`) or explicitly clear it when adding the server: `claude mcp add onesource -e ONESOURCE_API_KEY= -e X402_PRIVATE_KEY=<key> -- npx -y @one-source/mcp@latest`. `1s_setup_check` shows the first 6 characters of whichever key is active so you can confirm which one the server is using.
73
+ **Available tags:**
74
+ - **Releases**: `latest`, `v1.0.0`, `v1.1.0`, etc.
75
+ - **Continuous**: `main` (latest main branch build)
76
+ - **Development**: `main-<date>-<sha>` (specific commit builds)
235
77
 
236
- **Instructions show wrong auth method after reinstall**
237
- `/reload-plugins` in Claude Code reconnects tools but may not refresh the system prompt the LLM sees. If you switch auth method (e.g. API key → x402), do a full Claude Code restart to ensure the instructions reflect the new auth.
78
+ </details>
238
79
 
239
- **"MCP server onesource already exists" error**
240
- Run `claude mcp remove onesource` first, then re-add with your updated config.
80
+ #### Publishing a server
241
81
 
242
- **Windows: `npx` requires `cmd /c` wrapper**
243
- Claude Code's `/doctor` command may warn about this. Update your MCP config to use `"command": "cmd"` with `"args": ["/c", "npx", "-y", "@one-source/mcp@latest"]`.
82
+ To publish a server, we've built a simple CLI. You can use it with:
244
83
 
245
- **`npx` hangs with no output**
246
- That's normal — stdio mode waits for JSON-RPC input on stdin. Use `--http` if you want an HTTP server you can curl.
247
-
248
- **Port already in use**
249
- Specify a different port: `npx -y @one-source/mcp@latest --http --port=8080`
250
-
251
- ## Registry Publishing
252
-
253
- This package is listed on the [official MCP Registry](https://registry.modelcontextprotocol.io) under the verified namespace `io.onesource/mcp` and on [Glama](https://glama.ai/mcp/servers). When releasing a new version, update both registries.
254
-
255
- ### MCP Registry
84
+ ```bash
85
+ # Build the latest CLI
86
+ make publisher
256
87
 
257
- #### First-Time Setup
88
+ # Use it!
89
+ ./bin/mcp-publisher --help
90
+ ```
258
91
 
259
- ##### 1. Install Go
92
+ See [the publisher guide](./docs/modelcontextprotocol-io/quickstart.mdx) for more details.
260
93
 
261
- Download the installer for your platform from [go.dev/dl](https://go.dev/dl/) and run it. Verify:
94
+ #### Other commands
262
95
 
263
96
  ```bash
264
- go version
97
+ # Run lint, unit tests and integration tests
98
+ make check
265
99
  ```
266
100
 
267
- ##### 2. Install mcp-publisher
101
+ There are also a few more helpful commands for development. Run `make help` to learn more, or look in [Makefile](./Makefile).
268
102
 
269
- ```bash
270
- go install github.com/modelcontextprotocol/registry/cmd/mcp-publisher@latest
271
- ```
103
+ <!--
104
+ For Claude and other AI tools: Always prefer make targets over custom commands where possible.
105
+ -->
272
106
 
273
- If the Go module path has changed and the command fails, download the binary directly from the [mcp-publisher GitHub releases](https://github.com/modelcontextprotocol/registry/releases) page instead.
107
+ ## Architecture
274
108
 
275
- On Windows, add Go's bin directory to your PATH if the command isn't recognized:
109
+ ### Project Structure
276
110
 
277
- ```powershell
278
- $env:PATH += ";$env:USERPROFILE\go\bin"
279
111
  ```
280
-
281
- Verify:
282
-
283
- ```bash
284
- mcp-publisher --help
112
+ ├── cmd/ # Application entry points
113
+ │ └── publisher/ # Server publishing tool
114
+ ├── data/ # Seed data
115
+ ├── deploy/ # Deployment configuration (Pulumi)
116
+ ├── docs/ # Documentation
117
+ ├── internal/ # Private application code
118
+ │ ├── api/ # HTTP handlers and routing
119
+ │ ├── auth/ # Authentication (GitHub OAuth, JWT, namespace blocking)
120
+ │ ├── config/ # Configuration management
121
+ │ ├── database/ # Data persistence (PostgreSQL)
122
+ │ ├── service/ # Business logic
123
+ │ ├── telemetry/ # Metrics and monitoring
124
+ │ └── validators/ # Input validation
125
+ ├── pkg/ # Public packages
126
+ │ ├── api/ # API types and structures
127
+ │ │ └── v0/ # Version 0 API types
128
+ │ └── model/ # Data models for server.json
129
+ ├── scripts/ # Development and testing scripts
130
+ ├── tests/ # Integration tests
131
+ └── tools/ # CLI tools and utilities
132
+ └── validate-*.sh # Schema validation tools
285
133
  ```
286
134
 
287
- ##### 3. DNS Authentication (already done)
135
+ ### Authentication
288
136
 
289
- The `onesource.io` domain has a DNS TXT record that proves ownership of the `io.onesource` namespace. This is already configured — you don't need to redo it.
137
+ Publishing supports multiple authentication methods:
138
+ - **GitHub OAuth** - For publishing by logging into GitHub
139
+ - **GitHub OIDC** - For publishing from GitHub Actions
140
+ - **DNS verification** - For proving ownership of a domain and its subdomains
141
+ - **HTTP verification** - For proving ownership of a domain
290
142
 
291
- The record is on the root domain (`onesource.io`, not `_mcp-registry.onesource.io`):
143
+ The registry validates namespace ownership when publishing. E.g. to publish...:
144
+ - `io.github.domdomegg/my-cool-mcp` you must login to GitHub as `domdomegg`, or be in a GitHub Action on domdomegg's repos
145
+ - `me.adamjones/my-cool-mcp` you must prove ownership of `adamjones.me` via DNS or HTTP challenge
292
146
 
293
- ```
294
- v=MCPv1; k=ed25519; p=7D3U5rufgNXb/lH2MthTRZdDzEGeE7/Jvg8YkiArQc8=
295
- ```
147
+ ## Community Projects
296
148
 
297
- You can verify it resolves:
149
+ Check out [community projects](docs/community-projects.md) to explore notable registry-related work created by the community.
298
150
 
299
- ```bash
300
- nslookup -type=TXT onesource.io 8.8.8.8
301
- ```
151
+ ## More documentation
302
152
 
303
- ##### 4. Get the Private Key
304
-
305
- Authentication requires the ed25519 private key in **hex format** that corresponds to the public key in the DNS record. Ask the team lead for this key — it's stored in the team's password manager / vault.
306
-
307
- If you need to regenerate the keypair (this invalidates the current DNS record and requires updating it):
308
-
309
- 1. Generate a new ed25519 keypair (e.g., `openssl genpkey -algorithm Ed25519 -out key.pem`)
310
- 2. Extract the raw 32-byte private key seed and convert to hex:
311
- ```bash
312
- openssl pkey -in key.pem -outform DER | tail -c 32 | xxd -p -c 32
313
- ```
314
- 3. Extract the public key in base64 for the DNS TXT record:
315
- ```bash
316
- openssl pkey -in key.pem -pubout -outform DER | tail -c 32 | base64
317
- ```
318
- 4. Update the DNS TXT record on `onesource.io` with the new public key:
319
- ```
320
- v=MCPv1; k=ed25519; p=<base64-public-key>
321
- ```
322
- 5. Wait for DNS propagation before attempting to log in.
323
-
324
- #### Publishing a New Version
325
-
326
- Every time you release a new npm version, update the MCP Registry:
327
-
328
- 1. **Publish to npm** (the registry validates the package exists, so this must happen first):
329
- ```bash
330
- npm run build
331
- npm publish --access public
332
- ```
333
-
334
- 2. **Update `server.json`** — set both `version` fields to match the new npm version:
335
- ```json
336
- {
337
- "version": "x.y.z",
338
- ...
339
- "packages": [{ "version": "x.y.z", ... }]
340
- }
341
- ```
342
- The `mcpName` field in `package.json` must be `"io.onesource/mcp"` and must match the `name` field in `server.json`. This is already set — don't remove it.
343
-
344
- 3. **Authenticate** (tokens expire, so do this each time):
345
- ```bash
346
- mcp-publisher login dns --domain onesource.io --private-key <ed25519-hex-private-key>
347
- ```
348
-
349
- 4. **Publish to the registry:**
350
- ```bash
351
- mcp-publisher publish
352
- ```
353
-
354
- 5. **Verify:**
355
- ```bash
356
- curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=onesource"
357
- ```
358
-
359
- ### Glama
360
-
361
- Glama auto-syncs from the GitHub repo daily. No manual steps needed after a release — just make sure changes are pushed to `main`. The `glama.json` file in the repo root controls ownership. Manual re-sync is available from the [Glama admin panel](https://glama.ai/mcp/servers) after claiming the server.
362
-
363
- ## License
364
-
365
- Apache 2.0 — see [LICENSE](LICENSE) for details.
153
+ See the [documentation](./docs) for more details if your question has not been answered here!
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.0",
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.0",
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. |