a2a-exposed 0.4.0 → 0.5.0

package/lib/a2a.mjs

@@ -185,3 +185,70 @@ export async function rpc(url, version, token, method03, method1, params, peer =
 		die(`peer returned ${data && typeof data === "object" && data.error ? `JSON-RPC error ${describeHttp(status, data).replace(/^HTTP \d+: /, "")} (HTTP ${status})` : describeHttp(status, data)}`);
 	return data.result;
 }
+
+// ---------------------------------------------------------------- proxy mode: what the upstream card asks for
+// Same rules as the Worker's facade.ts (schemeKind / upstreamAuth); keep the two in step.
+
+/** "bearer" (HTTP bearer; OAuth 2.0 / OpenID Connect also send `Authorization: Bearer`), "basic", "http", "apiKey",
+ *  "mtls" or "unknown", for an A2A 1.0 ({ httpAuthSecurityScheme: ... }) or 0.3 / OpenAPI ({ type: "http", ... }) scheme. */
+export function schemeKind(s) {
+	if (!s || typeof s !== "object") return "unknown";
+	const http = (scheme) => { const v = String(scheme || "").toLowerCase(); return v === "bearer" ? "bearer" : v === "basic" ? "basic" : "http"; };
+	if (s.httpAuthSecurityScheme) return http(s.httpAuthSecurityScheme.scheme);
+	if (s.oauth2SecurityScheme || s.openIdConnectSecurityScheme) return "bearer";
+	if (s.apiKeySecurityScheme) return "apiKey";
+	if (s.mtlsSecurityScheme || s.mutualTlsSecurityScheme) return "mtls";
+	switch (String(s.type || "").toLowerCase()) {
+		case "http": return http(s.scheme);
+		case "oauth2": case "openidconnect": return "bearer";
+		case "apikey": return "apiKey";
+		case "mutualtls": return "mtls";
+	}
+	return "unknown";
+}
+
+/** { bearer: true | false | null, schemes: ["name: kind"], unsupported: [...] } for an upstream card. bearer: true when
+ *  the card asks for a bearer token (UPSTREAM_TOKEN), false when it declares no bearer / HTTP auth (no schemes,
+ *  anonymous allowed, or only schemes the façade can't present), null without a card. Requirements come from 1.0
+ *  `securityRequirements` or 0.3 `security`; without requirements every declared scheme counts. */
+export function upstreamAuth(card) {
+	if (!card || typeof card !== "object" || Array.isArray(card)) return { bearer: null, schemes: [], unsupported: [] };
+	const defs = card.securitySchemes && typeof card.securitySchemes === "object" && !Array.isArray(card.securitySchemes) ? card.securitySchemes : {};
+	const kinds = {};
+	for (const [n, s] of Object.entries(defs)) kinds[n] = schemeKind(s);
+	const schemes = Object.entries(kinds).map(([n, k]) => `${n}: ${k}`);
+	const raw = Array.isArray(card.securityRequirements) ? card.securityRequirements : Array.isArray(card.security) ? card.security : [];
+	const alts = raw.filter((r) => r && typeof r === "object" && !Array.isArray(r))
+		.map((r) => Object.keys(r.schemes && typeof r.schemes === "object" && !Array.isArray(r.schemes) ? r.schemes : r));
+	const kindOf = (n) => kinds[n] || "unknown";
+	if (!alts.length) {
+		const all = Object.keys(kinds);
+		const bearer = all.some((n) => kinds[n] === "bearer");
+		return { bearer, schemes, unsupported: bearer ? [] : all.filter((n) => kinds[n] !== "unknown").map((n) => `${n}: ${kinds[n]}`) };
+	}
+	if (alts.some((a) => a.length === 0)) return { bearer: false, schemes, unsupported: [] };
+	const bearer = alts.some((a) => a.some((n) => kindOf(n) === "bearer"));
+	return { bearer, schemes, unsupported: bearer ? [] : [...new Set(alts.flat())].map((n) => `${n}: ${kindOf(n)}`) };
+}
+
+/** Fetch the upstream's card from this machine (setup check), with the Access service token from the environment
+ *  when exported; only ever to the upstream origin (the caller checked it). Never sends UPSTREAM_TOKEN. Returns
+ *  { card } or { card: null, error }. Redirects are not followed (an Access login redirect is reported as such). */
+export async function fetchUpstreamCard(cardUrl, env = process.env) {
+	const headers = { accept: "application/json", "user-agent": "a2a-exposed-cli" };
+	if (env.UPSTREAM_ACCESS_CLIENT_ID && env.UPSTREAM_ACCESS_CLIENT_SECRET) {
+		headers["cf-access-client-id"] = env.UPSTREAM_ACCESS_CLIENT_ID;
+		headers["cf-access-client-secret"] = env.UPSTREAM_ACCESS_CLIENT_SECRET;
+	}
+	let r;
+	try { r = await fetch(cardUrl, { headers, redirect: "manual", signal: AbortSignal.timeout(15000) }); }
+	catch (e) { return { card: null, error: `request failed: ${e?.cause?.code || e?.cause?.message || e?.message || e}` }; }
+	const text = (await r.text().catch(() => "")).slice(0, 262144);
+	const loc = r.headers.get("location") || "";
+	if (r.status >= 300 && r.status < 400)
+		return { card: null, error: /cloudflareaccess\.com|\/cdn-cgi\/access\//i.test(loc) ? `HTTP ${r.status}: redirected to the Cloudflare Access login (export UPSTREAM_ACCESS_CLIENT_ID / UPSTREAM_ACCESS_CLIENT_SECRET so this check can pass Access)` : `HTTP ${r.status} redirect` };
+	let data = null;
+	try { data = JSON.parse(text); } catch { /* not JSON */ }
+	if (r.status === 200 && data && typeof data === "object" && !Array.isArray(data)) return { card: data };
+	return { card: null, error: describeHttp(r.status, data ?? text) };
+}

package/lib/commands.mjs

@@ -101,6 +101,11 @@ export async function token(action, label, o) {
 			const via = r.source === "pairing" ? `\tvia pairing: code ${r.user_code || "?"}${r.client_name ? `, ${JSON.stringify(r.client_name)}` : ""}` : "";
 			console.log(`${r.label}\tcreated=${r.created_at}\t${r.revoked_at ? "REVOKED " + r.revoked_at : "active"}${via}`);
 		}
+		// MCP connectors (Worker 0.5+): their own tokens, listed and revoked by label like peer tokens
+		const m = await ownerTry("GET", "/owner/mcp").catch(() => null);
+		if (m && m.status === 200 && m.data && Array.isArray(m.data.grants))
+			for (const g of m.data.grants)
+				console.log(`${g.label}\tcreated=${g.created_at}\t${g.revoked_at ? "REVOKED " + g.revoked_at : "active"}\tMCP connector: ${JSON.stringify(g.client_name || "?")} -> ${g.redirect_host}${g.last_used_at ? `, last used ${g.last_used_at}` : ""}`);
 		return;
 	}
 	if (!label) die("label required");
@@ -118,6 +123,14 @@ export async function token(action, label, o) {
 			if (o.json) return out({ revoked: true, label });
 			return console.log(`revoked ${label}: its token gets HTTP 401 from now on`);
 		}
+		if (r.status === 404) {
+			// not a peer token: maybe an MCP connector
+			const m = await ownerTry("DELETE", `/owner/mcp/${q(label)}`).catch(() => null);
+			if (m && m.status === 200 && m.data && m.data.revoked === true) {
+				if (o.json) return out({ revoked: true, label, kind: "mcp" });
+				return console.log(`revoked ${label}: that MCP connector gets HTTP 401 from now on (remove it in the client, or reconnect to approve it again)`);
+			}
+		}
 		if (r.status === 404 || (r.status === 200 && r.data && r.data.revoked === false))
 			die((r.data && r.data.error) || `no active token with label ${label} (see: a2a-exposed token list)`);
 		die(`could not revoke ${label}: ${describeHttp(r.status, r.data)}`);
@@ -157,7 +170,35 @@ function resolvePeer(to) {
 	die(`unknown peer alias ${JSON.stringify(to)} (see: a2a-exposed peers list)`);
 }
 
+/** peers sync [alias...]: upload outbound peers (URL + token, encrypted on the Worker with a key derived from the owner
+ *  token) so the MCP connector's send / poll_outbound tools can reach them. peers unsync <alias>: remove one. */
+async function peersRemote(sub, args) {
+	if (sub === "unsync") {
+		if (!args.length) die("usage: peers unsync <alias>...");
+		for (const alias of args) {
+			const r = await ownerTry("DELETE", `/owner/outbound-peers/${q(alias)}`);
+			if (r.status !== 200) die((r.data && r.data.error) || `could not unsync ${alias}: ${describeHttp(r.status, r.data)}`);
+			console.log(`unsynced ${alias}: the connector can no longer send to it`);
+		}
+		return;
+	}
+	const all = C.loadPeers();
+	const list = args.length ? args : Object.keys(all);
+	if (!list.length) die("no peers to sync: add one first (a2a-exposed connect <url> or peers add)");
+	for (const alias of list) {
+		const pe = all[alias];
+		if (!pe) die(`unknown peer alias ${JSON.stringify(alias)} (see: a2a-exposed peers list)`);
+		const tok = peerToken(pe.token_env);
+		const r = await ownerTry("PUT", `/owner/outbound-peers/${q(alias)}`, { url: pe.url.replace(/\/$/, ""), ...(tok ? { token: tok } : {}) });
+		if (r.status === 404) die("this Worker has no MCP support yet: redeploy (a2a-exposed deploy) and try again");
+		if (r.status !== 200) die(`could not sync ${alias}: ${(r.data && r.data.error) || describeHttp(r.status, r.data)}`);
+		console.log(`synced ${alias}\t${pe.url}\t${tok ? "token stored encrypted on the Worker" : "no token"}`);
+	}
+	console.error("# the MCP connector's send tool can now reach these peers; re-run after connect / token changes or an owner-token rotation");
+}
+
 export function peers(sub, args, o) {
+	if (sub === "sync" || sub === "unsync") return peersRemote(sub, args);
 	const all = C.loadPeers();
 	if (sub === "add") {
 		const [alias, url] = args;

package/lib/config.mjs

@@ -1,14 +1,12 @@
-// Config storage: ~/.config/a2a-exposed/config.env (chmod 600) + peers.json. Before the rename the directory was
-// ~/.config/a2a-over-webhook: when only that one exists it is used as is (nothing is moved or copied).
+// Config storage: ~/.config/a2a-exposed/config.env (chmod 600) + peers.json.
 // Environment variables always override values from config.env.
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 
-/** <base>/a2a-exposed, or the pre-rename <base>/a2a-over-webhook when only that exists (an existing deployment). */
-export function defaultConfigDir(base = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config"), exists = fs.existsSync) {
-	const dir = path.join(base, "a2a-exposed"), legacy = path.join(base, "a2a-over-webhook");
-	return !exists(dir) && exists(legacy) ? legacy : dir;
+/** <base>/a2a-exposed (base: $XDG_CONFIG_HOME or ~/.config). */
+export function defaultConfigDir(base = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config")) {
+	return path.join(base, "a2a-exposed");
 }
 
 export const CONFIG_DIR = process.env.A2A_CONFIG_DIR || defaultConfigDir();

package/lib/deploy.mjs

@@ -5,11 +5,25 @@ import path from "node:path";
 import { spawn, spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import * as C from "./config.mjs";
-import { cardUrlProblem, cfErrorCode, die, fingerprint, httpJson, randomToken, upstreamCardUrlProblem, upstreamUrlProblem } from "./a2a.mjs";
-import { owner } from "./commands.mjs";
+import { cardUrlProblem, cfErrorCode, die, fetchUpstreamCard, fingerprint, httpJson, randomToken, upstreamAuth, upstreamCardUrlProblem, upstreamUrlProblem } from "./a2a.mjs";
+import { owner, ownerTry } from "./commands.mjs";
+import { readHidden } from "./pair.mjs";
 import * as WD from "./workersdev.mjs";
 
 const PKG_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+/** Each Claude Code routine fire is a new cloud session: a 2xx only means a session started. */
+export const CLAUDE_CODE_NOTE = [
+	"note (claude-code): each fire starts a NEW cloud session, which sees only what the routine provides.",
+	"  Simplest: add this inbox as a connector at claude.ai/settings/connectors (URL: <your Worker URL>/mcp, approve with",
+	"  your approval password) and keep it enabled on the routine; the session then uses its tools, no CLI or token needed.",
+	"  Without the connector (CLI fallback), check that",
+	"  - the repo with the committed skills (.claude/skills/) is a routine source and the skills are on its default branch,",
+	"  - A2A_BASE_URL and A2A_OWNER_TOKEN are set on the routine's cloud environment (not only in this session),",
+	"  - the environment's network access allows this Worker's hostname,",
+	"  - the routine prompt tells Claude to act on the routine-fire-payload block.",
+	"  Then open the new session from the routine's runs and confirm it ran the inbox command without errors.",
+].join("\n");
+
 const PRESETS = ["grok-bot", "claude-code", "openclaw-wake", "openclaw-agent", "hermes", "generic"];
 // WAKE_ACCESS_*: Cloudflare Access service token for a wake URL behind Access (set by `tunnel create`, or exported
 // by hand for your own Access-protected endpoint)
@@ -26,7 +40,7 @@ const DEPLOY_KEYS = [
 	"A2A_PROVIDER_ORGANIZATION", "A2A_PROVIDER_URL", "A2A_DOCUMENTATION_URL",
 	"WAKE_PRESET", "WAKE_AGENT_ID", "WAKE_KEY_HEADER", "WAKE_KEY_PREFIX", "WAKE_BODY_TEMPLATE", "WAKE_CLI_COMMAND",
 	"WAKE_DEBOUNCE_SECONDS", "WAKE_MAX_PER_HOUR", "A2A_MAX_BODY", "A2A_RATE_PER_MIN", "A2A_ENABLE_CRON",
-	"A2A_WORKERS_DEV_SUBDOMAIN", "A2A_RETIRED_HOSTNAMES", "PAIRING_APPROVAL", "A2A_PBKDF2_ITERATIONS", "A2A_WORKERS_LOGS",
+	"A2A_WORKERS_DEV_SUBDOMAIN", "A2A_RETIRED_HOSTNAMES", "PAIRING_APPROVAL", "A2A_PBKDF2_ITERATIONS", "A2A_WORKERS_LOGS", "A2A_MCP",
 	"A2A_UPSTREAM_URL", "A2A_UPSTREAM_CARD_URL",
 ];
 // init/deploy flag -> config key
@@ -36,17 +50,15 @@ const FLAG_KEYS = {
 	"provider-organization": "A2A_PROVIDER_ORGANIZATION", "provider-url": "A2A_PROVIDER_URL",
 	preset: "WAKE_PRESET", "agent-id": "WAKE_AGENT_ID", "key-header": "WAKE_KEY_HEADER", "key-prefix": "WAKE_KEY_PREFIX",
 	"body-template": "WAKE_BODY_TEMPLATE", "cli-command": "WAKE_CLI_COMMAND", debounce: "WAKE_DEBOUNCE_SECONDS", "max-per-hour": "WAKE_MAX_PER_HOUR",
-	"pairing-approval": "PAIRING_APPROVAL", "pbkdf2-iterations": "A2A_PBKDF2_ITERATIONS", "workers-logs": "A2A_WORKERS_LOGS",
+	"pairing-approval": "PAIRING_APPROVAL", "pbkdf2-iterations": "A2A_PBKDF2_ITERATIONS", "workers-logs": "A2A_WORKERS_LOGS", mcp: "A2A_MCP",
 	upstream: "A2A_UPSTREAM_URL", "upstream-card-url": "A2A_UPSTREAM_CARD_URL",
 };
 export const PAIRING_MODES = ["human", "agent", "off"];
 export const DEPLOY_FLAGS = Object.keys(FLAG_KEYS);
 
 const step = (s) => console.error(`==> ${s}`);
-// Worker (and default D1) name for new deployments. A deployment made before the rename that has no saved
-// A2A_WORKER_NAME (a hand-written config.env) keeps the old default, so `deploy` never creates a second Worker.
-export const LEGACY_WORKER_NAME = "a2a-over-webhook";
-export const workerName = () => C.get("A2A_WORKER_NAME") || (C.get("A2A_D1_ID") ? LEGACY_WORKER_NAME : "a2a-exposed");
+// Worker (and default D1) name: A2A_WORKER_NAME (saved by init), else a2a-exposed.
+export const workerName = () => C.get("A2A_WORKER_NAME") || "a2a-exposed";
 /** No custom hostname: the Worker is served on <worker>.<account subdomain>.workers.dev (and only there). */
 const workersDevMode = () => !C.get("A2A_HOSTNAME");
 export const publicBase = () =>
@@ -63,6 +75,9 @@ export const NODE_HELP = `How to get Node 22 (any one; no root needed):
   or the official installer / binaries: https://nodejs.org/en/download
 Then check: node --version   (v22.18.0 or newer)`;
 
+/** What to do when the Cloudflare login itself is blocked (printed with "not logged in"; the setup skill says the same). */
+export const LOGIN_403_HELP = `If \`cf auth login\` (or \`wrangler login\`) fails with "OAuth error: HTTP 403 Forbidden" or a "Just a moment..." page BEFORE any code is shown, that is Cloudflare's bot mitigation for datacenter / VPS IPs, not a wrong account: don't retry. Use an API token instead: export CLOUDFLARE_API_TOKEN (and CLOUDFLARE_ACCOUNT_ID) in the environment, never argv (setup skill, Troubleshooting: API token).`;
+
 /** Dies unless `version` (default: this Node) is 22.18+; the message says how to get it. */
 export function checkNode(version = process.versions.node) {
 	const [maj, min] = String(version).replace(/^v/, "").split(".").map(Number);
@@ -192,6 +207,10 @@ function applyFlags(o) {
 			die("--pbkdf2-iterations must be an integer from 50000 to 100000 (default 100000, the Workers maximum; lower it only if /device approvals hit Cloudflare error 1102, the CPU limit)");
 		upd.A2A_PBKDF2_ITERATIONS = String(n);
 	}
+	if (upd.A2A_MCP !== undefined) {
+		if (!["on", "off"].includes(upd.A2A_MCP)) die("--mcp must be on or off (the remote MCP server at /mcp that Claude and other MCP clients add as a connector; default on)");
+		upd.A2A_MCP = upd.A2A_MCP === "off" ? "off" : null;
+	}
 	if (upd.A2A_WORKERS_LOGS !== undefined) {
 		if (!["on", "off"].includes(upd.A2A_WORKERS_LOGS)) die("--workers-logs must be on or off (Cloudflare Workers Logs: persisted, searchable Worker logs; query strings redacted)");
 		upd.A2A_WORKERS_LOGS = upd.A2A_WORKERS_LOGS === "on" ? "1" : null;
@@ -199,7 +218,11 @@ function applyFlags(o) {
 	if (upd.WAKE_PRESET && !PRESETS.includes(upd.WAKE_PRESET)) die(`unknown preset ${upd.WAKE_PRESET} (${PRESETS.join(" | ")})`);
 	for (const [flag, key] of [["upstream", "A2A_UPSTREAM_URL"], ["upstream-card-url", "A2A_UPSTREAM_CARD_URL"]]) {
 		if (upd[key] === undefined) continue;
-		if (["", "none", "off"].includes(String(upd[key]).trim().toLowerCase())) { upd[key] = null; continue; }
+		if (["", "none", "off"].includes(String(upd[key]).trim().toLowerCase())) {
+			upd[key] = null;
+			if (key === "A2A_UPSTREAM_URL") upd.A2A_UPSTREAM_NO_TOKEN = null; // the opt-out belonged to that upstream
+			continue;
+		}
 		const why = upstreamUrlProblem(String(upd[key]).trim());
 		if (why) die(`--${flag} ${why}`);
 		upd[key] = new URL(String(upd[key]).trim()).href;
@@ -346,7 +369,9 @@ function deployedBase() {
 
 export async function init(o) {
 	checkNode();
+	const prevUpstream = C.fileConfig().A2A_UPSTREAM_URL || "";
 	const switched = applyFlags(o);
+	const upstreamSecrets = await upstreamTokenCheck(o, { upstreamChanged: (C.get("A2A_UPSTREAM_URL") || "") !== prevUpstream });
 	const dir = workerDir(o);
 	C.saveConfig({ A2A_WORKER_DIR: dir, A2A_WORKER_NAME: workerName() });
 	if (workersDevMode()) {
@@ -361,11 +386,15 @@ export async function init(o) {
 	const prof = cfProfile();
 	step(`checking Cloudflare login (cf auth whoami${prof ? ` --profile ${prof}` : ""})`);
 	const who = cfJson(dir, ["auth", "whoami"]);
-	if (!who.authenticated) die(prof
+	if (!who.authenticated) die((process.env.CLOUDFLARE_API_TOKEN
+		? "CLOUDFLARE_API_TOKEN is set but cf does not accept it (expired, revoked, or IP-restricted: an IP filter must allow both this host's IPv4 /32 and IPv6 /128). Check the token (setup skill, Troubleshooting: API token), then re-run init"
+		: prof
 		? `cf profile "${prof}" is not logged in: run \`npx cf auth create ${prof} --no-browser\`, open the printed URL, enter the code, then re-run init`
-		: "not logged in to Cloudflare: run `cf auth login --no-browser`, open the printed URL, enter the code, then re-run init");
+		: "not logged in to Cloudflare: run `cf auth login --no-browser`, open the printed URL, enter the code, then re-run init") + `\n${LOGIN_403_HELP}`);
 	const accts = who.accounts || [];
 	if (!C.get("CLOUDFLARE_ACCOUNT_ID")) {
+		if (!accts.length && process.env.CLOUDFLARE_API_TOKEN)
+			die("the API token can't list accounts: add the permission User -> Memberships -> Read (or pass --account-id <id> / export CLOUDFLARE_ACCOUNT_ID; the id is in the dashboard URL)");
 		if (accts.length !== 1) die(`${accts.length} accounts available; pass --account-id <id>:\n` + accts.map((a) => `  ${a.id}  ${a.name}`).join("\n"));
 		C.saveConfig({ CLOUDFLARE_ACCOUNT_ID: accts[0].id });
 	} else if (accts.length && !accts.some((a) => a.id === C.get("CLOUDFLARE_ACCOUNT_ID"))) {
@@ -391,30 +420,102 @@ export async function init(o) {
 	if (!ownerToken || o["rotate-owner-token"]) ownerToken = randomToken(32);
 	C.saveConfig({ A2A_OWNER_TOKEN: ownerToken, A2A_BASE_URL: publicBase() || undefined });
 
-	const secrets = { OWNER_TOKEN: ownerToken, ...deploySecretsFromEnv() };
+	const secrets = { OWNER_TOKEN: ownerToken, ...deploySecretsFromEnv(), ...upstreamSecrets };
 	step(`deploying (secrets uploaded: ${Object.keys(secrets).join(", ")})`);
 	await deployAndLearn(dir, secrets, o);
 	const base = deployedBase();
 	if (base) await verifyDeployedCard(base);
 	console.log(base);
 	reportSwitch(switched);
-	proxyNote();
+	proxyNote(secrets);
 	console.error(`config saved to ${C.CONFIG_FILE} (chmod 600). Next: a2a-exposed status (shows the next setup step)`);
 }
 
-/** Proxy / expose mode reminder after a deploy (the upstream credentials are secrets: only their presence is shown). */
-function proxyNote() {
+/** Proxy / expose mode reminder after a deploy (the upstream credentials are secrets: only their names are shown). */
+function proxyNote(secrets = {}) {
 	const up = C.get("A2A_UPSTREAM_URL");
 	if (!up) return;
-	const sent = UPSTREAM_SECRETS.filter((k) => process.env[k]);
+	const sent = UPSTREAM_SECRETS.filter((k) => k in secrets);
 	console.error(`proxy mode: authenticated A2A calls are forwarded to ${up}; the public card is the upstream's, rewritten to this deployment's URL.` +
-		` Upstream secrets uploaded now: ${sent.join(", ") || "none (existing ones kept)"}. Check the upstream and the card with: a2a-exposed status`);
+		` Upstream secrets uploaded now: ${sent.join(", ") || "none (existing ones kept)"}. Check the whole path (Access, the agent's bearer check) with: a2a-exposed status`);
+}
+
+/** stdin and stderr are a terminal (a human at the keyboard), and not CI: only then may setup prompt. */
+const interactive = () => !!(process.stdin.isTTY && process.stderr.isTTY && !process.env.CI);
+
+/** Proxy mode setup check: the façade must hold the bearer token the upstream agent checks (UPSTREAM_TOKEN) in addition
+ *  to the Cloudflare Access service token, which only gets the Worker through the tunnel. Returns extra secrets to
+ *  upload ({ UPSTREAM_TOKEN } when read from stdin or a hidden prompt), or dies with what to do. Never reads argv.
+ *  Order: --upstream-token-stdin / exported UPSTREAM_TOKEN (uploaded) > --no-upstream-token (saved opt-out) > the
+ *  Worker already holds one for this upstream, or the card it fetched declares no bearer > the upstream card fetched from
+ *  here (with the exported Access token): no bearer declared -> fine; bearer or unknown -> hidden prompt on a terminal,
+ *  else exit 1. */
+export async function upstreamTokenCheck(o, { upstreamChanged = false } = {}) {
+	const up = C.get("A2A_UPSTREAM_URL");
+	if (!up) return {};
+	if (o["upstream-token-stdin"] && o["no-upstream-token"]) die("--upstream-token-stdin and --no-upstream-token are mutually exclusive");
+	if (o["upstream-token-stdin"]) {
+		const t = (process.stdin.isTTY ? await readHidden("UPSTREAM_TOKEN, the bearer the upstream agent expects (not shown): ") : fs.readFileSync(0, "utf8")).trim();
+		if (!t) die("--upstream-token-stdin: no token on stdin");
+		C.saveConfig({ A2A_UPSTREAM_NO_TOKEN: null });
+		return { UPSTREAM_TOKEN: t };
+	}
+	if (process.env.UPSTREAM_TOKEN) { C.saveConfig({ A2A_UPSTREAM_NO_TOKEN: null }); return {}; } // uploaded with the other exported secrets
+	if (o["no-upstream-token"]) {
+		C.saveConfig({ A2A_UPSTREAM_NO_TOKEN: "1" });
+		console.error("note: --no-upstream-token: deploying without an upstream bearer token (saved; `status` warns if the upstream card asks for one)");
+		return {};
+	}
+	if (C.get("A2A_UPSTREAM_NO_TOKEN") === "1") return {};
+	// an existing façade for this upstream: the Worker's secrets persist across deploys, and it reads the card through Access
+	if (!upstreamChanged && C.get("A2A_BASE_URL") && C.get("A2A_OWNER_TOKEN")) {
+		try {
+			const r = await ownerTry("GET", "/owner/facade");
+			if (r.status === 200 && r.data && r.data.mode === "proxy") {
+				if (r.data.hasUpstreamToken) return {};
+				if (r.data.upstreamAuth && r.data.upstreamAuth.bearer === false) return {};
+			}
+		} catch { /* not deployed yet / unreachable: check the card from here */ }
+	}
+	const cardUrl = C.get("A2A_UPSTREAM_CARD_URL") || new URL("/.well-known/agent-card.json", up).href;
+	step(`checking which credential the upstream's agent card asks for (${cardUrl})`);
+	const { card, error } = await fetchUpstreamCard(cardUrl);
+	const auth = upstreamAuth(card);
+	if (auth.unsupported.length)
+		console.error(`warning: the upstream card requires ${auth.unsupported.join(", ")}; the façade only presents \`Authorization: Bearer <UPSTREAM_TOKEN>\` (plus the Access service token), so the agent may refuse it`);
+	if (auth.bearer === false) {
+		console.error(`upstream card: no bearer auth declared${auth.schemes.length ? ` (schemes: ${auth.schemes.join(", ")})` : ""}, so no UPSTREAM_TOKEN is needed`);
+		return {};
+	}
+	const why = auth.bearer
+		? `the upstream's agent card asks for a bearer token (${auth.schemes.join(", ")})`
+		: `the upstream's agent card could not be read from here (${error}), so whether the agent needs a bearer token is unknown`;
+	const access = "Cloudflare Access (UPSTREAM_ACCESS_CLIENT_ID / _SECRET) only lets the Worker through the tunnel; the agent checks its own token too";
+	if (interactive()) {
+		console.error(`${why}. ${access}.`);
+		const t = (await readHidden("UPSTREAM_TOKEN, the bearer the upstream agent expects (not shown; empty = the agent needs none): ")).trim();
+		if (t) { C.saveConfig({ A2A_UPSTREAM_NO_TOKEN: null }); return { UPSTREAM_TOKEN: t }; }
+		if (auth.bearer) die("no UPSTREAM_TOKEN given, but the upstream card asks for one: peers' calls would fail with HTTP 502. Re-run and enter it, or pass --no-upstream-token if the agent really accepts calls without it");
+		C.saveConfig({ A2A_UPSTREAM_NO_TOKEN: "1" });
+		console.error("note: deploying without an upstream bearer token (saved; check the whole path with `a2a-exposed status`)");
+		return {};
+	}
+	die(`${why}, and no UPSTREAM_TOKEN is set. ${access}, so without it every peer call fails with HTTP 502.\n` +
+		"  Provide it (never as an argument): `read -rs UPSTREAM_TOKEN && export UPSTREAM_TOKEN`, then re-run; or pipe it: <command that prints the token> | a2a-exposed " +
+		`${C.get("A2A_D1_ID") ? "deploy" : "init ..."} --upstream-token-stdin\n` +
+		"  The agent needs no bearer token? Re-run with --no-upstream-token (saved for later deploys).");
 }
 
 export async function deploy(o) {
 	checkNode();
 	if (!C.get("A2A_D1_ID")) die("no saved deployment; run `a2a-exposed init` first");
+	// init saves A2A_WORKER_NAME before it creates the D1 database, so a saved D1 without a name is a hand-edited config:
+	// refuse rather than guess, so a redeploy never creates a second Worker next to the one this config deployed.
+	if (!C.get("A2A_WORKER_NAME") && o["worker-name"] === undefined)
+		die(`${C.CONFIG_FILE} has a saved deployment (A2A_D1_ID) but no A2A_WORKER_NAME; rerun with --worker-name <the Worker it deployed> (saved for next time)`);
+	const prevUpstream = C.fileConfig().A2A_UPSTREAM_URL || "";
 	const switched = applyFlags(o);
+	const upstreamSecrets = await upstreamTokenCheck(o, { upstreamChanged: (C.get("A2A_UPSTREAM_URL") || "") !== prevUpstream });
 	const dir = workerDir(o);
 	if (workersDevMode() && !WD.LABEL_RE.test(workerName())) die("on workers.dev the worker name must be a DNS label (lowercase letters, digits, hyphens)");
 	guardTunnelUrl();
@@ -423,14 +524,14 @@ export async function deploy(o) {
 	if (!o["skip-install"]) run("npm", ["install", "--no-audit", "--no-fund", "--loglevel=error"], { cwd: dir });
 	const env = cfEnv();
 	applyMigrations(dir, env);
-	const secrets = deploySecretsFromEnv();
+	const secrets = { ...deploySecretsFromEnv(), ...upstreamSecrets };
 	if (Object.keys(secrets).length && C.get("A2A_OWNER_TOKEN")) secrets.OWNER_TOKEN = C.get("A2A_OWNER_TOKEN");
 	step(Object.keys(secrets).length ? `deploying (secrets uploaded: ${Object.keys(secrets).join(", ")})` : "deploying (existing secrets kept)");
 	await deployAndLearn(dir, secrets, o);
 	const base = deployedBase();
 	if (base) await verifyDeployedCard(base);
 	if (switched) { console.log(base); reportSwitch(switched); }
-	proxyNote();
+	proxyNote(secrets);
 }
 
 /** Fingerprints of the wake secrets in the local environment (what `wake set` would upload). */
@@ -472,6 +573,7 @@ export async function wake(sub, o) {
 			die("no wake webhook configured on the Worker: export WAKE_WEBHOOK_URL (and WAKE_WEBHOOK_KEY or WAKE_HMAC_SECRET), then run `a2a-exposed wake set` first (or use polling)");
 		console.log(JSON.stringify(r, null, 2));
 		if (!(r.status >= 200 && r.status < 300)) process.exitCode = 1;
+		else if (C.get("WAKE_PRESET") === "claude-code") console.error(CLAUDE_CODE_NOTE);
 		return;
 	}
 	if (sub === "set") {
@@ -480,7 +582,9 @@ export async function wake(sub, o) {
 		if (!Object.keys(secrets).length && !DEPLOY_FLAGS.some((f) => o[f] !== undefined))
 			die("nothing to set: export WAKE_WEBHOOK_URL / WAKE_WEBHOOK_KEY / WAKE_HMAC_SECRET and/or pass --preset etc.");
 		await deploy(o); // wake set = save settings + upload secrets + redeploy, in one step
-		return console.error("wake settings deployed. Next: a2a-exposed wake preview, then a2a-exposed wake test");
+		console.error("wake settings deployed. Next: a2a-exposed wake preview, then a2a-exposed wake test");
+		if (C.get("WAKE_PRESET") === "claude-code") console.error(CLAUDE_CODE_NOTE);
+		return;
 	}
 	if (sub === "unset") {
 		const dir = workerDir(o), name = workerName();

package/lib/main.mjs

@@ -16,13 +16,14 @@ const HELP = `a2a-exposed ${VERSION} - public A2A endpoint for any AI agent (Clo
 Usage: a2a-exposed <command> [options]        (or: npx a2a-exposed <command>)
 
 Setup (needs Node 22.18+, e.g. \`mise exec node@22 -- npx a2a-exposed ...\`, and a Cloudflare login:
-npx cf auth login --no-browser)
+npx cf auth login --no-browser; on a VPS where it fails with HTTP 403 before showing a code, export
+CLOUDFLARE_API_TOKEN instead: setup skill, Troubleshooting)
   init [--hostname <host> | --workers-dev [--workers-dev-subdomain NAME]]
        [--agent-name N] [--agent-description D] [--agent-skills JSON]
        [--provider-organization O --provider-url U] [--preset P] [--worker-name W] [--d1-name D]
        [--account-id ID] [--cf-profile NAME] [--cli-command CMD] [--debounce S] [--max-per-hour N]
-       [--pairing-approval human|agent|off] [--pbkdf2-iterations N] [--workers-logs on|off] [--cron]
-       [--upstream URL [--upstream-card-url URL]] [--worker-dir DIR]
+       [--pairing-approval human|agent|off] [--pbkdf2-iterations N] [--workers-logs on|off] [--mcp on|off] [--cron]
+       [--upstream URL [--upstream-card-url URL] [--upstream-token-stdin | --no-upstream-token]] [--worker-dir DIR]
                                 deploy the Worker + D1 to your account; wake secrets are read from
                                 env WAKE_WEBHOOK_URL / WAKE_WEBHOOK_KEY / WAKE_HMAC_SECRET (never argv)
                                 no --hostname: serve on https://<worker>.<account subdomain>.workers.dev
@@ -38,6 +39,8 @@ npx cf auth login --no-browser)
                                 --pbkdf2-iterations  approval-password hashing cost, 50000-100000 (default 100000,
                                                the Workers maximum; lower only if /device hits error 1102)
                                 --workers-logs on|off  persisted Cloudflare Workers Logs (query strings redacted)
+                                --mcp on|off   remote MCP server at <url>/mcp for Claude and other MCP clients
+                                               (default on; each client needs your approval password once)
                                 --upstream URL  proxy / expose mode: a public façade for an agent that already
                                                speaks A2A (JSON-RPC) on a private network. URL is its endpoint on
                                                a Cloudflare Tunnel hostname behind Access (never a Tailnet/LAN
@@ -48,6 +51,12 @@ npx cf auth login --no-browser)
                                 --upstream-card-url  the upstream's card (default <upstream origin>/.well-known/
                                                agent-card.json); must be on the --upstream origin (it is
                                                fetched with the upstream credentials)
+                                               Setup reads that card: unless it declares no bearer auth, the
+                                               façade needs UPSTREAM_TOKEN besides the Access token (Access only
+                                               gets the Worker through the tunnel). Without it: a hidden prompt
+                                               on a terminal, else exit 1 with what to do
+                                --upstream-token-stdin  read UPSTREAM_TOKEN from stdin (hidden prompt on a terminal)
+                                --no-upstream-token  the upstream needs no bearer token: skip that check (saved)
                                 --cli-command  command shown in wake hints (default "npx a2a-exposed";
                                                e.g. "node /path/to/repo/cli/bin/a2a-exposed.mjs")
                                 --worker-dir   where the Worker project (template copy) lives (default
@@ -79,9 +88,16 @@ anywhere on the account: the inbox itself can be on workers.dev or a custom host
 
 Status
   status [--json]               deployment, base URL, agent card check (fetched by the CLI: no curl needed), wake
-                                mode (webhook / tunnel / none = polling), tunnel state, proxy-mode upstream and
-                                card-leak check (--upstream), and the next step to run.
+                                mode (webhook / tunnel / none = polling), tunnel state, proxy mode (--upstream):
+                                upstream card, Access credential and upstream bearer configured (separately), the
+                                live upstream check, the last failed peer call, card-leak check; warnings for peer
+                                token variables shadowing saved tokens; and the next step to run.
                                 Read-only; run it after an interruption and continue from "next step". Exit 1 = broken
+  upstream verify [--json]      proxy mode: check the façade's whole path, layer by layer: façade peer auth
+                                (unauthenticated call -> 401), then the Worker calls the upstream with its stored
+                                secrets (never sent to the CLI) using a JSON-RPC method that doesn't exist (no task
+                                is created): Cloudflare Access, the agent's bearer check, the A2A app. Exit 1 unless
+                                the app answered. \`status\` runs the same check
   url                           print the public base URL (exit 1 if none is configured)
   config                        print config (secrets masked) and its location
 
@@ -119,14 +135,18 @@ Pairing (OAuth 2.0 device flow, RFC 8628: agents connect without pasting tokens
 Inbound peer tokens (one per peer label; paired agents get one too)
   token issue <label>     print a new token once (fails if the label is active); manual fallback to \`connect\`
   token rotate <label>    replace the label's token
-  token list | token revoke <label>        list shows how each token was created (pairing: code + date);
+  token list | token revoke <label>        list shows how each token was created (pairing: code + date)
+                                           and MCP connectors (label mcp-*); revoke works for both;
                                            revoke of an unknown label exits 1
 
 Outbound (agents you call)
   peers add <alias> <url> [--token-env VAR | --token-stdin]
   peers list | peers rm <alias>
+  peers sync [alias...] | peers unsync <alias>
+                          upload peers (URL + token, encrypted on the Worker) so the MCP connector can send to
+                          them; default: all peers. Re-run after connect, token changes or an owner-token rotation
                           a token variable set in the environment overrides config.env; when a peer token
-                          differs between the two, connect/send/poll/peers warn on stderr (values never shown)
+                          differs between the two, connect/send/poll/peers/status warn (values never shown)
   send --to <alias|url> [--text T | stdin] [--context C] [--task T] [--push] [--proto 0.3|1.0]
   poll --to <alias|url> <taskId> [--proto 0.3|1.0]
   outbound <taskId>       stored state of a task you sent (incl. pushed updates)
@@ -139,7 +159,7 @@ const S = { type: "string" }, B = { type: "boolean" };
 const tunnelOpts = { "tunnel-hostname": S, "tunnel-zone": S, "tunnel-origin": S, "tunnel-path": S, "show-token": B, "zero-trust-org": S, dir: S, "worker-dir": S };
 const deployOpts = {
 	...Object.fromEntries(dep.DEPLOY_FLAGS.map((f) => [f, S])), dir: S, "worker-dir": S, cron: B, "skip-install": B, "rotate-owner-token": B,
-	"workers-dev": B, "workers-dev-subdomain": S,
+	"workers-dev": B, "workers-dev-subdomain": S, "upstream-token-stdin": B, "no-upstream-token": B,
 };
 const SPEC = {
 	init: { ...deployOpts, ...tunnelOpts, tunnel: B }, deploy: deployOpts, wake: deployOpts, tunnel: tunnelOpts,
@@ -151,6 +171,7 @@ const SPEC = {
 	send: { to: S, text: S, context: S, task: S, push: B, proto: S },
 	poll: { to: S, proto: S },
 	status: { json: B },
+	upstream: { json: B },
 	connect: { alias: S, name: S, json: B, "no-wait": B, replace: B, force: B, "card-url": S },
 	pair: { json: B, web: B, ttl: S },
 };
@@ -188,6 +209,11 @@ export async function main(argv) {
 		case "tunnel": return tun.tunnel(need(p[0], "tunnel create|status|rm"), o);
 		case "deploy": return dep.deploy(o);
 		case "status": return st.status(o);
+		case "upstream": {
+			const sub = need(p[0], "upstream verify [--json]");
+			if (sub === "verify" || sub === "check") return st.upstreamVerify(o);
+			throw new CliError(`unknown upstream action ${sub} (verify)`);
+		}
 		case "wake": return dep.wake(p[0], o);
 		case "url": {
 			const u = cmd.baseUrl();

package/lib/pair.mjs

@@ -181,7 +181,7 @@ export function cardUrlToSend(flag, own, quiet = false) {
 	if (flag) {
 		let u;
 		try { u = new URL(flag); } catch { die(`--card-url must be a URL (your agent card, e.g. https://agent.example.com/.well-known/agent-card.json)`); }
-		if (u.protocol !== "https:" || u.username || u.password) { note(`note: --card-url ${u.origin} is not a plain https URL, so it is left out of the pairing request (inboxes accept only https cards)`); return ""; }
+		if (u.protocol !== "https:" || u.username || u.password) { note(`note: --card-url ${u.origin} is not a plain https URL, so it is left out of the pairing request (inboxes accept only public https cards). Peers can't call an agent there: to be reachable, expose it through a public façade (setup skill: "Already have A2A on a Tailnet or LAN") and pass the façade's card`); return ""; }
 		if (u.href.length > 300) { note("note: --card-url is longer than 300 characters, so it is left out of the pairing request"); return ""; }
 		if (isPrivateHost(u.hostname)) note(`note: ${u.hostname} is on a private network: the peer's owner sees the card as informational ("not publicly reachable"). Expose your agent through a public façade for others to reach it (setup skill: "Already have A2A on a Tailnet or LAN").`);
 		return u.href;
@@ -278,7 +278,9 @@ A different agent at the same URL? Pass another --alias.`);
 		const r = await postForm(ep.device, params, replace && oldToken ? oldToken : null);
 		if (r.status !== 200 || !r.data.device_code || !r.data.user_code) {
 			const why = r.data.error_description || r.data.error || `HTTP ${r.status}`;
-			die(r.status === 429 ? `${peerName} is not accepting more pairing requests right now: ${why}` : r.status === 404 ? `${peerName} has device-flow pairing disabled (${why}); ask its owner for a token` : `pairing request to ${peerName} failed: ${why}`);
+			const privateCard = !!card && (() => { try { return isPrivateHost(new URL(card).hostname); } catch { return false; } })();
+			die(r.status === 429 ? `${peerName} is not accepting more pairing requests right now: ${why}` : r.status === 404 ? `${peerName} has device-flow pairing disabled (${why}); ask its owner for a token`
+				: `pairing request to ${peerName} failed: ${why}${privateCard && r.status === 400 ? `. The card URL sent (${new URL(card).host}) is not publicly reachable, and inboxes may accept only public https cards: retry with --card-url set to a public card, or expose your agent through a public façade first (setup skill: "Already have A2A on a Tailnet or LAN")` : ""}`);
 		}
 		st = { base, alias, device: ep.device, token: ep.token, deviceCode: r.data.device_code, userCode: r.data.user_code,
 			verificationUri: r.data.verification_uri || "", verificationUriComplete: r.data.verification_uri_complete || r.data.verification_uri || "",