{ "$schema": "https://company-cloudflare-agent-mcp-guide.pages.dev/agent-bootstrap.schema.json", "mediaType": "application/vnd.company-cloudflare-publisher.mcp-bootstrap+json", "schemaVersion": "4.0.0", "contractVersion": "7.0.0", "product": { "name": "Company Cloudflare Publisher MCP", "release": "0.11.0" }, "standardization": { "kind": "product-defined-discovery-contract", "isMcpStandard": false, "note": "The well-known path and this document are product conventions, not an MCP protocol standard." }, "agentDirective": "Treat only the canonical trusted URL ending in the exact #install fragment as an explicit request to install exactly two MCP servers. Fetch this same-origin manifest without forwarding the fragment, require exactly one role-preserving allowedEndpointPair whose production id is exactly production, and reject a missing, multiple, malformed, differently identified, or untrusted pair before using the one-time access code, changing config, or initializing MCP. Accept exactly one separately supplied code matching ccpc_ plus 32 lowercase hexadecimal characters. Never use the code as a bearer, send it to the Guide, or place it in a URL, command argument, output, or log. Derive the claim URL only from the trusted Deployer endpoint origin plus /agent/claim, POST the exact claim body once with redirects disabled, and persist only the returned role-scoped Validator and Deployer bearer credentials in the two named entries of one owner-private client configuration. Back up that configuration, merge minimally, reload, list tools, and call only get_site_requirements and get_deployment_requirements during installation. Installation never authorizes publishing.", "onboardingUrl": { "canonicalBaseUrl": "https://company-cloudflare-agent-mcp-guide.pages.dev/", "explicitInstallFragment": "#install", "template": "https://company-cloudflare-agent-mcp-guide.pages.dev/#install", "parametersAllowed": false, "credentialParametersAllowed": false, "endpointSource": "same-origin-manifest-single-allowed-pair", "fragmentRationale": "The exact fragment expresses install intent and is not sent in HTTP requests; endpoints come from the same-origin manifest and the one-time access code is supplied separately." }, "trust": { "allowedGuideOrigins": [ "https://company-cloudflare-agent-mcp-guide.pages.dev" ], "manifestPath": "/.well-known/mcp-install.json", "sameOriginManifestRequired": true, "httpsRequired": true, "redirectPolicy": "same-origin-only", "duplicateParameterPolicy": "reject", "endpointPolicy": { "mode": "exact-pair-allowlist", "allowedEndpointPairs": [ { "id": "production", "validator": "https://validator.8-210-204-8.sslip.io/mcp", "deployer": "https://deployer.8-210-204-8.sslip.io/mcp" } ], "productionPairCardinality": "exactly-one", "productionPairId": "production", "pairMatch": "normalized-exact-validator-and-deployer", "unlistedEndpointPolicy": "stop-before-code-use-config-change-or-mcp-initialization", "allowLoopbackDevelopment": true, "loopbackGuideRequirement": "http-loopback-only", "loopbackEndpointRequirement": "single-configured-loopback-pair", "productionGuideMayUseLoopbackException": false }, "untrustedOriginPolicy": "show documentation only; do not install" }, "credentials": { "mode": "one-time-code-claim", "delivery": "explicit-user-install-input", "inputName": "accessCode", "codePattern": "^ccpc_[a-f0-9]{32}$", "codeDisplayForm": "ccpc_<32-lowercase-hex>", "oneUse": true, "expiresInSeconds": 1800, "neverUseCodeAsBearer": true, "neverPlaceInUrl": true, "neverSendToGuide": true, "neverEchoOrLog": true, "claim": { "urlDerivation": "trusted-deployer-origin-plus-path", "path": "/agent/claim", "method": "POST", "contentType": "application/json", "redirectPolicy": "reject-all", "bodyFields": [ "code", "client_id", "contract_version", "endpoint_pair_id" ], "contractVersion": "7.0.0", "additionalBodyFieldsAllowed": false }, "successResponse": { "status": 200, "requiredFields": [ "install_id", "validator_access_token", "deployer_access_token" ], "additionalFieldsAllowed": false, "installIdOpaque": true, "installIdPattern": "^[a-f0-9]{32}$", "validatorTokenPrefix": "ccpv_", "deployerTokenPrefix": "ccpd_", "validatorTokenPattern": "^ccpv_[a-f0-9]{48}$", "deployerTokenPattern": "^ccpd_[a-f0-9]{48}$", "tokenLifetimeSeconds": 7776000, "roleScoped": true, "revocable": true, "cacheControl": "no-store" }, "outputs": [ { "role": "validator", "responseField": "validator_access_token", "templatePlaceholder": "{{validatorAccessToken}}", "requiredPrefix": "ccpv_", "requiredPattern": "^ccpv_[a-f0-9]{48}$" }, { "role": "deployer", "responseField": "deployer_access_token", "templatePlaceholder": "{{deployerAccessToken}}", "requiredPrefix": "ccpd_", "requiredPattern": "^ccpd_[a-f0-9]{48}$" } ], "failurePolicy": { "ambiguousOutcome": "treat-code-as-consumed-stop-and-request-new-code", "invalidOrExpiredCode": "stop-and-request-new-code", "unexpectedUsedCode": "stop-revoke-associated-install-if-identifiable-and-escalate", "sameCodeRetryAllowed": false, "directBearerFallbackAllowed": false }, "persistence": "owner-private-client-config-only", "requiredConfigProtection": "0600-on-posix-or-user-only-equivalent", "missingInputPolicy": "stop before changing client configuration and ask for exactly one one-time MCP access code", "operatorStaticCredentialsSuppliedToAgent": false, "migrationRequiresReOnboarding": true, "oauthMigration": "replace claimed role credentials with client-native OAuth login without changing the install URL or MCP roles" }, "servers": [ { "name": "company-cloudflare-validator", "role": "validator", "endpointPairKey": "validator", "transport": "streamable-http", "authCredential": "validatorAccessToken", "required": true, "toolTimeoutSeconds": 900, "firstCall": "get_site_requirements", "expectedTools": [ "get_site_requirements", "check_site_readiness", "create_input_upload", "validate_site", "get_validation_result" ] }, { "name": "company-cloudflare-deployer", "role": "deployer", "endpointPairKey": "deployer", "transport": "streamable-http", "authCredential": "deployerAccessToken", "required": true, "toolTimeoutSeconds": 900, "firstCall": "get_deployment_requirements", "expectedTools": [ "get_deployment_requirements", "create_credential_input", "get_credential_input_status", "check_deployment_readiness", "plan_deployment", "deploy_proposal", "get_deployment_status", "verify_basic_auth", "plan_rollback", "rollback_proposal" ] } ], "supportedClients": [ { "id": "codex", "label": "Codex", "detectionCommands": [ [ "codex", "--version" ] ], "configLocations": [ "~/.codex/config.toml" ], "installStrategy": "private-structured-config-merge-with-distinct-role-static-headers", "installArgv": [], "credentialPersistence": { "strategy": "owner-private-static-header", "requiredProtection": "0600-on-posix-or-user-only-equivalent", "nativeOAuthStoreUsed": false, "limitation": "Codex has no documented interface for importing custom claimed bearers into its native OAuth credential store; this interim configuration keeps both role tokens as static headers in the private config.toml." }, "configTemplate": { "format": "toml", "content": "[mcp_servers.company-cloudflare-validator]\nurl = \"{{validatorUrl}}\"\nhttp_headers = { Authorization = \"Bearer {{validatorAccessToken}}\" }\nrequired = true\ntool_timeout_sec = 900\n\n[mcp_servers.company-cloudflare-deployer]\nurl = \"{{deployerUrl}}\"\nhttp_headers = { Authorization = \"Bearer {{deployerAccessToken}}\" }\nrequired = true\ntool_timeout_sec = 900" }, "verifyArgv": [ [ "codex", "mcp", "list" ] ], "reload": "Run the non-JSON list command, restart Codex or start a new session, then call both requirements tools to prove connectivity." }, { "id": "claude", "label": "Claude Code", "detectionCommands": [ [ "claude", "--version" ] ], "configLocations": [ "~/.claude.json" ], "installStrategy": "private-structured-config-merge-with-distinct-role-static-headers", "installArgv": [], "credentialPersistence": { "strategy": "owner-private-static-header", "requiredProtection": "0600-on-posix-or-user-only-equivalent", "nativeOAuthStoreUsed": false, "limitation": "Claude Code stores these custom claimed bearers as static headers in the private user configuration; its secure native OAuth storage is used only by a later client-native OAuth flow." }, "configTemplate": { "format": "json", "content": "{\n \"mcpServers\": {\n \"company-cloudflare-validator\": {\n \"type\": \"http\",\n \"url\": \"{{validatorUrl}}\",\n \"headers\": { \"Authorization\": \"Bearer {{validatorAccessToken}}\" },\n \"timeout\": 900000\n },\n \"company-cloudflare-deployer\": {\n \"type\": \"http\",\n \"url\": \"{{deployerUrl}}\",\n \"headers\": { \"Authorization\": \"Bearer {{deployerAccessToken}}\" },\n \"timeout\": 900000\n }\n }\n}" }, "verifyArgv": [ [ "claude", "mcp", "list" ] ], "reload": "Approve trusted project MCP configuration when applicable, then run /mcp or start a new Claude Code session." }, { "id": "hermes", "label": "Hermes", "detectionCommands": [ [ "hermes", "--version" ] ], "configLocations": [ "~/.hermes/config.yaml" ], "installStrategy": "private-structured-config-merge-with-distinct-role-static-headers", "installArgv": [], "credentialPersistence": { "strategy": "owner-private-static-header", "requiredProtection": "0600-on-posix-or-user-only-equivalent", "nativeOAuthStoreUsed": false, "limitation": "Hermes supports environment substitution, but this zero-dependency interim template keeps claimed tokens in the owner-private YAML; native 0600 mcp-tokens storage applies only to OAuth credentials." }, "configTemplate": { "format": "yaml", "content": "mcp_servers:\n company-cloudflare-validator:\n url: \"{{validatorUrl}}\"\n headers:\n Authorization: \"Bearer {{validatorAccessToken}}\"\n timeout: 900\n company-cloudflare-deployer:\n url: \"{{deployerUrl}}\"\n headers:\n Authorization: \"Bearer {{deployerAccessToken}}\"\n timeout: 900" }, "verifyArgv": [ [ "hermes", "mcp", "list" ] ], "reload": "After the non-secret list shows both entries, start a new Hermes session and call both requirements tools to prove connectivity." }, { "id": "openclaw", "label": "OpenClaw", "detectionCommands": [ [ "openclaw", "--version" ] ], "configLocations": [ "~/.openclaw/openclaw.json" ], "installStrategy": "private-structured-config-merge-with-distinct-role-static-headers", "installArgv": [], "credentialPersistence": { "strategy": "owner-private-static-header", "requiredProtection": "0600-on-posix-or-user-only-equivalent", "nativeOAuthStoreUsed": false, "limitation": "OpenClaw warns about literal sensitive headers and its structured SecretRef surface does not cover claimed MCP headers in this contract; the interim tokens remain in owner-private openclaw.json until native OAuth migration." }, "configTemplate": { "format": "json5", "content": "{\n mcp: {\n servers: {\n \"company-cloudflare-validator\": {\n url: \"{{validatorUrl}}\",\n transport: \"streamable-http\",\n headers: { Authorization: \"Bearer {{validatorAccessToken}}\" },\n requestTimeoutMs: 900000\n },\n \"company-cloudflare-deployer\": {\n url: \"{{deployerUrl}}\",\n transport: \"streamable-http\",\n headers: { Authorization: \"Bearer {{deployerAccessToken}}\" },\n requestTimeoutMs: 900000\n }\n }\n }\n}" }, "verifyArgv": [ [ "openclaw", "mcp", "list" ] ], "reload": "After the non-JSON list shows both entries, reload MCP or restart the Gateway, then call both requirements tools to prove connectivity." } ], "credentialInput": { "mode": "trusted-deployer-origin-url", "createTool": "create_credential_input", "createArguments": [ "projectName" ], "statusTool": "get_credential_input_status", "statusArguments": [ "projectName", "credentialRef" ], "requiredStatus": "captured", "pageUrl": { "originRule": "exact-configured-deployer-endpoint-origin", "path": "/credential-input/", "queryAllowed": false, "fragmentRequired": true, "exactFragmentParameters": [ "projectName", "credentialRef", "submissionToken" ], "credentialsEnteredOnlyOnPage": true }, "reference": { "opaque": true, "requiredBy": [ "get_credential_input_status", "check_deployment_readiness", "plan_deployment", "deploy_proposal" ], "neverReplaceWithRawCredentialFields": true }, "privacy": { "neverAskForCredentialsInChat": true, "neverSendCredentialsInMcpArguments": true, "neverReadOrLogSubmissionToken": true, "passwordReturnedByMcp": false } }, "recovery": { "statusProbe": { "tool": "get_deployment_status", "arguments": [ "projectName" ], "requiredBeforeValidatorRenewal": true, "purpose": "branch-selection-only", "receiptReturned": false, "outcomes": { "STATUS_NOT_FOUND": "allow-same-finalized-claim-and-artifact-receipt-renewal", "matchingNonterminalExactReceipt": "use-retained-original-accepted-receipt", "operatorRequired": "stop-and-escalate-to-operator", "missingOrInvalidRecoveryMode": "stop-and-escalate-to-operator", "SERVICE_UNAVAILABLE": "retry-status-later-or-escalate-no-renewal", "otherError": "retry-status-later-or-escalate-no-renewal", "stable": "stop-and-escalate-to-operator", "mismatched": "stop-and-escalate-to-operator", "malformed": "stop-and-escalate-to-operator" } }, "beforeDeployerNonterminal": { "condition": "status-not-found-and-credential-page-or-receipt-expired", "retainExact": [ "projectName", "inputRef", "finalizedClaim", "artifact" ], "renewReceipt": { "tool": "validate_site", "arguments": [ "projectName", "inputRef" ], "sameFinalizedClaimOnly": true, "sameArtifactOnly": true }, "newCredentialInput": { "tool": "create_credential_input", "arguments": [ "projectName" ] }, "then": [ "capture-new-credential-ref", "repeat-readiness", "repeat-plan", "display-changes", "obtain-new-explicit-confirmation" ], "newUploadAllowed": false, "newProjectNameAllowed": false }, "afterDeployerNonterminal": { "condition": "matching-project-and-artifact-nonterminal-with-recovery-mode-exact-receipt", "requiredRecoveryMode": "exact-receipt", "exactProjectMatchRequired": true, "exactArtifactMatchRequired": true, "ambiguousConfirmationResponseMayBeLost": true, "receiptSource": "retained-original-accepted-receipt", "receiptRetainedBy": "agent-workflow", "persistedReceiptRequired": true, "replaceReceiptAllowed": false, "validatorRenewalAllowed": false, "newCredentialRefOnlyIfNeeded": true, "then": [ "repeat-readiness", "repeat-plan", "display-changes", "obtain-new-explicit-confirmation" ], "newUploadAllowed": false, "newProjectNameAllowed": false }, "unsafeStatus": { "states": [ "stable", "mismatched", "malformed" ], "action": "stop-and-escalate-to-operator" }, "statusError": { "states": [ "SERVICE_UNAVAILABLE", "otherError" ], "renewalAllowed": false, "credentialInputAllowed": false, "action": "retry-status-later-or-escalate-to-operator" }, "recoveryModeGate": { "receiptReuseMode": "exact-receipt", "exactProjectMatchRequired": true, "exactArtifactMatchRequired": true, "blockedValues": [ "operator-required", "missing", "invalid" ], "blockedAction": "stop-and-escalate-to-operator" } }, "topologyEvidence": { "customDomainAbsenceVerifiedByRuntime": true, "workerRoutesEnumeratedByRuntime": false, "workerRouteAbsence": "administrator-controlled-assumption", "reasonRoutesAreNotEnumerated": "Deployer intentionally has no Zone permission", "agentMustNotClaimWorkerRouteAbsenceWasVerified": true }, "rollback": { "planTool": "plan_rollback", "planArguments": [ "projectName" ], "planReadOnly": true, "planResult": { "currentRequired": true, "displayExactCurrentArtifactAndDeploymentState": true, "candidatesRecordedOnly": true, "candidateRequiredFields": [ "rollbackTargetId", "artifactId", "deployedAt", "confirmationId" ] }, "selection": { "userSelectsExactCandidate": true, "autoSelectAllowed": false, "omittedTargetAllowed": false }, "confirmation": { "separateExplicitConfirmationRequired": true, "displayBeforeConfirmation": [ "current", "selectedCandidate" ], "invalidatedBy": [ "project_change", "current_state_change", "selected_candidate_change", "confirmation_id_change" ] }, "executeTool": "rollback_proposal", "executeArguments": [ "projectName", "rollbackTargetId", "confirmationId" ] }, "installationWorkflow": [ { "step": 1, "action": "validate-onboarding-url", "rule": "Require a trusted allowedGuideOrigin, the exact #install marker, no fragment parameters, no URL credentials, and the guide root path. Stop before using the one-time code, changing config, or initializing MCP when trust fails." }, { "step": 2, "action": "fetch-and-validate-manifest", "rule": "Fetch manifestPath from the original guide origin without forwarding the URL fragment. Reject cross-origin redirects or an unsupported schemaVersion, then require exactly one role-preserving normalized endpoint pair. For the canonical HTTPS Guide its id must equal production; any other id stops before code use. Non-production ids are permitted only for an explicitly trusted HTTP loopback development Guide." }, { "step": 3, "action": "detect-client-and-code", "rule": "Prefer the current Agent's native supported client and never configure more than one client. If identity is ambiguous and multiple clients are installed, ask which single client to use. Require exactly one explicit accessCode matching ccpc_ plus 32 lowercase hexadecimal characters without repeating, logging, persisting, or sending it to the Guide. The code is a 30-minute one-use claim input and must never be used as an MCP bearer." }, { "step": 4, "action": "plan-and-back-up", "rule": "Show the chosen client, the two non-secret endpoints, the claim origin and path without the code, target config location, entries to add or replace, backup path, and the client's static-header persistence limitation. Before consuming the code, create any backup with owner-private protection and prove the target config and secret-bearing backup can be protected as 0600 on POSIX or user-only equivalent. Abort on unrelated config conflicts or inability to enforce protection." }, { "step": 5, "action": "claim-role-credentials", "rule": "After trust validation and backup, derive the exact claim URL from the trusted Deployer endpoint origin plus /agent/claim. POST once with no redirect and the strict JSON body {code,client_id,contract_version,endpoint_pair_id}. Accept only a no-store 200 response whose JSON object contains exactly an opaque install_id matching ^[a-f0-9]{32}$, a validator_access_token matching ^ccpv_[a-f0-9]{48}$, and a deployer_access_token matching ^ccpd_[a-f0-9]{48}$. An ambiguous response consumes the code: stop and request a new code. An unexpectedly used code requires revocation of any identifiable associated install and operator escalation. Never retry the same code, use it as a bearer, or fall back to a direct or operator static bearer." }, { "step": 6, "action": "install-and-verify-read-only", "rule": "Use a format-aware merge, preserve unrelated settings, and persist each returned bearer only in its matching named Authorization header. Enforce owner-private permissions before the first secret-bearing write and fail closed if they cannot be enforced. Keep the config and any secret-bearing backup owner-private. Reload the client, initialize both servers, compare tool names with expectedTools, and call only each server's firstCall. Do not create an upload or call any Cloudflare mutation." }, { "step": 7, "action": "rollback-on-install-failure", "rule": "Remove only entries added during this attempt or restore the verified owner-private backup. Revoke any claimed install when its identifier is safely available, never reuse the one-time code, report a redacted actionable error, and leave all unrelated configuration unchanged." } ], "operationWorkflow": { "validator": [ "get_site_requirements", "create_input_upload", "one-time HTTPS PUT", "check_site_readiness", "validate_site" ], "deployer": [ "get_deployment_requirements", "create_credential_input with projectName", "user enters credentials only at the exact trusted Deployer-origin /credential-input/ URL", "get_credential_input_status with projectName and credentialRef until captured", "check_deployment_readiness", "plan_deployment", "explicit confirmation of the displayed plan", "deploy_proposal", "get_deployment_status until active when directed" ], "finalRule": "Only an active deploy_proposal response may return access.url plus access.basicAuth.username and access.basicAuth.status=captured. The password remains out of band and must never be requested or returned through MCP, status, errors, or logs." }, "confirmationGate": { "required": true, "neverSatisfiedByInstallRequest": true, "neverSatisfiedByUrgencyWords": true, "scope": [ "projectName", "authMode", "derivedHostname", "derivedPublicPath", "derivedPublicUrl", "artifactId", "artifactDigest", "planNoOpState", "receipt", "credentialRef", "credentialInputStatus", "capturedUsername", "confirmationId" ], "invalidatedBy": [ "project_change", "source_change", "artifact_change", "receipt_change", "derived_target_change", "plan_state_change", "credential_reference_change", "credential_input_status_change", "captured_username_change", "confirmation_id_change" ] }, "successCriteria": [ "A missing, multiple, malformed, unlisted, role-swapped, or non-production-identified production endpoint pair stops before code use, client configuration changes, claim exchange, or MCP initialization. The canonical HTTPS pair id is exactly production.", "Exactly one supported client was changed and all unrelated configuration was preserved.", "The 30-minute one-use ccpc_ access code is sent exactly once only in the strict claim JSON body, is never used as a bearer, and never appears in the onboarding URL, Guide request, rendered examples, command argv, logs, config, or command output.", "The successful claim returns a 90-day revocable Validator token matching ^ccpv_[a-f0-9]{48}$ and a Deployer token matching ^ccpd_[a-f0-9]{48}$. Each appears only in its matching named entry of one owner-private client config and never in the other role.", "Fresh installation receives only claimed role credentials; it never receives, requests, or falls back to any shared or operator break-glass static credential. Migration requires re-onboarding with a new code.", "Both servers initialize, expected tools are present, and both requirements calls succeed.", "No upload, validation, deployment, Basic Auth verification, or rollback occurs during installation.", "For publishing, create_credential_input returns the only permitted trusted credential page, get_credential_input_status is captured before readiness, and no raw username or password enters MCP arguments.", "Ambiguous expiry recovery first calls get_deployment_status only to select a branch; status never returns a receipt. Only explicit STATUS_NOT_FOUND permits the exact original projectName and inputRef to renew the same finalized claim and artifact receipt. SERVICE_UNAVAILABLE or any other error forbids renewal and credential input; retry status later or escalate. A nonterminal may use the exact original accepted signed receipt retained by the Agent workflow only when project and artifact match exactly and server-authoritative recoveryMode is exact-receipt. operator-required, missing, or invalid recoveryMode, and stable, mismatched, or malformed state stop and escalate. No branch creates a new upload or project name.", "An active response returns URL, username, and status=captured, never the password." ], "limitations": [ "The installing Agent and its conversation provider can observe the user-supplied one-time code. Claimed role tokens are persisted as static Authorization headers because these four clients do not expose one common custom-token credential-store import; client configuration and secret-bearing backups must be treated as secrets.", "Operator static credentials are out-of-band break-glass controls and are never supplied to an Agent. Existing Agent installations must be replaced by re-onboarding with a new one-time code; there is no direct-bearer downgrade path. Client-native OAuth is not yet implemented.", "An ambiguous claim response burns the code and requires a new one. An unexpectedly used code stops automation, triggers revocation of any identifiable associated install, and escalates to an operator.", "Runtime verifies that the only Worker Custom Domain attached to the script is the operator-declared publishing hostname, which Cloudflare must report as attached, but does not enumerate Worker routes because Deployer has no Zone permission. Route absence is an administrator-controlled assumption and must not be reported as runtime-verified.", "Every published project has a distinct user-selected Basic Auth credential, but every project still shares one workers.dev browser origin; path authentication does not isolate DOM, cookies, storage, service workers, or same-origin requests.", "The project credential is entered only on the exact trusted Deployer-origin credential page. MCP readiness, plan, and deploy tools accept only credentialRef; the password is never returned by MCP.", "The installing agent needs local permission to inspect the client, back up its config, and change only the two named entries.", "A base documentation URL without the exact #install fragment is not installation authorization." ], "resources": { "humanGuide": "/", "machineManifest": "/.well-known/mcp-install.json", "schema": "/agent-bootstrap.schema.json", "agentInstructions": "/agent-instructions.md", "intentContract": "/agent-trigger.json", "llmsText": "/llms.txt" } }