Skip to content
Latest

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:

Terminal window
node scripts/generate-mcp-keys.js --output /private/path/vizzly-mcp.env

The 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=true
MCP_ORIGIN=https://app.example.com
VariablePurpose
MCP_JWKSPersistent private signing keys as a JSON Web Key Set, with distinct key IDs
MCP_COOKIE_KEYSJSON array of persistent cookie secrets, each at least 32 characters
MCP_ENCRYPTION_KEYExactly 32 bytes encoded as base64, for encrypted provider storage
MCP_CLIENTSOptional 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:

PathPurpose
/mcpRemote HTTP MCP resource
/oauthOAuth issuer
/.well-known/oauth-protected-resource/mcpProtected-resource metadata
/.well-known/oauth-authorization-server/oauthAuthorization-server metadata
/oauth/.well-known/openid-configurationProvider discovery
/oauth/authorizeAuthorization endpoint
/oauth/tokenToken endpoint
/oauth/revokeToken revocation endpoint
/oauth/jwksPublic 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.