Host the MCP server
MCP is off by default. Deploy the MCP release and run its database migrations before enabling it. For client setup, use Connect with MCP.
Generate and save keys
Run this once from your local Vizzly app checkout:
node scripts/generate-mcp-keys.js --output /private/path/vizzly-mcp.envThe script writes a private file (0600) and won’t overwrite one. Copy MCP_JWKS, MCP_COOKIE_KEYS,
and MCP_ENCRYPTION_KEY into your deployment’s secret store, without the shell quotes. It doesn’t
upload them for you. Don’t commit the file. Reuse the keys across deploys so connections keep working.
Set these alongside the keys and make sure your deployment passes them to the app:
MCP_ENABLED=trueMCP_ORIGIN=https://app.example.com| Variable | Purpose |
|---|---|
MCP_JWKS | Persistent private signing keys as a JSON Web Key Set, with distinct key IDs |
MCP_COOKIE_KEYS | JSON array of persistent cookie secrets, each at least 32 characters |
MCP_ENCRYPTION_KEY | Exactly 32 bytes encoded as base64, for encrypted provider storage |
MCP_CLIENTS | Optional JSON array of pre-registered OAuth client metadata; defaults to [] |
Set MCP_ORIGIN to your trusted public origin, without a path. Use HTTPS outside loopback
development. Every web instance needs the same PostgreSQL database and keys. Missing or invalid
keys stop the app from starting when MCP is enabled.
Back up the database and encryption key together. Changing that key without migrating the data breaks connections. Keep previous signing and cookie verification keys during rotation. Turning MCP off keeps connection data; valid connections can work again with the same database and keys.
Register a client
Vizzly supports Client ID Metadata Documents (CIMD). The client ID is a public HTTPS URL serving metadata with exact redirect URIs. Private addresses, redirects, oversized responses, and requests Vizzly can’t safely check are rejected.
You can also pre-register clients with an OAuth metadata array in MCP_CLIENTS. Public desktop
clients use authorization code with S256 PKCE; don’t put client secrets in them. Dynamic client
registration isn’t enabled.
Check discovery and proxy routing
All endpoints share the configured origin:
| Path | Purpose |
|---|---|
/mcp | Remote HTTP MCP resource |
/oauth | OAuth issuer |
/.well-known/oauth-protected-resource/mcp | Protected-resource metadata |
/.well-known/oauth-authorization-server/oauth | Authorization-server metadata |
/oauth/.well-known/openid-configuration | Provider discovery |
/oauth/authorize | Authorization endpoint |
/oauth/token | Token endpoint |
/oauth/revoke | Token revocation endpoint |
/oauth/jwks | Public signing keys |
Keep request headers and streaming responses intact through your trusted proxy. Use the configured origin for OAuth URLs, not arbitrary forwarded headers. MCP checks Host, Origin, CORS, bearer tokens, and body size. It accepts MCP OAuth tokens, not browser cookies or project tokens.
Verify access and renewal
Connect a client, read an allowed build, view an image, and refresh its token. Check that read-only connections have no write tools and disconnecting stops access. Only test comments or decisions when you want to save them. See token refresh for renewal rules.
Monitor refresh failures, permission denials, response times, and sizes. Keep tokens, authorization codes, PKCE verifiers, and images out of logs. Access is checked on every request. Retried writes use command IDs; comment emails use best-effort delivery.