quicknode · 0xsergen · Jul 2, 2026
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
@@ -11,9 +11,9 @@
   },
   "plugins": [
     {
-      "name": "mcp",
-      "description": "Manage your blockchain infrastructure across 80+ chains with your agents.",
-      "source": "./plugins/mcp",
+      "name": "quicknode",
+      "description": "Build on Quicknode blockchain infrastructure: manage endpoints across 80+ chains (MCP), plus commands, a subagent, and a skill for RPC, Solana, Hyperliquid, x402, MPP, and more.",
+      "source": "./plugins/quicknode",
       "strict": false
     }
   ]

diff --git a/.cursor-plugin/marketplace.json b/.cursor-plugin/marketplace.json
@@ -11,8 +11,8 @@
   },
   "plugins": [
     {
-      "name": "mcp",
-      "source": "./plugins/mcp",
+      "name": "quicknode",
+      "source": "./plugins/quicknode",
       "description": "Manage your blockchain infrastructure across 80+ chains with your agents."
     }
   ]

diff --git a/.github/workflows/publish-mcp-registry.yml b/.github/workflows/publish-mcp-registry.yml
@@ -22,12 +22,12 @@ jobs:
       - name: Sync version from tag to server.json
         run: |
           VERSION="${GITHUB_REF#refs/tags/v}"
-          jq --arg v "$VERSION" '.version = $v' plugins/mcp/server.json > plugins/mcp/server.tmp.json
-          mv plugins/mcp/server.tmp.json plugins/mcp/server.json
-          cat plugins/mcp/server.json
+          jq --arg v "$VERSION" '.version = $v' plugins/quicknode/server.json > plugins/quicknode/server.tmp.json
+          mv plugins/quicknode/server.tmp.json plugins/quicknode/server.json
+          cat plugins/quicknode/server.json
 
       - name: Authenticate to MCP Registry via GitHub OIDC
         run: ./mcp-publisher login github-oidc
 
       - name: Publish server to MCP Registry
-        run: ./mcp-publisher publish plugins/mcp/server.json
+        run: ./mcp-publisher publish plugins/quicknode/server.json
diff --git a/.github/workflows/sync-skill.yml b/.github/workflows/sync-skill.yml
@@ -0,0 +1,58 @@
+name: Sync quicknode-skill
+
+on:
+  schedule:
+    - cron: '0 9 * * 1'  # Every Monday 09:00 UTC
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Run sync script
+        id: sync
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set +e
+          bash scripts/sync-skill.sh
+          EXIT=$?
+          set -e
+          if [ $EXIT -eq 1 ]; then
+            echo "drift=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "drift=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Read upstream SHA
+        id: meta
+        if: steps.sync.outputs.drift == 'true'
+        run: |
+          SHA=$(grep "Upstream commit:" plugins/quicknode/skills/quicknode-skill/SKILL_SOURCE.md | awk '{print $NF}')
+          echo "sha=${SHA}" >> "$GITHUB_OUTPUT"
+
+      - name: Open PR on drift
+        if: steps.sync.outputs.drift == 'true'
+        uses: peter-evans/create-pull-request@v6
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          branch: sync/quicknode-skill-${{ steps.meta.outputs.sha }}
+          delete-branch: true
+          commit-message: "sync: update quicknode-skill from blockchain-skills@${{ steps.meta.outputs.sha }}"
+          title: "Sync quicknode-skill from blockchain-skills@${{ steps.meta.outputs.sha }}"
+          body: |
+            Automated sync of `plugins/quicknode/skills/quicknode-skill/` from upstream [`quiknode-labs/blockchain-skills`](https://github.com/quiknode-labs/blockchain-skills).
+
+            **Upstream commit:** `${{ steps.meta.outputs.sha }}`
+
+            Review the diff to confirm no breaking changes before merging.
+          labels: "sync,automated"
+          reviewers: "0xsergen"
diff --git a/README.md b/README.md
@@ -4,9 +4,9 @@ Agent plugins from Quicknode. MCP servers, skills, and more.
 
 ## Available plugins
 
-| Plugin                  | Description                                                                                                                 |
-| ----------------------- | --------------------------------------------------------------------------------------------------------------------------- |
-| [`mcp`](./plugins/mcp/) | Manage your blockchain infrastructure across 80+ chains with your agents. |
+| Plugin                              | Description                                                                                                                                                     |
+| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`quicknode`](./plugins/quicknode/) | Build on Quicknode blockchain infrastructure: manage endpoints across 80+ chains (MCP), plus commands, a subagent, and a skill for RPC, Solana, Hyperliquid, x402, MPP, and more. |
 
 ## Install
 
@@ -17,7 +17,13 @@ Agent plugins from Quicknode. MCP servers, skills, and more.
 | VS Code  | [docs/install/vscode.md](./docs/install/vscode.md)     |
 | Zed      | [docs/install/zed.md](./docs/install/zed.md)           |
 
-For Claude Code and ChatGPT, use the existing listings on the respective marketplaces.
+For Claude Code, add this marketplace and install the `quicknode` plugin:
+
+```
+/plugin marketplace add quicknode/agent-plugins
+```
+
+For ChatGPT, use the existing listing on its marketplace.
 
 ## License
 

diff --git a/docs/install/cursor.md b/docs/install/cursor.md
@@ -31,7 +31,7 @@ No `auth` block needed. The Quicknode MCP server uses OAuth 2.1 with **Dynamic C
 
 ## What you get
 
-Manage your blockchain infrastructure from your AI assistant: endpoints, rate limits, security, metrics, logs, and billing. See the [plugin README](../../plugins/mcp/README.md) for capabilities.
+Manage your blockchain infrastructure from your AI assistant: endpoints, rate limits, security, metrics, logs, and billing. See the [plugin README](../../plugins/quicknode/README.md) for capabilities.
 
 ## Troubleshooting
 

diff --git a/docs/install/vscode.md b/docs/install/vscode.md
@@ -37,7 +37,7 @@ On first connection, VS Code performs OAuth 2.1 + Dynamic Client Registration ag
 
 ## What you get
 
-Manage your blockchain infrastructure from your AI assistant: endpoints, rate limits, security, metrics, logs, and billing. See the [plugin README](../../plugins/mcp/README.md) for capabilities.
+Manage your blockchain infrastructure from your AI assistant: endpoints, rate limits, security, metrics, logs, and billing. See the [plugin README](../../plugins/quicknode/README.md) for capabilities.
 
 ## Requirements
 

diff --git a/docs/install/windsurf.md b/docs/install/windsurf.md
@@ -32,7 +32,7 @@ windsurf://windsurf-mcp-registry?serverName=quicknode-mcp
 
 ## What you get
 
-Manage your blockchain infrastructure from your AI assistant: endpoints, rate limits, security, metrics, logs, and billing. See the [plugin README](../../plugins/mcp/README.md) for capabilities.
+Manage your blockchain infrastructure from your AI assistant: endpoints, rate limits, security, metrics, logs, and billing. See the [plugin README](../../plugins/quicknode/README.md) for capabilities.
 
 ## Requirements
 

diff --git a/docs/install/zed.md b/docs/install/zed.md
@@ -39,7 +39,7 @@ Note: Zed uses `context_servers` (not `mcpServers`).
 
 ## What you get
 
-Manage your blockchain infrastructure from your AI assistant: endpoints, rate limits, security, metrics, logs, and billing. See the [plugin README](../../plugins/mcp/README.md) for capabilities.
+Manage your blockchain infrastructure from your AI assistant: endpoints, rate limits, security, metrics, logs, and billing. See the [plugin README](../../plugins/quicknode/README.md) for capabilities.
 
 ## Requirements
 

diff --git a/plugins/mcp/README.md b/plugins/mcp/README.md
diff --git a/plugins/quicknode/.claude-plugin/plugin.json b/plugins/quicknode/.claude-plugin/plugin.json
@@ -0,0 +1,12 @@
+{
+  "name": "quicknode",
+  "description": "Build on Quicknode blockchain infrastructure from your AI coding agent. Manage endpoints, streams, webhooks, and 80+ chains — plus accurate API knowledge for RPC, Solana, Hyperliquid, x402, MPP, and more.",
+  "version": "1.0.0",
+  "author": {
+    "name": "Quicknode",
+    "url": "https://www.quicknode.com"
+  },
+  "homepage": "https://www.quicknode.com/docs/build-with-ai",
+  "repository": "https://github.com/quicknode/agent-plugins",
+  "license": "MIT"
+}
diff --git a/plugins/mcp/.cursor-plugin/plugin.json → plugins/quicknode/.cursor-plugin/plugin.json b/plugins/mcp/.cursor-plugin/plugin.json → plugins/quicknode/.cursor-plugin/plugin.json
@@ -1,5 +1,5 @@
 {
-  "name": "mcp",
+  "name": "quicknode",
   "displayName": "Quicknode MCP",
   "version": "1.0.0",
   "description": "Manage your blockchain infrastructure across 80+ chains with your agents.",

diff --git a/plugins/quicknode/README.md b/plugins/quicknode/README.md
@@ -0,0 +1,73 @@
+# Quicknode
+
+Build on Quicknode blockchain infrastructure from your AI agent.
+
+In **Claude Code**, this plugin bundles the Quicknode MCP server, outcome-focused slash commands, an RPC troubleshooting subagent, and a continuously-synced blockchain skill. In other clients (Cursor, Windsurf, VS Code, Zed), it provides the remote MCP server.
+
+## MCP server
+
+- **Endpoint**: `https://mcp.quicknode.com/mcp`
+- **Transport**: Streamable HTTP (stateless)
+- **Auth**: OAuth 2.1 with Dynamic Client Registration (RFC 7591). Clients register themselves automatically; no API key in your config.
+
+Manage your blockchain infrastructure: list, inspect, provision, and archive endpoints across supported chains; adjust rate limits; manage security options and rules; fetch metrics, logs, and usage; and query billing and supported chains.
+
+## Slash commands (Claude Code)
+
+Outcome-focused commands that route you to the right Quicknode product. Namespaced as `/quicknode:<name>`.
+
+| Command                 | What it does                                                                               |
+| ----------------------- | ------------------------------------------------------------------------------------------ |
+| `/quicknode:build-web3`   | Scaffold a working Web3 starter app wired to the right Quicknode product for your use case. |
+| `/quicknode:new-endpoint` | Provision a Quicknode RPC endpoint (chain/network/name) via MCP.                            |
+| `/quicknode:monitor`      | Set up real-time on-chain event monitoring — picks Webhooks vs Streams for your needs.      |
+| `/quicknode:backfill`     | Configure a Streams Dataset job to retrieve historical blockchain data over a range.        |
+| `/quicknode:query-data`   | Write and run SQL against Quicknode SQL Explorer.                                            |
+| `/quicknode:swap`         | Get a quote or execute a token swap on Solana or EVM via the Swap API.                       |
+| `/quicknode:agent-access` | Add wallet-paid blockchain access to an AI agent via x402 or MPP.                            |
+
+## Subagent (Claude Code)
+
+- **rpc-troubleshooter** — a Quicknode RPC diagnostics specialist. Triggers on RPC errors (reverts, 429s, timeouts, missing methods, chain mismatches, archive/trie-node errors) and returns a root-cause diagnosis, a corrected snippet, and any relevant add-on/plan recommendation.
+
+## Skill (Claude Code)
+
+- **quicknode-skill** — accurate API knowledge across 80+ chains: RPC, Streams, Webhooks, SQL Explorer, IPFS, Solana DAS, Yellowstone gRPC, HyperCore, KV Store, Admin API, x402, MPP, and Agent Subscriptions. Synced automatically from [`quiknode-labs/blockchain-skills`](https://github.com/quiknode-labs/blockchain-skills) via a weekly GitHub workflow, so its API details stay current.
+
+## Install
+
+**Claude Code** — add the marketplace, then install the `quicknode` plugin:
+
+```
+/plugin marketplace add quicknode/agent-plugins
+```
+
+**Other clients** — see the per-client guides at the repo root:
+
+- [Cursor](../../docs/install/cursor.md)
+- [Windsurf](../../docs/install/windsurf.md)
+- [VS Code](../../docs/install/vscode.md)
+- [Zed](../../docs/install/zed.md)
+
+Manual MCP config (works for any client supporting remote MCP):
+
+```json
+{
+  "mcpServers": {
+    "quicknode": {
+      "type": "http",
+      "url": "https://mcp.quicknode.com/mcp"
+    }
+  }
+}
+```
+
+On first connection, the client performs DCR against `https://mcp.quicknode.com/register`, then walks you through OAuth in your browser. No pre-shared `CLIENT_ID` / `CLIENT_SECRET` needed.
+
+## Requirements
+
+A Quicknode account. Sign up at [quicknode.com](https://www.quicknode.com).
+
+## License
+
+MIT. See [LICENSE.md](../../LICENSE.md) at the repo root.
diff --git a/plugins/quicknode/agents/rpc-troubleshooter.md b/plugins/quicknode/agents/rpc-troubleshooter.md
@@ -0,0 +1,48 @@
+---
+description: Diagnose Quicknode RPC errors — reverts, timeouts, rate limits, wrong network, missing methods. Triggers on phrases like "RPC error", "eth_call reverted", "429 from Quicknode", "JSON-RPC timeout", "execution reverted", "missing trie node", "wrong chainId".
+tools: Read, Grep, WebFetch
+---
+
+You are a Quicknode RPC diagnostics specialist. Your only job is to diagnose RPC errors and suggest a concrete fix or the right Quicknode add-on.
+
+## Step 1 — Gather the error
+
+Ask the user (or extract from context) for:
+
+1. The **exact error message** (copy-paste the full JSON-RPC error or HTTP response)
+2. The **method** that failed (e.g. `eth_call`, `trace_transaction`, `eth_getLogs`)
+3. The **chain and network** (Ethereum mainnet? Base? Solana?)
+4. The **endpoint URL** (redact the key — just the host is enough)
+5. The **request payload** if available (contract address, block number, params)
+
+## Step 2 — Diagnose
+
+Cross-reference `skills/quicknode-skill/references/rpc-reference.md` and `skills/quicknode-skill/references/marketplace-addons.md`.
+
+Map the error to one of these root causes:
+
+| Symptom | Root cause | Fix |
+|---------|-----------|-----|
+| `execution reverted` / `revert` in data | Contract-level revert — not an RPC issue | Decode revert reason; check contract state, params, msg.sender |
+| `429 Too Many Requests` | Rate limit exceeded | Check endpoint rate limit in dashboard; upgrade plan or add rate limit exception |
+| `method not found` / `-32601` | Method not enabled on the endpoint | Enable the method in endpoint settings or add the relevant add-on |
+| `timeout` / no response | Network or compute timeout | Check if the request is too compute-heavy (large `eth_getLogs` range); add block range limit |
+| `wrong chainId` / chain mismatch | Endpoint URL points to wrong chain | Verify endpoint chain/network in dashboard |
+| `missing trie node` / `state not available` | Archive data requested on non-archive endpoint | Switch to an archive endpoint or add Archive add-on |
+| `invalid JSON` / `-32700` | Malformed request payload | Show corrected request format |
+| `ECONNREFUSED` / `ENOTFOUND` | Endpoint URL wrong or service down | Verify URL; check status.quicknode.com |
+
+## Step 3 — Recommend
+
+Based on the diagnosis:
+
+1. **Immediate fix** — What the user can change right now (request params, block range, endpoint setting)
+2. **Add-on or plan upgrade** (if needed) — Reference `marketplace-addons.md` for the exact add-on name and what it enables
+3. **Code fix** (if applicable) — Show the corrected request snippet
+
+## Rules
+
+- Never guess the root cause without evidence from the error message
+- If the error is a contract revert, say so clearly — it is not a Quicknode issue
+- Only suggest add-ons that exist in `marketplace-addons.md` — do not invent product names
+- Keep the diagnosis to 3 sections: what happened, why, and how to fix it
diff --git a/plugins/quicknode/commands/agent-access.md b/plugins/quicknode/commands/agent-access.md
@@ -0,0 +1,37 @@
+---
+description: Add wallet-paid blockchain access to an AI agent — no API keys, pay with stablecoins via x402 or MPP. Optionally provision a full Quicknode account via Agent Subscriptions.
+argument-hint: "[x402|mpp] [one-shot|full-account]"
+---
+
+You are a Quicknode agentic payments expert. Help the user add wallet-paid blockchain access to an AI agent using x402 or MPP.
+
+Read `skills/quicknode-skill/references/x402-reference.md` and `skills/quicknode-skill/references/mpp-reference.md` for accurate protocol details, pricing, endpoint URLs, SDK names, and header formats before responding. Do not use any values from memory — always derive them from the reference files.
+
+## Step 1 — Pick the access mode
+
+Ask if not clear from context:
+
+- **One-shot RPC** — Agent pays per request directly via the protocol proxy. No Quicknode account needed.
+- **Full platform account** — Agent uses the same protocols against Agent Subscriptions to provision a full Quicknode API key, unlocking RPC, Streams, Webhooks, SQL Explorer, Key-Value Store, and Admin API.
+
+## Step 2 — Pick the protocol
+
+From the reference files, summarize the key tradeoffs between x402 and MPP (billing model, session support, SDK availability) in a compact table, then ask the user which fits their use case — or recommend one based on their context.
+
+## Step 3 — Setup walkthrough
+
+Once the user has chosen protocol + access mode:
+
+1. Show the correct base URL for the chosen protocol (from the reference)
+2. Show the install command for the official SDK
+3. Produce a working TypeScript snippet that handles the full payment flow — auth, headers, and error handling — using the SDK (no manual header construction)
+4. Provide a `.env.example` with the required env vars (no values, just keys)
+
+If the user chose **full platform account**: show the Agent Subscriptions flow — use the chosen protocol to provision a `QN_*` API key, then use it like a normal Quicknode account.
+
+## Rules
+
+- All pricing, URLs, and header formats must come from the reference files — never from memory
+- Always use environment variables for private keys — never hard-code
+- If the user is building on Solana, check the reference for the Solana-specific SDK variant
+- Do not invent header formats — use only what the reference files document