@quidli/connect-mcp 0.1.1 → 0.3.0

package/README.md

@@ -1,57 +1,128 @@
-# @quidli/connect-mcp
+# Quidli Connect MCP
 
-MCP server exposing [Quidli Connect](https://connect.quid.li) product APIs as tools for Cursor, Claude Desktop, and other MCP hosts.
+Use [Quidli Connect](https://connect.quid.li) from Cursor, Claude Desktop, or any MCP-compatible client — wallet lookup, scores, Smart Send drops, and the Connect agent.
 
-## Requirements
+## Choose how to connect
 
-- Node.js 20+
-- A Connect API key ([Enable API access](https://connect.quid.li))
 
-## Cursor configuration
+|                 | **Hosted** (`mcp.connect.quid.li`)                                                   | **Local** (`npx @quidli/connect-mcp`)                                                      |
+| --------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------ |
+| **Setup**       | Add a URL in MCP settings                                                            | Run a local process via `npx`                                                              |
+| **Auth**        | Connect API key only                                                                 | API key, x402 pay-per-call, or none for lookup/scores/agent                                |
+| **Pros**        | No install; always on Quidli infrastructure; simplest setup                          | Wallet private key never leaves your machine; pay per call with USDC instead of an API key |
+| **Cons**        | Requires a Connect API key; no pay-per-call billing                                  | Requires Node.js 20+; `npx` may download the package on first run                          |
+| **Limitations** | Cannot use x402 / wallet auth — do **not** send a private key to the hosted endpoint | x402 mode needs USDC on Base (mainnet `8453`); `connect_drop` requires an API key          |
 
-### Remote URL (recommended for production)
 
-Same pattern as GitHub MCP — Cursor connects to a hosted endpoint and sends your API key in headers:
+Get a Connect API key at [connect.quid.li](https://connect.quid.li) → **Enable API access**.
+
+---
+
+## Hosted (recommended)
+
+Best if you have a Connect API key and want zero local setup.
+
+### Cursor
+
+**If you already have other MCP servers:** skip the deeplink and [add manually](#cursor-manual) — the one-click install can overwrite your entire `mcp.json` in some Cursor versions.
+
+[Add to Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=quidli-connect&config=eyJ1cmwiOiJodHRwczovL21jcC5jb25uZWN0LnF1aWQubGkiLCJoZWFkZXJzIjp7IngtYXBpLWtleSI6IiJ9fQ==)
+
+Or paste into **Cursor Settings → MCP → Add new MCP server**:
+
+```
+cursor://anysphere.cursor-deeplink/mcp/install?name=quidli-connect&config=eyJ1cmwiOiJodHRwczovL21jcC5jb25uZWN0LnF1aWQubGkiLCJoZWFkZXJzIjp7IngtYXBpLWtleSI6IiJ9fQ==
+```
+
+Then open **Cursor Settings → MCP → quidli-connect** and set `headers.x-api-key` to your Connect API key.
+
+#### Add manually {#cursor-manual}
+
+Merge this into `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project) under `mcpServers` — do not replace your existing entries:
+
+```json
+"quidli-connect": {
+  "url": "https://mcp.connect.quid.li",
+  "headers": {
+    "x-api-key": "<your-connect-api-key>"
+  }
+}
+```
+
+### Claude Desktop
+
+1. Open **Claude → Settings → Connectors** (or **Settings → Developer → Edit Config** on older versions).
+2. Add a custom MCP connector with URL `https://mcp.connect.quid.li` and header `x-api-key: <your-connect-api-key>`.
+
+Or merge this into your config file and restart Claude:
+
+- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
 
 ```json
 {
   "mcpServers": {
-    "connect": {
+    "quidli-connect": {
       "url": "https://mcp.connect.quid.li",
       "headers": {
-        "x-api-key": "set-your-api-key-here"
+        "x-api-key": "<your-connect-api-key>"
       }
     }
   }
 }
 ```
 
-After one-click install, open **Cursor Settings → MCP → connect** and replace `set-your-api-key-here` with your real API key from [connect.quid.li](https://connect.quid.li) (Enable API access). Until you do, the server returns `401` with setup instructions.
-
-**Add to Cursor** deeplink (placeholder key pre-filled):
+If your Claude version does not support remote `url` connectors, use the local bridge instead (still hosted API, runs a small local helper):
 
-```
-cursor://anysphere.cursor-deeplink/mcp/install?name=connect&config=eyJ1cmwiOiJodHRwczovL21jcC5jb25uZWN0LnF1aWQubGkIiwiaGVhZGVycyI6eyJ4LWFwaS1rZXkiOiJzZXQteW91ci1hcGkta2V5LWhlcmUifX0=
+```json
+{
+  "mcpServers": {
+    "quidli-connect": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "mcp-remote@latest",
+        "--http",
+        "https://mcp.connect.quid.li",
+        "--header",
+        "x-api-key:${CONNECT_API_KEY}"
+      ],
+      "env": {
+        "CONNECT_API_KEY": "<your-connect-api-key>"
+      }
+    }
+  }
+}
 ```
 
-Or generate programmatically:
+Requires **Node.js 20+** for the bridge. Restart Claude Desktop after saving. You should see a hammer icon in the chat input when tools are available.
 
-```typescript
-import { buildCursorMcpInstallDeeplink } from '@quidli/connect-mcp/deeplink';
-```
+Until a valid API key is set, requests return `401` with setup instructions.
 
-### Local stdio (npm / development)
+---
 
-Add to `.cursor/mcp.json` (or global MCP settings):
+## Local (stdio)
+
+Best if you want pay-per-call with a wallet, or prefer credentials in a local env file.
+
+Requires **Node.js 20+**.
+
+### Cursor
+
+Add one of the following to `.cursor/mcp.json` (project) or your global MCP settings.
+
+#### Option A — API key
+
+Same billing model as hosted; credentials stay on your machine.
 
 ```json
 {
   "mcpServers": {
-    "connect": {
+    "quidli-connect": {
       "command": "npx",
       "args": ["-y", "@quidli/connect-mcp"],
       "env": {
-        "CONNECT_API_KEY": "<your-api-key>",
+        "CONNECT_API_KEY": "<your-connect-api-key>",
         "CONNECT_API_BASE_URL": "https://api.connect.quid.li"
       }
     }
@@ -59,59 +130,114 @@ Add to `.cursor/mcp.json` (or global MCP settings):
 }
 ```
 
-`CONNECT_API_KEY` is **required** for stdio mode — the process exits at startup if missing. Remote HTTP mode reads `x-api-key` from each request instead.
+#### Option B — x402 pay-per-call (wallet)
 
-## Standalone HTTP server (local / debugging)
+No API key. Authenticated calls pay automatically when the API returns HTTP 402. Your wallet private key is only read by the local process.
 
-```bash
-cd packages/connect-mcp
-npm run build
-CONNECT_API_BASE_URL=https://api.connect.quid.li npm run start:http
+```json
+{
+  "mcpServers": {
+    "quidli-connect": {
+      "command": "npx",
+      "args": ["-y", "@quidli/connect-mcp"],
+      "env": {
+        "EVM_PRIVATE_KEY": "0x<wallet-with-usdc-on-base>",
+        "CONNECT_API_BASE_URL": "https://api.connect.quid.li",
+        "CONNECT_X402_EVM_NETWORK": "8453"
+      }
+    }
+  }
+}
 ```
 
-Environment:
+Use `84532` for Base Sepolia when pointing at a staging API.
 
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `CONNECT_MCP_HTTP_HOST` | `0.0.0.0` | Bind address |
-| `CONNECT_MCP_HTTP_PORT` | `8080` | Listen port |
-| `CONNECT_API_BASE_URL` | `https://api.connect.quid.li` | Upstream Connect API |
+#### Option C — no credentials (lookup / scores / agent)
 
-Health check: `GET /health`
+The MCP process starts without `CONNECT_API_KEY` or `EVM_PRIVATE_KEY`. `connect_lookup`, `connect_scores_*`, `connect_agent_prompt`, and `connect_get_price` call the API without auth. That succeeds when x402 is disabled (price `0`, typical for local). On production with x402 enabled, those tools return HTTP 402 until you set a key or wallet.
 
-## Tools (7)
+`connect_me`, `connect_drop`, and `connect_drop_balance` still require `CONNECT_API_KEY`.
 
-| Tool | HTTP | Auth |
-|------|------|------|
-| `connect_get_price` | `GET /price` | none |
-| `connect_lookup` | `POST /lookup` | api-key |
-| `connect_scores_batch` | `POST /scores` | api-key |
-| `connect_scores_by_account` | `GET /scores/:platform/:identifier` | api-key |
-| `connect_scores_by_username` | `GET /scores/u/:username` | api-key |
-| `connect_drop` | `POST /drop` | api-key |
-| `connect_agent_prompt` | `POST /agent` | api-key |
+```json
+{
+  "mcpServers": {
+    "quidli-connect": {
+      "command": "npx",
+      "args": ["-y", "@quidli/connect-mcp"],
+      "env": {
+        "CONNECT_API_BASE_URL": "http://127.0.0.1:3011"
+      }
+    }
+  }
+}
+```
+
+### Claude Desktop
 
-Not exposed: `POST /lookup/exposed`, agent feedback, member/admin routes.
+1. Open **Claude → Settings → Developer → Edit Config** (enable Developer mode first if you do not see it).
+2. Merge one of the blocks below into `mcpServers` in:
 
-## Auth notes
+- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
 
-- **MCP uses api-key only.** x402 pay-per-call and Privy Bearer are HTTP-only (use [API docs](https://connect.quid.li/docs) or skills directly).
-- `connect_get_price` is public on the HTTP API and does not send `x-api-key`.
+3. Restart Claude Desktop.
 
-## Development
+#### Option A — API key
 
-```bash
-cd packages/connect-mcp
-npm install
-npm test
-npm run build
-CONNECT_API_KEY=<key> npm start
+```json
+{
+  "mcpServers": {
+    "quidli-connect": {
+      "command": "npx",
+      "args": ["-y", "@quidli/connect-mcp"],
+      "env": {
+        "CONNECT_API_KEY": "<your-connect-api-key>",
+        "CONNECT_API_BASE_URL": "https://api.connect.quid.li"
+      }
+    }
+  }
+}
 ```
 
-## Publish
+#### Option B — x402 pay-per-call (wallet)
 
-```bash
-npm publish --access public
+```json
+{
+  "mcpServers": {
+    "quidli-connect": {
+      "command": "npx",
+      "args": ["-y", "@quidli/connect-mcp"],
+      "env": {
+        "EVM_PRIVATE_KEY": "0x<wallet-with-usdc-on-base>",
+        "CONNECT_API_BASE_URL": "https://api.connect.quid.li",
+        "CONNECT_X402_EVM_NETWORK": "8453"
+      }
+    }
+  }
+}
 ```
 
-(Requires `@quidli` npm org access.)
+If both `CONNECT_API_KEY` and `EVM_PRIVATE_KEY` are set, the API key is used.
+
+Credentials are optional in local mode. Without either variable, lookup/scores/agent still work when the API does not charge x402. `connect_me` and Smart Send tools require `CONNECT_API_KEY`.
+
+---
+
+## Tools
+
+
+| Tool                         | What it does                                              |
+| ---------------------------- | --------------------------------------------------------- |
+| `connect_get_price`          | List reference prices (no auth)                           |
+| `connect_lookup`             | Resolve social identities to EVM and SOL wallet addresses |
+| `connect_lookup_exposed`     | List platforms a recipient has exposed on Connect         |
+| `connect_scores_batch`       | Batch scores for accounts or usernames                    |
+| `connect_scores_by_account`  | Scores for one linked account                             |
+| `connect_scores_by_username` | Scores by Connect username                                |
+| `connect_me`                 | API key owner profile, scores, and linked accounts — **API key only** |
+| `connect_drop`               | Smart Send (batch token transfer) — **API key only**      |
+| `connect_drop_balance`       | Smart Send wallet balances on a chain — **API key only**  |
+| `connect_agent_prompt`       | Natural-language agent for recipients discovery           |
+
+
+Ask your client to use these tools when you need Connect data or actions.

package/dist/client.d.ts

@@ -1,16 +1,22 @@
 import type { ConnectClientConfig } from './config.js';
 import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
 export type HttpMethod = 'GET' | 'POST';
+export type ConnectAuthMode = 'api-key' | 'x402';
 export interface ConnectRequestOptions {
     method: HttpMethod;
     path: string;
     authenticated?: boolean;
+    /** Fail before calling the API when CONNECT_API_KEY is unset (Smart Send /me). */
+    requireApiKey?: boolean;
     body?: unknown;
     query?: Record<string, string | undefined>;
     timeoutMs?: number;
 }
 export declare class ConnectClient {
     private readonly config;
+    private readonly authMode;
+    private readonly paidFetch?;
     constructor(config: ConnectClientConfig);
+    private resolveFetch;
     request(options: ConnectRequestOptions): Promise<CallToolResult>;
 }

package/dist/client.js

@@ -1,13 +1,29 @@
 import { mapHttpError } from './errors.js';
 import { errorResult, successResult } from './result.js';
+import { createPaidFetch } from './x402-fetch.js';
 export class ConnectClient {
     config;
+    authMode;
+    paidFetch;
     constructor(config) {
         this.config = config;
+        this.authMode = config.evmPrivateKey && !config.apiKey ? 'x402' : 'api-key';
+        if (!config.apiKey && config.evmPrivateKey) {
+            this.paidFetch = createPaidFetch(config.evmPrivateKey, config.x402EvmNetwork);
+        }
+    }
+    resolveFetch(authenticated) {
+        if (authenticated && this.paidFetch) {
+            return this.paidFetch;
+        }
+        return fetch;
     }
     async request(options) {
         const { method, path, body, query, timeoutMs } = options;
         const authenticated = options.authenticated ?? true;
+        if (options.requireApiKey && !this.config.apiKey) {
+            return errorResult('This tool requires CONNECT_API_KEY. Get a key at https://connect.quid.li (Enable API access). x402 wallet auth is not supported for this action.');
+        }
         const url = new URL(path, `${this.config.baseUrl}/`);
         if (query) {
             for (const [key, value] of Object.entries(query)) {
@@ -19,7 +35,7 @@ export class ConnectClient {
         const headers = {
             accept: 'application/json',
         };
-        if (authenticated) {
+        if (authenticated && this.config.apiKey) {
             headers['x-api-key'] = this.config.apiKey;
         }
         if (body !== undefined) {
@@ -29,8 +45,9 @@ export class ConnectClient {
         const timeout = timeoutMs
             ? setTimeout(() => controller.abort(), timeoutMs)
             : undefined;
+        const httpFetch = this.resolveFetch(authenticated);
         try {
-            const response = await fetch(url, {
+            const response = await httpFetch(url, {
                 method,
                 headers,
                 body: body !== undefined ? JSON.stringify(body) : undefined,
@@ -39,9 +56,9 @@ export class ConnectClient {
             const raw = await response.json().catch(() => ({}));
             if (!response.ok) {
                 if (response.status === 504) {
-                    return errorResult(mapHttpError(504, raw));
+                    return errorResult(mapHttpError(504, raw, this.authMode));
                 }
-                return errorResult(mapHttpError(response.status, raw));
+                return errorResult(mapHttpError(response.status, raw, this.authMode));
             }
             return successResult({
                 httpStatus: response.status,

package/dist/config.d.ts

@@ -1,6 +1,11 @@
 export interface ConnectClientConfig {
     baseUrl: string;
-    apiKey: string;
+    /** When set, sent on every authenticated Connect API request. */
+    apiKey?: string;
+    /** When apiKey is unset, authenticated requests pay via x402 on 402. */
+    evmPrivateKey?: `0x${string}`;
+    /** EVM chain id for x402 (default 8453 = Base mainnet). */
+    x402EvmNetwork: number;
 }
 export interface HttpServerConfig {
     host: string;
@@ -8,4 +13,11 @@ export interface HttpServerConfig {
     baseUrl: string;
 }
 export declare function loadHttpServerConfig(env?: NodeJS.ProcessEnv): HttpServerConfig;
+/**
+ * Stdio MCP: credentials are optional.
+ * Lookup/scores/agent work without auth when the API allows it (x402 price 0)
+ * or with CONNECT_API_KEY / EVM_PRIVATE_KEY. /account/me and /drop require an API key.
+ */
 export declare function loadConfig(env?: NodeJS.ProcessEnv): ConnectClientConfig;
+/** Hosted HTTP MCP: api-key from request header only. */
+export declare function createHostedClientConfig(apiKey: string, baseUrl: string): ConnectClientConfig;

package/dist/config.js

@@ -1,6 +1,19 @@
+import { normalizeEvmPrivateKey } from './x402-fetch.js';
 const DEFAULT_BASE_URL = 'https://api.connect.quid.li';
 const DEFAULT_HTTP_HOST = '0.0.0.0';
 const DEFAULT_HTTP_PORT = 8080;
+const DEFAULT_X402_EVM_NETWORK = 8453;
+function parseX402EvmNetwork(env) {
+    const raw = env.CONNECT_X402_EVM_NETWORK?.trim() || env.X402_EVM_NETWORK?.trim() || String(DEFAULT_X402_EVM_NETWORK);
+    const network = Number(raw);
+    if (!Number.isInteger(network) || network < 1) {
+        throw new Error(`CONNECT_X402_EVM_NETWORK must be a positive integer (got "${raw}")`);
+    }
+    return network;
+}
+function loadBaseUrl(env) {
+    return (env.CONNECT_API_BASE_URL?.trim() || DEFAULT_BASE_URL).replace(/\/$/, '');
+}
 export function loadHttpServerConfig(env = process.env) {
     const host = env.CONNECT_MCP_HTTP_HOST?.trim() || DEFAULT_HTTP_HOST;
     const portRaw = env.CONNECT_MCP_HTTP_PORT?.trim() || String(DEFAULT_HTTP_PORT);
@@ -8,14 +21,29 @@ export function loadHttpServerConfig(env = process.env) {
     if (!Number.isInteger(port) || port < 1 || port > 65535) {
         throw new Error(`CONNECT_MCP_HTTP_PORT must be a valid port (got "${portRaw}")`);
     }
-    const baseUrl = (env.CONNECT_API_BASE_URL?.trim() || DEFAULT_BASE_URL).replace(/\/$/, '');
-    return { host, port, baseUrl };
+    return { host, port, baseUrl: loadBaseUrl(env) };
 }
+/**
+ * Stdio MCP: credentials are optional.
+ * Lookup/scores/agent work without auth when the API allows it (x402 price 0)
+ * or with CONNECT_API_KEY / EVM_PRIVATE_KEY. /account/me and /drop require an API key.
+ */
 export function loadConfig(env = process.env) {
-    const apiKey = env.CONNECT_API_KEY?.trim();
-    if (!apiKey) {
-        throw new Error('CONNECT_API_KEY is required. Get a key at https://connect.quid.li (Enable API access).');
-    }
-    const baseUrl = (env.CONNECT_API_BASE_URL?.trim() || DEFAULT_BASE_URL).replace(/\/$/, '');
-    return { apiKey, baseUrl };
+    const apiKey = env.CONNECT_API_KEY?.trim() || undefined;
+    const evmPrivateKey = normalizeEvmPrivateKey(env.EVM_PRIVATE_KEY);
+    const x402EvmNetwork = parseX402EvmNetwork(env);
+    return {
+        baseUrl: loadBaseUrl(env),
+        apiKey,
+        evmPrivateKey: apiKey ? undefined : evmPrivateKey,
+        x402EvmNetwork,
+    };
+}
+/** Hosted HTTP MCP: api-key from request header only. */
+export function createHostedClientConfig(apiKey, baseUrl) {
+    return {
+        baseUrl,
+        apiKey,
+        x402EvmNetwork: DEFAULT_X402_EVM_NETWORK,
+    };
 }

package/dist/deeplink.js

@@ -7,7 +7,7 @@ export function buildCursorRemoteMcpConfig(apiKey = CONNECT_MCP_API_KEY_PLACEHOL
         },
     };
 }
-export function buildCursorMcpInstallDeeplink(serverName = 'connect', config = buildCursorRemoteMcpConfig()) {
+export function buildCursorMcpInstallDeeplink(serverName = 'quidli-connect', config = buildCursorRemoteMcpConfig()) {
     const encoded = Buffer.from(JSON.stringify(config), 'utf8').toString('base64');
     return `cursor://anysphere.cursor-deeplink/mcp/install?name=${encodeURIComponent(serverName)}&config=${encoded}`;
 }

package/dist/errors.d.ts

@@ -1,2 +1,3 @@
 export declare function parseNestErrorMessage(body: unknown): string;
-export declare function mapHttpError(status: number, body: unknown): string;
+export type ConnectAuthMode = 'api-key' | 'x402';
+export declare function mapHttpError(status: number, body: unknown, authMode?: ConnectAuthMode): string;

package/dist/errors.js

@@ -10,15 +10,19 @@ export function parseNestErrorMessage(body) {
     }
     return 'Request failed';
 }
-export function mapHttpError(status, body) {
+export function mapHttpError(status, body, authMode = 'api-key') {
     const detail = parseNestErrorMessage(body);
     switch (status) {
         case 400:
             return detail;
         case 401:
-            return `Unauthorized: ${detail}. Verify CONNECT_API_KEY at https://connect.quid.li`;
+            return authMode === 'api-key'
+                ? `Unauthorized: ${detail}. Verify CONNECT_API_KEY at https://connect.quid.li`
+                : `Unauthorized: ${detail}. Verify EVM_PRIVATE_KEY and wallet USDC balance for x402.`;
         case 402:
-            return `Payment required (${detail}). MCP requires a valid Connect API key — x402 is not supported in MCP.`;
+            return authMode === 'api-key'
+                ? `Payment required (${detail}). Set CONNECT_API_KEY or use local stdio with EVM_PRIVATE_KEY for x402.`
+                : `Payment failed (${detail}). Ensure your wallet has USDC on the expected network and EVM_PRIVATE_KEY is correct.`;
         case 404:
             return detail;
         case 504:

package/dist/mount.js

@@ -1,4 +1,5 @@
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { createHostedClientConfig } from './config.js';
 import { createMcpServer } from './create-mcp-server.js';
 import { validateRequestApiKey } from './http-auth.js';
 export { resolveRequestHost } from './request-host.js';
@@ -49,7 +50,7 @@ export function mountConnectMcpHttp(router, options) {
             return;
         }
         try {
-            const server = createMcpServer({ apiKey: auth.apiKey, baseUrl });
+            const server = createMcpServer(createHostedClientConfig(auth.apiKey, baseUrl));
             const transport = new StreamableHTTPServerTransport({
                 sessionIdGenerator: undefined, // stateless — no session tracking
                 enableJsonResponse: true,

package/dist/schemas.d.ts

@@ -28,6 +28,21 @@ export declare const lookupInputSchema: {
         username: z.ZodOptional<z.ZodString>;
     }, z.ZodTypeAny, "passthrough">>, "many">;
 };
+export declare const lookupExposedInputSchema: {
+    recipient: z.ZodObject<{
+        type: z.ZodEnum<["email", "phone", "telegram", "discord", "farcaster", "twitter", "github", "linkedin", "slack", "wallet", "username"]>;
+        id: z.ZodOptional<z.ZodString>;
+        username: z.ZodOptional<z.ZodString>;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        type: z.ZodEnum<["email", "phone", "telegram", "discord", "farcaster", "twitter", "github", "linkedin", "slack", "wallet", "username"]>;
+        id: z.ZodOptional<z.ZodString>;
+        username: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        type: z.ZodEnum<["email", "phone", "telegram", "discord", "farcaster", "twitter", "github", "linkedin", "slack", "wallet", "username"]>;
+        id: z.ZodOptional<z.ZodString>;
+        username: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough">>;
+};
 export declare const scoresBatchInputSchema: {
     users: z.ZodArray<z.ZodObject<{
         type: z.ZodEnum<["email", "phone", "telegram", "discord", "farcaster", "twitter", "github", "linkedin", "slack", "wallet", "username"]>;
@@ -60,6 +75,9 @@ export declare const scoresByAccountInputSchema: {
 export declare const scoresByUsernameInputSchema: {
     username: z.ZodString;
 };
+export declare const dropBalanceInputSchema: {
+    chainId: z.ZodNumber;
+};
 export declare const dropInputSchema: {
     idempotencyKey: z.ZodString;
     chainId: z.ZodNumber;

package/dist/schemas.js

@@ -26,6 +26,9 @@ export const lookupInputSchema = {
         .min(1)
         .describe('Recipients to resolve to EVM/Solana wallets'),
 };
+export const lookupExposedInputSchema = {
+    recipient: linkedAccountSchema.describe('Recipient whose exposed linked accounts and Connect profile should be listed'),
+};
 export const scoresBatchInputSchema = {
     users: z.array(linkedAccountSchema).min(1).describe('Users to fetch scores for'),
     filter: z
@@ -59,6 +62,9 @@ export const scoresByAccountInputSchema = {
 export const scoresByUsernameInputSchema = {
     username: z.string().min(1),
 };
+export const dropBalanceInputSchema = {
+    chainId: z.number().int().describe('EVM chain ID (Smart Send supported chains only)'),
+};
 export const dropInputSchema = {
     idempotencyKey: z.string().uuid(),
     chainId: z.number().int(),

package/dist/tools/register.d.ts

@@ -1,4 +1,4 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { ConnectClient } from '../client.js';
-export declare const CONNECT_MCP_TOOL_NAMES: readonly ["connect_get_price", "connect_lookup", "connect_scores_batch", "connect_scores_by_account", "connect_scores_by_username", "connect_drop", "connect_agent_prompt"];
+export declare const CONNECT_MCP_TOOL_NAMES: readonly ["connect_get_price", "connect_lookup", "connect_lookup_exposed", "connect_scores_batch", "connect_scores_by_account", "connect_scores_by_username", "connect_me", "connect_drop", "connect_drop_balance", "connect_agent_prompt"];
 export declare function registerTools(server: McpServer, client: ConnectClient): void;

package/dist/tools/register.js

@@ -1,12 +1,15 @@
-import { agentPromptInputSchema, dropInputSchema, lookupInputSchema, scoresBatchInputSchema, scoresByAccountInputSchema, scoresByUsernameInputSchema, } from '../schemas.js';
+import { agentPromptInputSchema, dropBalanceInputSchema, dropInputSchema, lookupExposedInputSchema, lookupInputSchema, scoresBatchInputSchema, scoresByAccountInputSchema, scoresByUsernameInputSchema, } from '../schemas.js';
 const AGENT_TIMEOUT_MS = 65_000;
 export const CONNECT_MCP_TOOL_NAMES = [
     'connect_get_price',
     'connect_lookup',
+    'connect_lookup_exposed',
     'connect_scores_batch',
     'connect_scores_by_account',
     'connect_scores_by_username',
+    'connect_me',
     'connect_drop',
+    'connect_drop_balance',
     'connect_agent_prompt',
 ];
 export function registerTools(server, client) {
@@ -16,6 +19,11 @@ export function registerTools(server, client) {
         path: '/lookup',
         body: { recipients },
     }));
+    server.tool('connect_lookup_exposed', 'List platforms a recipient has exposed on Connect, with enriched profile, scores, and wallet addresses. May require x402 payment when the profile owner charges for lookups.', lookupExposedInputSchema, async ({ recipient }) => client.request({
+        method: 'POST',
+        path: '/lookup/exposed',
+        body: { recipient },
+    }));
     server.tool('connect_scores_batch', 'Batch scores for linked accounts or Connect usernames. Optional filter excludes users below minScore.', scoresBatchInputSchema, async ({ users, filter }) => client.request({
         method: 'POST',
         path: '/scores',
@@ -29,14 +37,25 @@ export function registerTools(server, client) {
         method: 'GET',
         path: `/scores/u/${encodeURIComponent(username.trim())}`,
     }));
+    server.tool('connect_me', 'Get the Connect profile, scores, and all linked accounts for the API key owner. Use to identify which user the key belongs to.', {}, async () => client.request({
+        method: 'GET',
+        path: '/account/me',
+    }));
     server.tool('connect_drop', 'Execute a Smart Send (batch token transfer). Returns 201 when submitted or 202 when recipients still processing — retry with same idempotencyKey.', dropInputSchema, async ({ ignoreFailedRecipients, ...body }) => client.request({
         method: 'POST',
         path: '/drop',
         body,
+        requireApiKey: true,
         query: ignoreFailedRecipients === true
             ? { ignoreFailedRecipients: 'true' }
             : undefined,
     }));
+    server.tool('connect_drop_balance', 'Get native and ERC-20 balances for the API key owner Smart Send embedded wallet on a chain. Use before connect_drop to verify gas and token funds.', dropBalanceInputSchema, async ({ chainId }) => client.request({
+        method: 'GET',
+        path: '/drop/balance',
+        requireApiKey: true,
+        query: { chainId: String(chainId) },
+    }));
     server.tool('connect_agent_prompt', 'Natural-language agent turn for Farcaster/Lens cohort discovery. Blocking up to 60s. Omit sessionId to start; include to continue. Do not send requester.', agentPromptInputSchema, async ({ prompt, sessionId }) => client.request({
         method: 'POST',
         path: '/agent',

package/dist/x402-fetch.d.ts

@@ -0,0 +1,2 @@
+export declare function normalizeEvmPrivateKey(value: string | undefined): `0x${string}` | undefined;
+export declare function createPaidFetch(evmPrivateKey: `0x${string}`, chainId: number): typeof fetch;

package/dist/x402-fetch.js

@@ -0,0 +1,30 @@
+import { x402Client, wrapFetchWithPayment } from '@x402/fetch';
+import { ExactEvmScheme } from '@x402/evm/exact/client';
+import { toClientEvmSigner } from '@x402/evm';
+import { privateKeyToAccount } from 'viem/accounts';
+import { createPublicClient, http } from 'viem';
+import { base, baseSepolia } from 'viem/chains';
+const EVM_CHAIN_BY_ID = {
+    8453: base,
+    84532: baseSepolia,
+};
+export function normalizeEvmPrivateKey(value) {
+    const trimmed = value?.trim();
+    if (!trimmed) {
+        return undefined;
+    }
+    return (trimmed.startsWith('0x') ? trimmed : `0x${trimmed}`);
+}
+function getEvmPublicClient(chainId) {
+    const chain = EVM_CHAIN_BY_ID[chainId] ?? base;
+    return createPublicClient({ chain, transport: http() });
+}
+export function createPaidFetch(evmPrivateKey, chainId) {
+    const account = privateKeyToAccount(evmPrivateKey);
+    const evmSigner = toClientEvmSigner(account, getEvmPublicClient(chainId));
+    const client = new x402Client();
+    const scheme = new ExactEvmScheme(evmSigner);
+    client.register(`eip155:${chainId}`, scheme);
+    client.register('eip155:*', scheme);
+    return wrapFetchWithPayment(fetch, client);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quidli/connect-mcp",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "MCP server for Quidli Connect product APIs",
   "keywords": [
     "mcp",
@@ -13,6 +13,11 @@
     "agent"
   ],
   "homepage": "https://connect.quid.li",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Quidli/sns-backend.git",
+    "directory": "packages/connect-mcp"
+  },
   "author": {
     "name": "Quidli",
     "url": "https://quid.xyz"
@@ -34,8 +39,8 @@
     "./http": "./dist/http.js"
   },
   "scripts": {
-    "build": "tsc && chmod +x dist/index.js dist/index-http.js",
-    "prepublishOnly": "npm run build",
+    "build": "tsc",
+    "prepublishOnly": "npm run build && chmod +x dist/index.js dist/index-http.js",
     "start": "node dist/index.js",
     "start:http": "node dist/index-http.js",
     "test": "vitest run",
@@ -47,10 +52,14 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.25.2",
+    "@x402/evm": "~2.5.0",
+    "@x402/fetch": "~2.5.0",
     "express": "^5.2.1",
+    "viem": "^2.50.4",
     "zod": "^3.24.2"
   },
   "devDependencies": {
+    "@types/express": "^5.0.6",
     "@types/node": "^22.13.10",
     "typescript": "^5.8.2",
     "vitest": "^3.0.9"