Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

fix(mcp): require avatars:write for mint_3d_asset and generate_garment unless the caller paid the per-call x402 price

nirholas43ad38907ed6
diff --git a/api/_mcp/dispatch.js b/api/_mcp/dispatch.js
index 4f6d0c2dd..66d44e7a4 100644
--- a/api/_mcp/dispatch.js
+++ b/api/_mcp/dispatch.js
@@ -61,6 +61,16 @@ export function isPublicTool(name) {
return PUBLIC_TOOLS.has(name);
}
+/**
+ * A scoped tool needs the scope on the caller's token. An x402 principal has no
+ * account, so a priced tool they paid for per call is the one case that stands
+ * in for the scope: the payment is the authorization.
+ */
+export function toolScopeSatisfied(tool, auth, name) {
+ if (!tool.scope || hasScope(auth.scope, tool.scope)) return true;
+ return auth.source === 'x402' && auth.x402Paid === true && Boolean(priceFor(name));
+}
+
export const PROTOCOL_VERSION = '2025-06-18';
const SERVER_INFO = { name: '3d-agent-mcp', version: '1.0.0' };
const log = logger('mcp');
@@ -198,7 +208,7 @@ async function onToolCall(params, auth, started, req) {
const gate = await gateCall(POLICY_SERVER, name, sentArgs, auth, req, declaredArgs(CATALOG_BY_NAME.get(name)));
if (!gate.ok) return gate.result;
const args = gate.args === sentArgs ? rawArgs : gate.args;
- if (tool.scope && !hasScope(auth.scope, tool.scope)) {
+ if (!toolScopeSatisfied(tool, auth, name)) {
throw rpcError(-32002, `insufficient scope, requires ${tool.scope}`);
}
// Defense-in-depth: validate args against the tool's inputSchema before
diff --git a/api/_mcp/tools/garments.js b/api/_mcp/tools/garments.js
index 83b05e616..da6d5ada2 100644
--- a/api/_mcp/tools/garments.js
+++ b/api/_mcp/tools/garments.js
@@ -40,6 +40,7 @@ function workerConfig() {
export const toolDefs = [
{
name: 'generate_garment',
+ scope: 'avatars:write',
title: 'Generate a wearable garment from a text prompt',
annotations: {
readOnlyHint: false,
diff --git a/api/_mcp/tools/tokenize.js b/api/_mcp/tools/tokenize.js
index 85bc67b9b..5408841dd 100644
--- a/api/_mcp/tools/tokenize.js
+++ b/api/_mcp/tools/tokenize.js
@@ -31,6 +31,7 @@ export async function unpaidMintLimited(network, auth) {
export const toolDefs = [
{
name: 'mint_3d_asset',
+ scope: 'avatars:write',
title: 'Mint a 3D asset as a Solana NFT',
// Creates an on-chain Core NFT. Not destructive (it mints, never deletes),
// and idempotent: the claim-first guard means repeating a call with the
diff --git a/tests/mcp-write-tool-scope.test.js b/tests/mcp-write-tool-scope.test.js
new file mode 100644
index 000000000..3d8a31de6
--- /dev/null
+++ b/tests/mcp-write-tool-scope.test.js
@@ -0,0 +1,33 @@
+// Tools that write (mint an NFT, generate a garment) must demand avatars:write
+// from a session or key. Only a caller who paid the per-call x402 price may
+// stand in without the scope.
+
+import { describe, it, expect } from 'vitest';
+import { toolDefs as tokenizeDefs } from '../api/_mcp/tools/tokenize.js';
+import { toolDefs as garmentDefs } from '../api/_mcp/tools/garments.js';
+import { toolScopeSatisfied } from '../api/_mcp/dispatch.js';
+
+const byName = (defs, n) => defs.find((d) => d.name === n);
+
+describe('write tools declare a scope', () => {
+ it('mint_3d_asset and generate_garment require avatars:write', () => {
+ expect(byName(tokenizeDefs, 'mint_3d_asset').scope).toBe('avatars:write');
+ expect(byName(garmentDefs, 'generate_garment').scope).toBe('avatars:write');
+ });
+});
+
+describe('toolScopeSatisfied', () => {
+ const tool = { scope: 'avatars:write' };
+ it('rejects a read-only key', () => {
+ expect(toolScopeSatisfied(tool, { source: 'api_key', scope: 'avatars:read' }, 'mint_3d_asset')).toBe(false);
+ });
+ it('accepts a key holding the scope', () => {
+ expect(toolScopeSatisfied(tool, { source: 'api_key', scope: 'avatars:write' }, 'mint_3d_asset')).toBe(true);
+ });
+ it('accepts an x402 caller who paid the priced tool', () => {
+ expect(toolScopeSatisfied(tool, { source: 'x402', scope: '', x402Paid: true }, 'mint_3d_asset')).toBe(true);
+ });
+ it('rejects an x402 caller who has not paid per call', () => {
+ expect(toolScopeSatisfied(tool, { source: 'x402', scope: '' }, 'mint_3d_asset')).toBe(false);
+ });
+});