damonzucconi-mcp

Remote MCP server for managing damonzucconi.com through its GraphQL API.

Production endpoint: https://damonzucconi-mcp.damonzucconi.workers.dev/mcp

The server is one stateless Cloudflare Worker with no storage bindings. A static bearer token protects the MCP endpoint. The Worker signs into the GraphQL API with the existing admin credentials and caches the resulting JWT until shortly before expiry.

It exposes tools for artworks, exhibitions, tags, nested entities, and ordering. Artwork and exhibition deletion are intentionally unavailable; perform those manually.

Local development

Requires Node.js 20+ and npm.

npm install
cp .dev.vars.example .dev.vars

Set the three secrets in .dev.vars:

openssl rand -hex 32

MCP_AUTH_TOKEN=<paste-generated-value>
ADMIN_USERNAME=your-api-admin-username
ADMIN_PASSWORD=your-api-admin-password

MCP_AUTH_TOKEN is a shared secret, not a username or login token. The Worker stores one copy and each MCP client sends the same value as a bearer token. Possession of this value grants access to the server.

There is no automatic synchronization:

• .dev.vars supplies the local Worker and is the source used by npm run secrets:push.

• npm run secrets:push copies the value to Cloudflare's encrypted Worker secrets for production.

• Cursor and ChatGPT read that same value from the client-side environment variable DAMONZUCCONI_MCP_TOKEN.

If you change MCP_AUTH_TOKEN, run npm run secrets:push, update DAMONZUCCONI_MCP_TOKEN, and restart the client. A client using a different value will receive 401 Unauthorized.

npm run codegen
npm run typecheck
npm run dev

The local MCP endpoint is http://127.0.0.1:8787/mcp. In another terminal:

npm run smoke

To test production instead:

MCP_URL=https://damonzucconi-mcp.damonzucconi.workers.dev npm run smoke

Connect from Cursor

Add this to .cursor/mcp.json for this project or ~/.cursor/mcp.json globally:

{
  "mcpServers": {
    "damonzucconi": {
      "url": "https://damonzucconi-mcp.damonzucconi.workers.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${env:DAMONZUCCONI_MCP_TOKEN}"
      }
    }
  }
}

Set DAMONZUCCONI_MCP_TOKEN in the environment Cursor inherits, using the same value as MCP_AUTH_TOKEN in .dev.vars, then restart Cursor. Remote servers do not support envFile.

Connect from ChatGPT desktop

The ChatGPT desktop app shares MCP configuration with Codex in ~/.codex/config.toml. Add:

[mcp_servers.damonzucconi]
url = "https://damonzucconi-mcp.damonzucconi.workers.dev/mcp"
bearer_token_env_var = "DAMONZUCCONI_MCP_TOKEN"
default_tools_approval_mode = "writes"

On macOS, make the token available to apps launched from Finder or the Dock:

read -s "DAMONZUCCONI_MCP_TOKEN?MCP token: "
echo
launchctl setenv DAMONZUCCONI_MCP_TOKEN "$DAMONZUCCONI_MCP_TOKEN"
unset DAMONZUCCONI_MCP_TOKEN

Paste the same value as MCP_AUTH_TOKEN when prompted by read. The token is not written to config.toml or shell history.

Fully quit and reopen ChatGPT, then open Settings → MCP servers and select Restart. Type /mcp in the composer to confirm that damonzucconi is connected. See OpenAI's MCP documentation if the desktop UI changes.

Deploy

Wrangler authentication opens a browser:

npx wrangler login

For a first deployment:

npm run deploy
npm run secrets:push

secrets:push uploads the three entries from .dev.vars. On later deployments, run only npm run deploy unless a secret changed.

Before deploying changes:

npm run codegen
npm run typecheck
npm run smoke
npm run deploy
MCP_URL=https://damonzucconi-mcp.damonzucconi.workers.dev npm run smoke

GraphQL code generation

Queries and mutations live in src/graphql/. npm run codegen introspects the GraphQL schema and refreshes:

• schema.graphql

• src/generated/

Do not edit generated files. If codegen or type checking fails after an API change, update the .graphql operations or their Zod tool schemas before deploying.

By default codegen reads https://api.damonzucconi.com/graph. Override that with a local schema file or endpoint when the production schema is behind:

GRAPHQL_SCHEMA=http://127.0.0.1:3000/graph npm run codegen
GRAPHQL_SCHEMA=../damonzucconi-api/schema.graphql npm run codegen