@magpieloans/magpie-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Magpie Capital
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,173 @@
+# magpie-mcp
+
+**MCP server exposing the Magpie Capital x402 API as native tools for Claude Desktop, Cursor, Windsurf, ChatGPT desktop, and any other MCP-aware agent host.**
+
+Drop one config block into your host and your agent can query Magpie's protocol state, simulate borrows, fetch credit scores, build deposit/withdraw transactions, and post conditional borrow intents — all as first-class tool calls. No bespoke client code, no API keys.
+
+## What it exposes
+
+19 tools wrapping the x402 endpoints:
+
+**Free reads (work out of the box):**
+- `magpie_pool_state` — live LendingPool account
+- `magpie_protocol_pulse` — 24h aggregates (active loans, volume, liquidations)
+- `magpie_recent_activity` — anonymized borrow/repay/liquidate stream
+- `magpie_loan` — single loan by ID
+- `magpie_wallet_loans` — all loans for a wallet
+- `magpie_tiers` — protocol tier constants
+- `magpie_simulate_borrow` — quote a loan without submitting
+- `magpie_collateral_eligible` — full collateral catalog
+- `magpie_liquidatable` — loans currently liquidatable
+- `magpie_credit_leaderboard` — top wallets by credit score
+- `magpie_lp_state` — depositor position + pool context
+
+**Paid (require a configured Solana keypair):**
+- `magpie_credit_score` — 0.001 SOL
+- `magpie_token_risk` — 0.001 SOL (per-token risk profile)
+- `magpie_build_borrow` — 0.005 SOL
+- `magpie_build_repay` — 0.002 SOL
+- `magpie_build_deposit` — 0.002 SOL
+- `magpie_build_withdraw` — 0.002 SOL
+- `magpie_build_liquidate` — 0.003 SOL (liquidate a past-due loan, receive keeper bounty)
+- `magpie_create_intent` — 0.01 SOL (conditional borrow)
+- `magpie_get_intent` — 0.0005 SOL (poll)
+
+When a paid tool fires, the server signs an x402 payment tx locally with your configured keypair and forwards the signature to magpie-x402. The keypair never leaves your machine.
+
+## Install
+
+Two paths. Both end at the same place.
+
+### Path A — npm (recommended once published)
+
+No clone, no build, no absolute paths in your host config:
+
+```bash
+# Verify it runs once before wiring into your host:
+npx -y @magpieloans/magpie-mcp --help
+```
+
+Then in your host config:
+
+```json
+{
+  "mcpServers": {
+    "magpie": {
+      "command": "npx",
+      "args": ["-y", "@magpieloans/magpie-mcp"],
+      "env": {
+        "SOLANA_RPC_URL": "https://api.mainnet-beta.solana.com",
+        "MAGPIE_MCP_PAYER_KEYPAIR": "/path/to/payer-id.json"
+      }
+    }
+  }
+}
+```
+
+### Path B — from source
+
+If the npm package isn't published yet, or you want to hack on the server:
+
+```bash
+git clone git@github.com:magpiecapital/magpie-x402.git
+cd magpie-x402/mcp
+npm install
+npm run build
+```
+
+Built executable lands at `mcp/dist/index.js`. Use the absolute path in your host config below.
+
+## Configure your host
+
+Pick the snippet for your host. The `command` + `args` shape changes between npm-install vs source-build; the `env` block is identical.
+
+### Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "magpie": {
+      "command": "node",
+      "args": ["/ABS/PATH/TO/magpie-x402/mcp/dist/index.js"],
+      "env": {
+        "SOLANA_RPC_URL": "https://api.mainnet-beta.solana.com",
+        "MAGPIE_MCP_PAYER_KEYPAIR": "/ABS/PATH/TO/payer-id.json"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop. The Magpie tools appear in the tool picker.
+
+### Cursor
+
+Edit `~/.cursor/mcp.json`. Same shape as Claude Desktop above.
+
+### Windsurf
+
+Edit `~/.codeium/windsurf/mcp_config.json`. Same shape.
+
+### ChatGPT desktop / any other MCP-aware host
+
+Use the same shape — point the host at `node /ABS/PATH/.../mcp/dist/index.js`, pass env vars through the host's MCP config interface.
+
+## Free-only mode (no keypair)
+
+Omit `MAGPIE_MCP_PAYER_KEYPAIR` and all 11 free tools still work. Paid tools return a clear error explaining that no payer is configured. Useful for read-only research agents or as a no-friction first install.
+
+## Environment variables
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `MAGPIE_X402_BASE_URL` | `https://x402.magpie.capital` | Override for self-hosted or testnet deployments |
+| `SOLANA_RPC_URL` | `https://api.mainnet-beta.solana.com` | RPC used to send x402 payment txs. Public RPC rate-limits aggressively — use Helius/Triton/QuickNode for any real volume. |
+| `MAGPIE_MCP_PAYER_KEYPAIR` | _(unset)_ | Path to a Solana keypair JSON in the standard `solana-keygen` format. Enables paid tools. |
+
+## Cost ceiling
+
+The keypair you configure is the only place SOL can leave. Per-call costs are exact (the server doesn't ever pay more than the 402 challenge demands), but if you're paranoid about runaway tool-calls during agent experimentation, fund the payer wallet with a small float — say 0.05 SOL — and let it run dry rather than top it up unattended.
+
+## Security model
+
+- The MCP server reads but never modifies your keypair file. The keypair is loaded into memory once at startup; the signature for each paid call happens locally; only the resulting tx signature ever leaves your machine (sent to magpie-x402 in the `X-Payment` header).
+- The Magpie x402 service has no way to sign anything on your behalf. Even with a complete compromise of x402.magpie.capital, the worst case is that you pay for tool calls you didn't get useful results from. Your keypair is not exposed.
+- For high-stakes write paths (`build-borrow`, `build-deposit`, etc.) the server returns an *unsigned* tx. Your agent receives it as plain text; you decide whether to sign + submit it. The MCP server itself never signs anything besides x402 payment transfers.
+
+## Troubleshooting
+
+**Tool doesn't appear in host UI** — restart the host after editing config. Most hosts only re-read the MCP config on launch.
+
+**402 error on a paid tool** — `MAGPIE_MCP_PAYER_KEYPAIR` is unset or the file doesn't exist. Run `solana-keygen new -o ~/.config/solana/magpie-mcp.json` and point the env var at the result, then `solana transfer …` a small SOL float in.
+
+**`fetch failed` on x402.magpie.capital** — check the URL is reachable from your machine. If you're behind a corporate proxy, set `HTTPS_PROXY` in the same `env` block.
+
+**RPC rate-limit during a paid call** — switch `SOLANA_RPC_URL` to a paid Helius/Triton/QuickNode URL. The default `api.mainnet-beta.solana.com` will throttle under any sustained use.
+
+## For maintainers — publishing to npm
+
+The package is set up for `npm publish` with no additional configuration. From `mcp/`:
+
+```bash
+# One-time per machine:
+npm login --scope=@magpieloans
+
+# Each release:
+# 1. Bump version in package.json (semver)
+# 2. Publish — prepublishOnly rebuilds dist/ and chmod +x's the binary
+npm publish
+```
+
+The package is scoped (`@magpieloans/magpie-mcp`) and `publishConfig.access: "public"` is set, so publish doesn't require any extra flags. The `files` field whitelists what ships — only `dist/`, `README.md`, `LICENSE` end up in the tarball (~9 KB).
+
+Verify the contents before publish:
+
+```bash
+npm pack --dry-run
+```
+
+## License
+
+MIT.

package/dist/index.js

@@ -0,0 +1,407 @@
+#!/usr/bin/env node
+/**
+ * Magpie MCP server — exposes the magpie-x402 API as native MCP tools
+ * for Claude Desktop, Cursor, Windsurf, ChatGPT desktop, and any other
+ * MCP-aware agent host.
+ *
+ * Transport: stdio (the standard for desktop hosts).
+ *
+ * Free tools work out of the box. Paid tools require a configured
+ * Solana keypair (env var) that's funded with a small SOL balance for
+ * the per-call payments. The server signs payment txs locally; nothing
+ * is sent to magpie-x402 except the public X-Payment header.
+ *
+ * Env vars:
+ *   MAGPIE_X402_BASE_URL    default https://x402.magpie.capital
+ *   SOLANA_RPC_URL          default https://api.mainnet-beta.solana.com
+ *   MAGPIE_MCP_PAYER_KEYPAIR  path to a Solana keypair JSON (~/.config/solana/id.json format)
+ *
+ * Run from this directory:
+ *   npm install && npm run build && node dist/index.js
+ *
+ * Or via tsx without build step:
+ *   npx tsx src/index.ts
+ *
+ * Wire into Claude Desktop / Cursor / Windsurf via their `mcpServers`
+ * config — see ../README.md in this directory for snippets.
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { call, loadKeypairFromEnv } from "./x402-client.js";
+const baseUrl = process.env.MAGPIE_X402_BASE_URL ?? "https://x402.magpie.capital";
+const rpcUrl = process.env.SOLANA_RPC_URL ?? "https://api.mainnet-beta.solana.com";
+const payer = loadKeypairFromEnv();
+const ctx = { baseUrl, rpcUrl, payer };
+// Schema-only tool registry. Each entry maps to a thin handler below
+// that turns the args into a magpie-x402 HTTP call. Keeping the tool
+// list in one declarative block makes ListTools cheap + always in sync
+// with CallTool dispatch.
+const TOOLS = [
+    // ── Free reads ──────────────────────────────────────────────────
+    {
+        name: "magpie_pool_state",
+        description: "Get live on-chain Magpie LendingPool state — totalDeposits, totalBorrowed, totalShares, utilization, fees earned. Free, 15s cache.",
+        inputSchema: { type: "object", properties: {} },
+    },
+    {
+        name: "magpie_protocol_pulse",
+        description: "24h protocol aggregates: active loans, active borrowers, borrows in last 1h + 24h, borrow volume in SOL, repays, liquidations. Pure aggregates, no per-wallet data. Free, 30s cache.",
+        inputSchema: { type: "object", properties: {} },
+    },
+    {
+        name: "magpie_recent_activity",
+        description: "Anonymized recent borrow/repay/liquidate events across the protocol. Wallets reduced to Xxxx…Yyyy. Useful as 'is this protocol active right now' signal. Free, 15s cache.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                limit: {
+                    type: "integer",
+                    minimum: 1,
+                    maximum: 200,
+                    default: 50,
+                },
+            },
+        },
+    },
+    {
+        name: "magpie_loan",
+        description: "Fetch a single Magpie loan by its u64 ID. Free.",
+        inputSchema: {
+            type: "object",
+            properties: { loan_id: { type: "string", pattern: "^[0-9]+$" } },
+            required: ["loan_id"],
+        },
+    },
+    {
+        name: "magpie_wallet_loans",
+        description: "All loans owned by a wallet. Optional ?status filter. Free, 8s cache.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                wallet: { type: "string" },
+                status: { type: "string", enum: ["active", "repaid", "liquidated"] },
+            },
+            required: ["wallet"],
+        },
+    },
+    {
+        name: "magpie_tiers",
+        description: "Magpie loan tier constants — three fixed tiers (Express / Quick / Standard) with their LTV, duration, and fee parameters. Free, 1h cache.",
+        inputSchema: { type: "object", properties: {} },
+    },
+    {
+        name: "magpie_simulate_borrow",
+        description: "Preview a loan WITHOUT submitting. Pure math from caller-supplied prices + the public tier constants. Use tier='all' to compare all three tiers. Free.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                mint: { type: "string" },
+                amount: { type: "string", pattern: "^[0-9]+$" },
+                decimals: { type: "string", pattern: "^[0-9]{1,2}$" },
+                pricePerTokenUsd: { type: "string" },
+                solPriceUsd: { type: "string" },
+                tier: {
+                    type: "string",
+                    enum: ["express", "quick", "standard", "all"],
+                    default: "all",
+                },
+            },
+            required: ["mint", "amount", "decimals", "pricePerTokenUsd", "solPriceUsd"],
+        },
+    },
+    {
+        name: "magpie_collateral_eligible",
+        description: "Catalog of every token currently approved as Magpie collateral. Mint, symbol, decimals, category. First-touch endpoint for new agent integrations. Free, 1h cache.",
+        inputSchema: { type: "object", properties: {} },
+    },
+    {
+        name: "magpie_liquidatable",
+        description: "Active loans at or past their on-chain due timestamp — the canonical liquidation-bot data feed. Sorted most-past-due-first. Use within_seconds for pre-positioning. Free, 8s cache.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                within_seconds: { type: "integer", minimum: 0, maximum: 604800 },
+                limit: { type: "integer", minimum: 1, maximum: 500 },
+            },
+        },
+    },
+    {
+        name: "magpie_credit_leaderboard",
+        description: "Top wallets ranked by Magpie credit score (anonymized to Xxxx…Yyyy). Free, 60s cache.",
+        inputSchema: { type: "object", properties: {} },
+    },
+    {
+        name: "magpie_lp_state",
+        description: "Read a wallet's LP position in the main LendingPool — shares, deposited lamports, current value, yield earned, share-of-pool, plus pool context. Free, 10s cache.",
+        inputSchema: {
+            type: "object",
+            properties: { wallet: { type: "string" } },
+            required: ["wallet"],
+        },
+    },
+    // ── Paid endpoints ──────────────────────────────────────────────
+    {
+        name: "magpie_credit_score",
+        description: "Magpie credit score (300-850) + tier benefits for a wallet. Paid: 0.001 SOL per lookup.",
+        inputSchema: {
+            type: "object",
+            properties: { wallet: { type: "string" } },
+            required: ["wallet"],
+        },
+    },
+    {
+        name: "magpie_token_risk",
+        description: "Per-token risk profile from Magpie's internal risk engine — risk score (0-100), dimension breakdown (volatility, liquidity, concentration, volume, rug_pull), market data, max allowed LTV the program will enforce, operator flags. Useful pre-borrow collateral check. Paid: 0.001 SOL per lookup.",
+        inputSchema: {
+            type: "object",
+            properties: { mint: { type: "string" } },
+            required: ["mint"],
+        },
+    },
+    {
+        name: "magpie_build_borrow",
+        description: "Build an UNSIGNED borrow transaction. Server runs the full anti-exploit gate eval (ban registry, TWAP, pool floor, cross-source price, RWA-only guard, etc.) and returns a partial-signed tx. Agent signs locally and submits to magpie.capital/api/v1/cosign-borrow. Paid: 0.005 SOL.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                borrower_wallet: { type: "string" },
+                collateral_mint: { type: "string" },
+                collateral_amount: { type: "string", pattern: "^[0-9]+$" },
+                tier: { type: "integer", enum: [0, 1, 2] },
+            },
+            required: ["borrower_wallet", "collateral_mint", "collateral_amount", "tier"],
+        },
+    },
+    {
+        name: "magpie_build_repay",
+        description: "Build an unsigned repay tx for an existing loan. Paid: 0.002 SOL.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                borrower_wallet: { type: "string" },
+                loan_id: { type: "string", pattern: "^[0-9]+$" },
+            },
+            required: ["borrower_wallet", "loan_id"],
+        },
+    },
+    {
+        name: "magpie_build_deposit",
+        description: "Build an UNSIGNED LP-deposit transaction (wraps SOL → wSOL → deposits into the main LendingPool → closes wSOL ATA). Agent signs and submits. Paid: 0.002 SOL.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                depositor: { type: "string" },
+                lamports: { type: "string", pattern: "^[0-9]+$" },
+            },
+            required: ["depositor", "lamports"],
+        },
+    },
+    {
+        name: "magpie_build_withdraw",
+        description: "Build an unsigned LP-withdraw tx for the requested shares. Server pre-validates the on-chain position and refuses chunks larger than max_safe_shares. Paid: 0.002 SOL.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                depositor: { type: "string" },
+                shares: { type: "string", pattern: "^[0-9]+$" },
+            },
+            required: ["depositor", "shares"],
+        },
+    },
+    {
+        name: "magpie_build_liquidate",
+        description: "Build an unsigned liquidate-loan tx for a past-due active loan. The keeper (your wallet) receives keeper_reward_bps share of the seized collateral as bounty; the rest goes to the lender authority for pool recovery. Permissionless — any wallet can liquidate. Server pre-validates the loan exists, is active, and is past due. Paid: 0.003 SOL. Workflow: poll magpie_liquidatable to find candidates, then call this on the loan_pda.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                keeper: { type: "string" },
+                loan_pda: { type: "string" },
+            },
+            required: ["keeper", "loan_pda"],
+        },
+    },
+    {
+        name: "magpie_create_intent",
+        description: "Post a CONDITIONAL borrow intent. Bot watches the trigger condition (price_above / price_below / time_after / pool_liq_above) and builds the unsigned tx when matched. Single payment covers entire intent lifecycle. Paid: 0.01 SOL. Optional webhook_url — server POSTs an HMAC-SHA256-signed payload on match instead of forcing you to poll. The webhook_secret is returned ONCE in the response; persist it to verify signatures on receive.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                borrower_wallet: { type: "string" },
+                collateral_mint: { type: "string" },
+                collateral_amount: { type: "string" },
+                tier: { type: "integer", enum: [0, 1, 2] },
+                condition_type: {
+                    type: "string",
+                    enum: ["price_above", "price_below", "time_after", "pool_liq_above"],
+                },
+                condition_params: { type: "object" },
+                expires_in_seconds: { type: "integer", minimum: 60, maximum: 2592000 },
+                webhook_url: {
+                    type: "string",
+                    format: "uri",
+                    description: "Optional HTTPS endpoint to receive the match notification. Must be HTTPS; private IPs blocked.",
+                },
+            },
+            required: [
+                "borrower_wallet",
+                "collateral_mint",
+                "collateral_amount",
+                "tier",
+                "condition_type",
+                "condition_params",
+            ],
+        },
+    },
+    {
+        name: "magpie_get_intent",
+        description: "Poll the status of a conditional borrow intent. When status='matched', the response includes partial_signed_tx_b64 ready to sign + submit. Paid: 0.0005 SOL per poll.",
+        inputSchema: {
+            type: "object",
+            properties: { id: { type: "string" } },
+            required: ["id"],
+        },
+    },
+];
+// ── Server wiring ─────────────────────────────────────────────────
+const server = new Server({
+    name: "magpie-mcp",
+    version: "0.1.0",
+}, {
+    capabilities: { tools: {} },
+});
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: TOOLS,
+}));
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+    const { name, arguments: args = {} } = req.params;
+    const a = args;
+    try {
+        let result;
+        switch (name) {
+            case "magpie_pool_state":
+                result = await call(ctx, "GET", "/api/v1/pool");
+                break;
+            case "magpie_protocol_pulse":
+                result = await call(ctx, "GET", "/api/v1/agent/protocol-pulse");
+                break;
+            case "magpie_recent_activity":
+                result = await call(ctx, "GET", "/api/v1/agent/activity", {
+                    query: a.limit !== undefined ? { limit: String(a.limit) } : {},
+                });
+                break;
+            case "magpie_loan":
+                result = await call(ctx, "GET", `/api/v1/loan/${encodeURIComponent(String(a.loan_id))}`);
+                break;
+            case "magpie_wallet_loans": {
+                const q = {};
+                if (a.status)
+                    q.status = String(a.status);
+                result = await call(ctx, "GET", `/api/v1/wallet/${encodeURIComponent(String(a.wallet))}/loans`, { query: q });
+                break;
+            }
+            case "magpie_tiers":
+                result = await call(ctx, "GET", "/api/v1/tiers");
+                break;
+            case "magpie_simulate_borrow": {
+                const q = {
+                    mint: String(a.mint),
+                    amount: String(a.amount),
+                    decimals: String(a.decimals),
+                    pricePerTokenUsd: String(a.pricePerTokenUsd),
+                    solPriceUsd: String(a.solPriceUsd),
+                };
+                if (a.tier)
+                    q.tier = String(a.tier);
+                result = await call(ctx, "GET", "/api/v1/simulate-borrow", { query: q });
+                break;
+            }
+            case "magpie_collateral_eligible":
+                result = await call(ctx, "GET", "/api/v1/collateral/eligible");
+                break;
+            case "magpie_liquidatable": {
+                const q = {};
+                if (a.within_seconds !== undefined)
+                    q.within_seconds = String(a.within_seconds);
+                if (a.limit !== undefined)
+                    q.limit = String(a.limit);
+                result = await call(ctx, "GET", "/api/v1/markets/liquidatable", { query: q });
+                break;
+            }
+            case "magpie_credit_leaderboard":
+                result = await call(ctx, "GET", "/api/v1/agent/leaderboard");
+                break;
+            case "magpie_lp_state":
+                result = await call(ctx, "GET", "/api/v1/agent/lp-state", {
+                    query: { wallet: String(a.wallet) },
+                });
+                break;
+            case "magpie_credit_score":
+                result = await call(ctx, "GET", "/api/v1/credit-score", {
+                    query: { wallet: String(a.wallet) },
+                });
+                break;
+            case "magpie_token_risk":
+                result = await call(ctx, "GET", "/api/v1/agent/token-risk", {
+                    query: { mint: String(a.mint) },
+                });
+                break;
+            case "magpie_build_borrow":
+                result = await call(ctx, "POST", "/api/v1/agent/build-borrow", { body: a });
+                break;
+            case "magpie_build_repay":
+                result = await call(ctx, "POST", "/api/v1/agent/build-repay", { body: a });
+                break;
+            case "magpie_build_deposit":
+                result = await call(ctx, "POST", "/api/v1/agent/build-deposit", { body: a });
+                break;
+            case "magpie_build_withdraw":
+                result = await call(ctx, "POST", "/api/v1/agent/build-withdraw", { body: a });
+                break;
+            case "magpie_build_liquidate":
+                result = await call(ctx, "POST", "/api/v1/agent/build-liquidate", { body: a });
+                break;
+            case "magpie_create_intent":
+                result = await call(ctx, "POST", "/api/v1/agent/intent", { body: a });
+                break;
+            case "magpie_get_intent":
+                result = await call(ctx, "GET", "/api/v1/agent/intent", {
+                    query: { id: String(a.id) },
+                });
+                break;
+            default:
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: `unknown tool: ${name}` }],
+                };
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({ data: result.data, paid: result.paid }, null, 2),
+                },
+            ],
+        };
+    }
+    catch (err) {
+        return {
+            isError: true,
+            content: [
+                {
+                    type: "text",
+                    text: `error calling ${name}: ${err.message}`,
+                },
+            ],
+        };
+    }
+});
+const transport = new StdioServerTransport();
+await server.connect(transport);
+// MCP servers communicate over stdio so anything written to stdout
+// gets parsed as protocol JSON. Use stderr for any human-readable
+// startup logs.
+const payerNote = payer
+    ? `paid endpoints enabled — payer: ${payer.publicKey.toBase58()}`
+    : "free endpoints only — set MAGPIE_MCP_PAYER_KEYPAIR to enable paid tools";
+process.stderr.write(`magpie-mcp ready (${baseUrl}) — ${payerNote}\n`);

package/dist/x402-client.js

@@ -0,0 +1,77 @@
+/**
+ * Minimal x402 client for the MCP server. Same logic as the
+ * examples/lib/x402-client.ts but typed for the MCP context (no
+ * keypair-loading helpers; the MCP server loads its keypair once
+ * at startup from env vars).
+ */
+import { Connection, Keypair, PublicKey, SystemProgram, Transaction, TransactionInstruction, sendAndConfirmTransaction, } from "@solana/web3.js";
+const MEMO_PROGRAM_ID = new PublicKey("MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr");
+export async function call(ctx, method, path, init = {}) {
+    const url = new URL(path, ctx.baseUrl);
+    for (const [k, v] of Object.entries(init.query ?? {})) {
+        url.searchParams.set(k, v);
+    }
+    const headers = { Accept: "application/json" };
+    if (init.body !== undefined)
+        headers["Content-Type"] = "application/json";
+    const first = await fetch(url, {
+        method,
+        headers,
+        body: init.body !== undefined ? JSON.stringify(init.body) : undefined,
+    });
+    if (first.status !== 402) {
+        const data = (await first.json());
+        if (!first.ok) {
+            throw new Error(`magpie ${first.status} ${path}: ${JSON.stringify(data)}`);
+        }
+        return { data, paid: null };
+    }
+    if (!ctx.payer) {
+        throw new Error(`${path} is a paid endpoint (402) but no payer keypair was configured. Set MAGPIE_MCP_PAYER_KEYPAIR.`);
+    }
+    const payTo = first.headers.get("X-Payment-Required-Recipient");
+    const amountStr = first.headers.get("X-Payment-Required-Amount");
+    const nonce = first.headers.get("X-Payment-Required-Nonce");
+    const memo = first.headers.get("X-Payment-Required-Memo");
+    if (!payTo || !amountStr || !nonce || !memo) {
+        throw new Error(`${path} 402 missing required headers`);
+    }
+    const connection = new Connection(ctx.rpcUrl, "confirmed");
+    const tx = new Transaction();
+    tx.add(SystemProgram.transfer({
+        fromPubkey: ctx.payer.publicKey,
+        toPubkey: new PublicKey(payTo),
+        lamports: BigInt(amountStr),
+    }));
+    tx.add(new TransactionInstruction({
+        keys: [],
+        programId: MEMO_PROGRAM_ID,
+        data: Buffer.from(memo, "utf8"),
+    }));
+    const signature = await sendAndConfirmTransaction(connection, tx, [ctx.payer], { commitment: "confirmed" });
+    const retry = await fetch(url, {
+        method,
+        headers: { ...headers, "X-Payment": signature },
+        body: init.body !== undefined ? JSON.stringify(init.body) : undefined,
+    });
+    const data = (await retry.json());
+    if (!retry.ok) {
+        throw new Error(`magpie retry ${retry.status} ${path}: ${JSON.stringify(data)}`);
+    }
+    return {
+        data,
+        paid: { amountLamports: amountStr, txSignature: signature, nonce },
+    };
+}
+export function loadKeypairFromEnv() {
+    // Two supported forms:
+    //   MAGPIE_MCP_PAYER_KEYPAIR=/abs/path/to/id.json (Solana CLI format)
+    //   MAGPIE_MCP_PAYER_SECRET=base58_encoded_secret_key
+    const path = process.env.MAGPIE_MCP_PAYER_KEYPAIR;
+    if (path) {
+        const fs = require("node:fs");
+        const raw = JSON.parse(fs.readFileSync(path.replace(/^~/, process.env.HOME || ""), "utf8"));
+        return Keypair.fromSecretKey(new Uint8Array(raw));
+    }
+    return undefined;
+}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@magpieloans/magpie-mcp",
+  "version": "0.1.0",
+  "description": "MCP server exposing Magpie Capital's x402 API as native tools for Claude Desktop, Cursor, Windsurf, ChatGPT desktop, and any MCP-aware agent host.",
+  "type": "module",
+  "bin": {
+    "magpie-mcp": "dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "typecheck": "tsc --noEmit",
+    "start": "node dist/index.js",
+    "prepublishOnly": "rm -rf dist && tsc && chmod +x dist/index.js"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "magpie",
+    "solana",
+    "defi",
+    "lending",
+    "ai-agents",
+    "x402",
+    "claude-desktop",
+    "cursor",
+    "windsurf"
+  ],
+  "author": "Magpie Capital",
+  "license": "MIT",
+  "homepage": "https://magpie.capital/x402",
+  "bugs": {
+    "url": "https://github.com/magpiecapital/magpie-x402/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/magpiecapital/magpie-x402.git",
+    "directory": "mcp"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@solana/web3.js": "^1.95.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.5.0"
+  }
+}