Hosting PORTAGE_AGENT_PROFILE¶
Real UCP servers (confirmed live against Shopify's 2026-08-25 rollout)
require every catalog/cart/checkout call to carry a meta.ucp-agent.profile
URL, and fetch it themselves before answering. An unreachable or malformed
profile fails closed — profile_unreachable / profile_malformed, both
before the call's own shape is even considered (see
portage-ucp-client/lib/portage/ucp/client/transports/http.rb). This is a
document describing this agent, distinct from /.well-known/ucp (see
well-known-ucp.md), which describes a business.
Generating one¶
cd portage-cli
bundle exec exe/portage generate agent-profile \
--out ../portage-cli/agent-profile/agent-profile.json \
--key-out ../portage-cli/agent-profile/agent-profile.key.pem
Commit the --out JSON. Never commit --key-out — it's covered by the
root .gitignore's *.key.pem pattern. Nothing in this repo signs outbound
requests with that key yet (Portage::Ucp::Security::Signature only
verifies inbound ones); it's published now so keys isn't empty
and so a future signer has a kid to sign under without reshaping the
document again.
Then, once the commit is on main: bundle exec rake agent_profile:purge.
With this repo's jsdelivr default (see below) that's not optional — skip
it and the CDN keeps serving the previous document to every real UCP
server for up to a week, which looks exactly like the generator never ran.
Rotating¶
bundle exec exe/portage generate agent-profile --rotate \
--out ../portage-cli/agent-profile/agent-profile.json \
--key-out ../portage-cli/agent-profile/agent-profile.key.pem
--rotate keeps every kid already published and adds one more, so a
request signed under the outgoing key keeps verifying while callers move to
the new one. Nothing here ever drops a key — retire an old entry by hand
once nothing signs with it any more.
Same as above: commit, then bundle exec rake agent_profile:purge.
Hosting requirements¶
Whatever serves this document, live UCP servers reject anything that doesn't satisfy every one of these (from the 2026-08-25 spec):
- HTTPS, reachable with no prior coordination
- No 3xx redirects on the exact URL — not even http→https or a trailing-slash bounce
Cache-Control: public, max-age=<60 or more; neverprivate,no-store, orno-cacheapplication/json
This repo's default: jsdelivr, hand-published¶
There is no CI workflow publishing this document — .github/workflows/
was removed entirely (commit 9669621, "Drop GitHub Actions workflows"). An
earlier revision of this doc described
.github/workflows/publish-agent-profile.yml redeploying
agent-profile.json to GitHub Pages on every push to main; that workflow
never actually deployed anything (Pages Source was never flipped to
"GitHub Actions" — see "One-time setup" below) and no longer exists at all.
Treat any reference to it elsewhere (old commit messages, cached docs) as
historical, not current behavior.
The actual default, and what .env.example's PORTAGE_AGENT_PROFILE
points at, is jsdelivr's GitHub CDN mirror serving the checked-in
portage-cli/agent-profile/agent-profile.json directly — no build step,
no redeploy step, nothing to keep running:
Same checked-in JSON, no Pages build required. Do not point this at
raw.githubusercontent.com — confirmed live against billabong.com's real
Shopify UCP store (2026-09-17): raw.githubusercontent.com serves this exact
path as Content-Type: text/plain; charset=utf-8, which a strict UCP server
rejects (profile_malformed, surfaced by portage-ucp-client as a generic
"tools/call request is unprocessable" 422 with an empty body — there's no
in-band signal pointing at content-type, so check the profile URL's headers
by hand with curl -I if you see that error). jsdelivr serves the same file
as application/json with no redirect and Cache-Control: public,
max-age=604800, and was confirmed live past the agent-profile check on the
same store. GitHub's CDN caching on jsdelivr/raw file serving isn't a
documented guarantee the way GitHub Pages's is — switch to Pages (see
below) if that ever matters more than the zero-setup jsdelivr default.
Purge jsdelivr after every change to agent-profile.json. That
max-age=604800 applies to the @main alias, so for up to a week after a
profile change the CDN keeps handing servers the old document. The failure
that produces is not a cosmetic staleness — it is the Tool not found
registry miss §42 is about, reproducing against correct code in the repo.
Confirmed 2026-09-22, days after the capability-id fix landed and was pushed
to main: raw.githubusercontent.com served the per-action ids while
cdn.jsdelivr.net/gh/...@main/... still served the coarse
dev.ucp.shopping.catalog with services: []. One command fixes it:
(agent_profile:purge is now an alias for rake jsdelivr:purge[agent_profile] — the same
task also purges known-stores/{stores,products}.json, the other file this repo publishes
over the same @main channel; see buy-skill-and-local-browser.md
Phase 2c. Run rake jsdelivr:purge with no argument to purge everything at once.)
Pinning @<full-sha> instead of @main avoids the whole class of problem —
jsdelivr treats a sha path as immutable and can't serve a stale one — at the
cost of updating .env.example on every profile change. Either is fine; what
isn't fine is assuming a push to main is live.
Switching to GitHub Pages instead (avoids the purge step above, at the
cost of standing up a deploy path there's no workflow to run automatically
now — every agent-profile.json change needs its own manual Pages
deploy): Settings → Pages → Build and deployment → Source = "GitHub
Actions", then set:
Any other host that meets the requirements above works too — GitHub Pages is just what this repo would run without asking anyone to stand up separate infrastructure, if a workflow existed to drive it.
Resolved: Tool not found on every call once the profile is wired up¶
The profile was the cause after all, contrary to what this section said between 2026-09-17 and 2026-09-22. It is not a platform allowlist. The capability identifiers the profile declared were wrong, and a UCP server resolves an agent's tool registry from exactly those.
Catalog is registered per action — dev.ucp.shopping.catalog.search and
dev.ucp.shopping.catalog.lookup — not as one coarse
dev.ucp.shopping.catalog. AgentProfile declared the coarse name (it
reused Portage::Ucp::Capabilities::CATALOG.name, which is correct for
our own server's manifest, where one Capability object owns all three
catalog actions). A profile declaring only the coarse name resolves to zero
catalog tools, and the server answers search_catalog with -32602 Tool not
found: search_catalog — seconds after tools/list advertised it, with
nothing in the error pointing at the profile. Versions were "1" where the
registry uses spec revisions, and services was left {}, which declares
an agent that speaks no service at all.
Verified live 2026-09-22 against catalog.shopify.com/api/ucp/mcp and two
per-shop endpoints, anonymously — no Dev Dashboard token, no signatures, no
approval of any kind:
- profile declaring
dev.ucp.shopping.catalog.search/.lookup→search_catalogreturns real products - profile declaring coarse
dev.ucp.shopping.catalog→Tool not found: search_catalog, same endpoint, same connection - no profile →
invalid_profile_url; unreachable profile →profile_unreachable
The get_order tell that this section previously read as proof of an
allowlist is something narrower: Orders genuinely does require a Dev
Dashboard token carrying read_global_api_orders, so it is forbidden at the
anonymous tier no matter what the profile says. Catalog, Cart and Checkout
build/edit tools are all available at that tier per
Shopify's own auth tiers.
Reading one capability's real permission error as the explanation for
another capability's registry miss is what sent the whole investigation down
the allowlist path.
The one thing that is gated case-by-case is complete_checkout, which
needs both checkout permission on a token and the merchant having your
agent's channel enabled. continue_url — a link the shopper finishes in the
store's own checkout — is the supported path without it, and every cart and
checkout response carries one.
What this means: the fix was in this client. See
ucp-tool-gating-investigation.md for
the full trail, including the localization-context bug found underneath this
one.