@quidli/connect-mcp 0.2.0 → 0.4.0

package/README.md

@@ -8,38 +8,44 @@ Use [Quidli Connect](https://connect.quid.li) from Cursor, Claude Desktop, or an
 |                 | **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 **or** x402 pay-per-call                                                           |
-| **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                          |
+| **Auth**        | Optional API key. Without a key: lookup/scores/agent/price under a shared anonymous quota | API key, x402 pay-per-call, or none for lookup/scores/agent                                |
+| **Pros**        | No install; try without a key; always on Quidli infrastructure                       | Wallet private key never leaves your machine; pay per call with USDC instead of an API key |
+| **Cons**        | Anonymous traffic shares a global rate limit; 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          |
 
 
-Get a Connect API key at [connect.quid.li](https://connect.quid.li) → **Enable API access**.
+Get a Connect API key at [connect.quid.li](https://connect.quid.li) → **Enable API access** for higher limits, `connect_me`, and Smart Send.
 
 ---
 
 ## Hosted (recommended)
 
-Best if you have a Connect API key and want zero local setup.
+Zero local setup. Lookup, scores, agent, and price work without an API key (shared anonymous quota). Add a key for higher limits, your profile (`connect_me`), and Smart Send.
 
 ### 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==)
+[Add to Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=quidli-connect&config=eyJ1cmwiOiJodHRwczovL21jcC5jb25uZWN0LnF1aWQubGkifQ==)
 
 Or paste into **Cursor Settings → MCP → Add new MCP server**:
 
 ```
-cursor://anysphere.cursor-deeplink/mcp/install?name=quidli-connect&config=eyJ1cmwiOiJodHRwczovL21jcC5jb25uZWN0LnF1aWQubGkiLCJoZWFkZXJzIjp7IngtYXBpLWtleSI6IiJ9fQ==
+cursor://anysphere.cursor-deeplink/mcp/install?name=quidli-connect&config=eyJ1cmwiOiJodHRwczovL21jcC5jb25uZWN0LnF1aWQubGkifQ==
 ```
 
-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"
+}
+```
+
+Optional — higher limits and Smart Send:
+
 ```json
 "quidli-connect": {
   "url": "https://mcp.connect.quid.li",
@@ -52,7 +58,7 @@ Merge this into `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project) un
 ### 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>`.
+2. Add a custom MCP connector with URL `https://mcp.connect.quid.li`. Optionally set header `x-api-key: <your-connect-api-key>`.
 
 Or merge this into your config file and restart Claude:
 
@@ -63,10 +69,7 @@ Or merge this into your config file and restart Claude:
 {
   "mcpServers": {
     "quidli-connect": {
-      "url": "https://mcp.connect.quid.li",
-      "headers": {
-        "x-api-key": "<your-connect-api-key>"
-      }
+      "url": "https://mcp.connect.quid.li"
     }
   }
 }
@@ -83,13 +86,8 @@ If your Claude version does not support remote `url` connectors, use the local b
         "-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>"
-      }
+        "https://mcp.connect.quid.li"
+      ]
     }
   }
 }
@@ -97,7 +95,7 @@ If your Claude version does not support remote `url` connectors, use the local b
 
 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.
 
-Until a valid API key is set, requests return `401` with setup instructions.
+Without a key, `initialize` / `tools/list` always succeed. Anonymous `tools/call` share a global quota (HTTP **429** when exceeded — get a key for higher limits). Placeholder keys still return **401**.
 
 ---
 
@@ -152,6 +150,26 @@ No API key. Authenticated calls pay automatically when the API returns HTTP 402.
 
 Use `84532` for Base Sepolia when pointing at a staging API.
 
+#### Option C — no credentials (lookup / scores / agent)
+
+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.
+
+`connect_me`, `connect_drop`, and `connect_drop_balance` still require `CONNECT_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
 
 1. Open **Claude → Settings → Developer → Edit Config** (enable Developer mode first if you do not see it).
@@ -199,7 +217,7 @@ Use `84532` for Base Sepolia when pointing at a staging API.
 
 If both `CONNECT_API_KEY` and `EVM_PRIVATE_KEY` are set, the API key is used.
 
-At least one of `CONNECT_API_KEY` or `EVM_PRIVATE_KEY` is required for local mode.
+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`.
 
 ---
 
@@ -210,10 +228,13 @@ At least one of `CONNECT_API_KEY` or `EVM_PRIVATE_KEY` is required for local mod
 | ---------------------------- | --------------------------------------------------------- |
 | `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           |
 
 

package/dist/anonymous-quota.d.ts

@@ -0,0 +1,28 @@
+import type { AnonymousQuotaConfig } from './config.js';
+export declare const ANON_QUOTA_EXEMPT_TOOLS: Set<string>;
+export declare const ANON_AGENT_TOOL = "connect_agent_prompt";
+export interface QuotaDecision {
+    allowed: boolean;
+    retryAfterSec?: number;
+    message?: string;
+}
+export declare class SlidingWindowLimiter {
+    private readonly limit;
+    private readonly windowMs;
+    private readonly now;
+    private hits;
+    constructor(limit: number, windowMs?: number, now?: () => number);
+    private prune;
+    wouldExceed(): {
+        exceeded: boolean;
+        retryAfterSec: number;
+    };
+    record(): void;
+}
+export declare class AnonymousToolQuota {
+    private readonly global;
+    private readonly agent;
+    constructor(global: SlidingWindowLimiter, agent: SlidingWindowLimiter);
+    static fromConfig(config: AnonymousQuotaConfig, now?: () => number): AnonymousToolQuota;
+    consume(body: unknown): QuotaDecision;
+}

package/dist/anonymous-quota.js

@@ -0,0 +1,78 @@
+import { getJsonRpcMethod, getJsonRpcToolName } from './jsonrpc.js';
+export const ANON_QUOTA_EXEMPT_TOOLS = new Set(['connect_get_price']);
+export const ANON_AGENT_TOOL = 'connect_agent_prompt';
+const GLOBAL_QUOTA_MESSAGE = 'Anonymous MCP quota exceeded. Get a Connect API key at https://connect.quid.li (Enable API access) for higher limits.';
+const AGENT_QUOTA_MESSAGE = 'Anonymous MCP agent quota exceeded. Get a Connect API key at https://connect.quid.li (Enable API access) for higher limits.';
+export class SlidingWindowLimiter {
+    limit;
+    windowMs;
+    now;
+    hits = [];
+    constructor(limit, windowMs = 60_000, now = Date.now) {
+        this.limit = limit;
+        this.windowMs = windowMs;
+        this.now = now;
+    }
+    prune(now) {
+        const cutoff = now - this.windowMs;
+        while (this.hits.length > 0 && this.hits[0] <= cutoff) {
+            this.hits.shift();
+        }
+    }
+    wouldExceed() {
+        const now = this.now();
+        this.prune(now);
+        if (this.hits.length >= this.limit) {
+            const retryAfterSec = Math.max(1, Math.ceil((this.hits[0] + this.windowMs - now) / 1000));
+            return { exceeded: true, retryAfterSec };
+        }
+        return { exceeded: false, retryAfterSec: 0 };
+    }
+    record() {
+        this.hits.push(this.now());
+    }
+}
+export class AnonymousToolQuota {
+    global;
+    agent;
+    constructor(global, agent) {
+        this.global = global;
+        this.agent = agent;
+    }
+    static fromConfig(config, now) {
+        return new AnonymousToolQuota(new SlidingWindowLimiter(config.rpm, 60_000, now), new SlidingWindowLimiter(config.agentRpm, 60_000, now));
+    }
+    consume(body) {
+        const method = getJsonRpcMethod(body);
+        if (method !== 'tools/call') {
+            return { allowed: true };
+        }
+        const toolName = getJsonRpcToolName(body);
+        if (toolName && ANON_QUOTA_EXEMPT_TOOLS.has(toolName)) {
+            return { allowed: true };
+        }
+        if (toolName === ANON_AGENT_TOOL) {
+            const agentLimit = this.agent.wouldExceed();
+            if (agentLimit.exceeded) {
+                return {
+                    allowed: false,
+                    retryAfterSec: agentLimit.retryAfterSec,
+                    message: AGENT_QUOTA_MESSAGE,
+                };
+            }
+        }
+        const globalLimit = this.global.wouldExceed();
+        if (globalLimit.exceeded) {
+            return {
+                allowed: false,
+                retryAfterSec: globalLimit.retryAfterSec,
+                message: GLOBAL_QUOTA_MESSAGE,
+            };
+        }
+        if (toolName === ANON_AGENT_TOOL) {
+            this.agent.record();
+        }
+        this.global.record();
+        return { allowed: true };
+    }
+}

package/dist/client.d.ts

@@ -6,6 +6,8 @@ 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;

package/dist/client.js

@@ -7,7 +7,7 @@ export class ConnectClient {
     paidFetch;
     constructor(config) {
         this.config = config;
-        this.authMode = config.apiKey ? 'api-key' : 'x402';
+        this.authMode = config.evmPrivateKey && !config.apiKey ? 'x402' : 'api-key';
         if (!config.apiKey && config.evmPrivateKey) {
             this.paidFetch = createPaidFetch(config.evmPrivateKey, config.x402EvmNetwork);
         }
@@ -21,6 +21,9 @@ export class ConnectClient {
     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)) {

package/dist/config.d.ts

@@ -13,7 +13,18 @@ export interface HttpServerConfig {
     baseUrl: string;
 }
 export declare function loadHttpServerConfig(env?: NodeJS.ProcessEnv): HttpServerConfig;
-/** Stdio MCP: CONNECT_API_KEY and/or EVM_PRIVATE_KEY (at least one required). */
+/**
+ * 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;
+export interface AnonymousQuotaConfig {
+    allowAnonymous: boolean;
+    rpm: number;
+    agentRpm: number;
+}
+export declare function isAnonymousMcpAllowed(env?: NodeJS.ProcessEnv): boolean;
+export declare function loadAnonymousQuotaConfig(env?: NodeJS.ProcessEnv): AnonymousQuotaConfig;
+/** Hosted HTTP MCP: api-key from request header when present. */
+export declare function createHostedClientConfig(apiKey: string | undefined, baseUrl: string): ConnectClientConfig;

package/dist/config.js

@@ -23,14 +23,15 @@ export function loadHttpServerConfig(env = process.env) {
     }
     return { host, port, baseUrl: loadBaseUrl(env) };
 }
-/** Stdio MCP: CONNECT_API_KEY and/or EVM_PRIVATE_KEY (at least one required). */
+/**
+ * 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() || undefined;
     const evmPrivateKey = normalizeEvmPrivateKey(env.EVM_PRIVATE_KEY);
     const x402EvmNetwork = parseX402EvmNetwork(env);
-    if (!apiKey && !evmPrivateKey) {
-        throw new Error('CONNECT_API_KEY or EVM_PRIVATE_KEY is required. Get an API key at https://connect.quid.li (Enable API access), or set EVM_PRIVATE_KEY for pay-per-call x402.');
-    }
     return {
         baseUrl: loadBaseUrl(env),
         apiKey,
@@ -38,11 +39,35 @@ export function loadConfig(env = process.env) {
         x402EvmNetwork,
     };
 }
-/** Hosted HTTP MCP: api-key from request header only. */
+const DEFAULT_ANON_RPM = 50;
+const DEFAULT_ANON_AGENT_RPM = 5;
+export function isAnonymousMcpAllowed(env = process.env) {
+    const raw = env.CONNECT_MCP_ALLOW_ANONYMOUS?.trim().toLowerCase();
+    return raw === 'true' || raw === '1';
+}
+function parsePositiveInt(raw, fallback, name) {
+    if (!raw?.trim()) {
+        return fallback;
+    }
+    const value = Number(raw);
+    if (!Number.isInteger(value) || value < 1) {
+        throw new Error(`${name} must be a positive integer (got "${raw}")`);
+    }
+    return value;
+}
+export function loadAnonymousQuotaConfig(env = process.env) {
+    return {
+        allowAnonymous: isAnonymousMcpAllowed(env),
+        rpm: parsePositiveInt(env.CONNECT_MCP_ANON_RPM, DEFAULT_ANON_RPM, 'CONNECT_MCP_ANON_RPM'),
+        agentRpm: parsePositiveInt(env.CONNECT_MCP_ANON_AGENT_RPM, DEFAULT_ANON_AGENT_RPM, 'CONNECT_MCP_ANON_AGENT_RPM'),
+    };
+}
+/** Hosted HTTP MCP: api-key from request header when present. */
 export function createHostedClientConfig(apiKey, baseUrl) {
+    const trimmed = apiKey?.trim() || undefined;
     return {
         baseUrl,
-        apiKey,
+        apiKey: trimmed,
         x402EvmNetwork: DEFAULT_X402_EVM_NETWORK,
     };
 }

package/dist/deeplink.d.ts

@@ -1,6 +1,6 @@
 export interface CursorMcpRemoteConfig {
     url: string;
-    headers: {
+    headers?: {
         'x-api-key': string;
     };
 }

package/dist/deeplink.js

@@ -1,9 +1,13 @@
 import { CONNECT_MCP_API_KEY_PLACEHOLDER, CONNECT_MCP_REMOTE_URL } from './metadata.js';
 export function buildCursorRemoteMcpConfig(apiKey = CONNECT_MCP_API_KEY_PLACEHOLDER) {
+    const trimmed = apiKey.trim();
+    if (!trimmed) {
+        return { url: CONNECT_MCP_REMOTE_URL };
+    }
     return {
         url: CONNECT_MCP_REMOTE_URL,
         headers: {
-            'x-api-key': apiKey,
+            'x-api-key': trimmed,
         },
     };
 }

package/dist/hosted-gate.d.ts

@@ -0,0 +1,21 @@
+import { AnonymousToolQuota } from './anonymous-quota.js';
+import { type HeaderCarrier } from './http-auth.js';
+export interface HostedMcpGateOk {
+    ok: true;
+    apiKey?: string;
+}
+export interface HostedMcpGateError {
+    ok: false;
+    status: number;
+    message: string;
+    code: number;
+    retryAfterSec?: number;
+}
+export type HostedMcpGateResult = HostedMcpGateOk | HostedMcpGateError;
+export interface HostedMcpGateRequest extends HeaderCarrier {
+    body?: unknown;
+}
+export declare function gateHostedMcpRequest(req: HostedMcpGateRequest, options: {
+    env?: NodeJS.ProcessEnv;
+    anonymousQuota: AnonymousToolQuota;
+}): HostedMcpGateResult;

package/dist/hosted-gate.js

@@ -0,0 +1,21 @@
+import { validateRequestApiKey } from './http-auth.js';
+export function gateHostedMcpRequest(req, options) {
+    const env = options.env ?? process.env;
+    const auth = validateRequestApiKey(req, env);
+    if (!auth.ok) {
+        return { ok: false, status: 401, message: auth.message, code: -32001 };
+    }
+    if (!auth.apiKey) {
+        const quota = options.anonymousQuota.consume(req.body);
+        if (!quota.allowed) {
+            return {
+                ok: false,
+                status: 429,
+                message: quota.message ?? 'Anonymous MCP quota exceeded.',
+                code: -32029,
+                retryAfterSec: quota.retryAfterSec,
+            };
+        }
+    }
+    return { ok: true, apiKey: auth.apiKey };
+}

package/dist/http-auth.d.ts

@@ -1,13 +1,16 @@
-import type { IncomingMessage } from 'node:http';
+import type { IncomingHttpHeaders } from 'node:http';
 export interface RequestApiKeyResult {
     ok: true;
-    apiKey: string;
+    apiKey?: string;
 }
 export interface RequestApiKeyError {
     ok: false;
     message: string;
 }
 export type RequestApiKeyValidation = RequestApiKeyResult | RequestApiKeyError;
-export declare function extractRequestApiKey(req: IncomingMessage): string | undefined;
+export interface HeaderCarrier {
+    headers: IncomingHttpHeaders;
+}
+export declare function extractRequestApiKey(req: HeaderCarrier): string | undefined;
 export declare function isPlaceholderApiKey(apiKey: string): boolean;
-export declare function validateRequestApiKey(req: IncomingMessage): RequestApiKeyValidation;
+export declare function validateRequestApiKey(req: HeaderCarrier, env?: NodeJS.ProcessEnv): RequestApiKeyValidation;

package/dist/http-auth.js

@@ -1,3 +1,4 @@
+import { isAnonymousMcpAllowed } from './config.js';
 import { CONNECT_MCP_API_KEY_PLACEHOLDER } from './metadata.js';
 const PLACEHOLDER_API_KEYS = new Set([
     'your-connect-api-key',
@@ -14,9 +15,12 @@ export function extractRequestApiKey(req) {
 export function isPlaceholderApiKey(apiKey) {
     return PLACEHOLDER_API_KEYS.has(apiKey);
 }
-export function validateRequestApiKey(req) {
+export function validateRequestApiKey(req, env = process.env) {
     const apiKey = extractRequestApiKey(req);
     if (!apiKey) {
+        if (isAnonymousMcpAllowed(env)) {
+            return { ok: true };
+        }
         return {
             ok: false,
             message: 'Missing x-api-key header. Get a key at https://connect.quid.li (Enable API access) and set it in your MCP headers.',

package/dist/jsonrpc.d.ts

@@ -0,0 +1,2 @@
+export declare function getJsonRpcMethod(body: unknown): string | undefined;
+export declare function getJsonRpcToolName(body: unknown): string | undefined;

package/dist/jsonrpc.js

@@ -0,0 +1,14 @@
+export function getJsonRpcMethod(body) {
+    if (!body || typeof body !== 'object' || Array.isArray(body)) {
+        return undefined;
+    }
+    const method = body.method;
+    return typeof method === 'string' ? method : undefined;
+}
+export function getJsonRpcToolName(body) {
+    if (!body || typeof body !== 'object' || Array.isArray(body)) {
+        return undefined;
+    }
+    const params = body.params;
+    return typeof params?.name === 'string' ? params.name : undefined;
+}

package/dist/metadata.js

@@ -3,7 +3,7 @@ export const CONNECT_MCP_REMOTE_URL = 'https://mcp.connect.quid.li';
 export const CONNECT_MCP_SERVER_INFO = {
     name: 'quidli-connect',
     title: 'Quidli Connect',
-    version: '0.1.0',
+    version: '0.4.0',
     websiteUrl: 'https://connect.quid.li',
     icons: [
         {

package/dist/mount.d.ts

@@ -1,7 +1,10 @@
 import type { IRouter } from 'express';
+import { AnonymousToolQuota } from './anonymous-quota.js';
 export { resolveRequestHost } from './request-host.js';
 export interface ConnectMcpMountOptions {
     baseUrl: string;
+    env?: NodeJS.ProcessEnv;
+    anonymousQuota?: AnonymousToolQuota;
 }
 export declare function resolveEmbeddedApiBaseUrl(port: number, env?: NodeJS.ProcessEnv): string;
 export declare function isConnectMcpHost(hostname: string, env?: NodeJS.ProcessEnv): boolean;

package/dist/mount.js

@@ -1,16 +1,20 @@
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
-import { createHostedClientConfig } from './config.js';
+import { AnonymousToolQuota } from './anonymous-quota.js';
+import { createHostedClientConfig, loadAnonymousQuotaConfig } from './config.js';
 import { createMcpServer } from './create-mcp-server.js';
-import { validateRequestApiKey } from './http-auth.js';
+import { gateHostedMcpRequest } from './hosted-gate.js';
 export { resolveRequestHost } from './request-host.js';
-function sendJsonRpcError(res, status, message) {
+function sendJsonRpcError(res, status, message, options) {
     if (res.headersSent) {
         return;
     }
+    if (options?.retryAfterSec) {
+        res.setHeader('Retry-After', String(options.retryAfterSec));
+    }
     res.status(status).json({
         jsonrpc: '2.0',
         error: {
-            code: -32001,
+            code: options?.code ?? -32001,
             message,
         },
         id: null,
@@ -37,6 +41,8 @@ export function isConnectMcpHost(hostname, env = process.env) {
 }
 export function mountConnectMcpHttp(router, options) {
     const { baseUrl } = options;
+    const env = options.env ?? process.env;
+    const anonymousQuota = options.anonymousQuota ?? AnonymousToolQuota.fromConfig(loadAnonymousQuotaConfig(env));
     router.get('/health', (_req, res) => {
         res.json({ ok: true, service: 'quidli-connect-mcp' });
     });
@@ -44,13 +50,16 @@ export function mountConnectMcpHttp(router, options) {
     // No in-memory session map, so Cloud Run restarts / multiple instances
     // never cause "Missing or invalid MCP session" errors.
     router.all('/', async (req, res) => {
-        const auth = validateRequestApiKey(req);
-        if (!auth.ok) {
-            sendJsonRpcError(res, 401, auth.message);
+        const gate = gateHostedMcpRequest(req, { env, anonymousQuota });
+        if (!gate.ok) {
+            sendJsonRpcError(res, gate.status, gate.message, {
+                code: gate.code,
+                retryAfterSec: gate.retryAfterSec,
+            });
             return;
         }
         try {
-            const server = createMcpServer(createHostedClientConfig(auth.apiKey, baseUrl));
+            const server = createMcpServer(createHostedClientConfig(gate.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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quidli/connect-mcp",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "MCP server for Quidli Connect product APIs",
   "keywords": [
     "mcp",
@@ -39,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",