UCP Gateway

register ucp profile

register_ucp_profile

Register a public hosted UCP agent profile and receive agent_id/profile_url. Default path: send agent_name plus public_key_jwk and the gateway builds the canonical UCP profile with default Shopping capabilities. Re-registering the same public_key_jwk in the same namespace is idempotent and returns the existing agent_id. Do not build a capability map for normal registration. Create local ./.ucpgateway/ files; keep private_key.jwk local and save returned agent_id/profile_url/profile_json to ./.ucpgateway/agent.json.

Input Schema

TableJSON Schema

Name	Required	Description
`metadata`	No	Optional public metadata for the generated profile, such as homepage or runtime. Do not include secrets, tokens, passwords, payment data, private keys, or buyer PII; server-owned fields are overwritten.
`namespace`	No	Public profile namespace for hosted UCP profiles. Usually 'openclaw'; use lowercase letters, numbers, underscores, or hyphens.
`agent_name`	Yes	Human-readable public agent name, max 120 characters.
`skill_name`	No	Optional public skill/package name, e.g. 'ucp-gateway-skill'.
`description`	No	Optional public agent description, max 500 characters.
`profile_json`	No	Advanced/legacy only. Public UCP profile JSON for callers that already know the full UCP profile format. Normal SKILL.md-only agents should omit profile_json and send public_key_jwk instead; the gateway builds default Shopping capabilities. If supplied, profile_json must contain ucp.version, ucp.capabilities using exact supported keys (dev.ucp.shopping.catalog.search, dev.ucp.shopping.catalog.lookup, dev.ucp.shopping.catalog, dev.ucp.shopping.cart, dev.ucp.shopping.checkout), ucp.payment_handlers, and only public signing_keys. 'shopping' and 'dev.ucp.shopping' are invalid shorthand. Never include private JWK fields d, p, q, dp, dq, qi, or k.
`skill_version`	No	Optional public skill/package version, e.g. '0.2.0'.
`public_key_jwk`	No	Default registration public key. Send an EC P-256 public JWK object (kty='EC', crv='P-256', x, y, optional kid/alg/use). Never include private JWK fields d, p, q, dp, dq, qi, or k; keep private_key.jwk local.

Output Schema

TableJSON Schema

Name	Required	Description
`ok`	Yes	True for successful tool execution; false for structured tool errors.
`error`	No	Structured tool error.
`created`	No	True when a new profile row was created; false when an existing active profile was reused for this namespace and public key fingerprint.
`message`	Yes	Human-readable result summary or recovery message.
`profile`	No	Hosted public UCP profile JSON. Contains only public key material; private keys must stay local.
`agent_id`	No	Registered UCP Gateway UUID. Save it to ./.ucpgateway/agent.json and include it in every Shopping tool call.
`namespace`	No	Public profile namespace for hosted UCP profiles. Usually 'openclaw'; use lowercase letters, numbers, underscores, or hyphens.
`next_step`	Yes	Recommended next step. Suggestions are non-binding and never authorize payment or state-changing actions.
`profile_url`	No	Hosted public UCP profile JSON URL for this agent.
`profile_json`	No	Hosted public UCP profile JSON. Contains only public key material; private keys must stay local.
`registry_url`	No	Public registry page URL.
`gateway_mcp_url`	No	Canonical UCP Gateway MCP endpoint URL to save in ./.ucpgateway/agent.json.
`existing_profile`	No	True when registration was idempotent and returned an existing active profile without creating a new row.

TDQS

A4.6/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description discloses key behaviors beyond the annotations: idempotency on re-registration, creation of local files (.ucpgateway/), and privacy warnings (keep private_key.jwk local). It also explains the two registration paths with different requirements. There is no contradiction with annotations (readOnlyHint=false, destructiveHint=false).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise (four sentences) and front-loaded with the core purpose. However, it could be improved by breaking the two registration modes into separate sections for clarity. The current block format is dense but still efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite complexity (8 params, nested objects, two registration modes), the description covers outcomes (returns agent_id/profile_url), file handling, idempotency, and security. An output schema exists, so return value details are structured elsewhere. The description provides sufficient context for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% description coverage, so baseline is 3. The description adds value by explaining the relationship between parameters (e.g., oneOf for public_key_jwk vs profile_json) and reinforcing security guidance (never include private JWK fields). This integration of schema and description enhances understanding.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Register a public hosted UCP agent profile and receive agent_id/profile_url.' It specifies two registration modes (default and advanced/legacy) and distinguishes itself from sibling tools like get_ucp_profile by focusing on creation rather than retrieval.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides usage guidance such as 'Do not build a capability map for normal registration' and notes idempotency for re-registration. However, it does not explicitly compare with sibling tools or state when not to use this tool, leaving some ambiguity.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All UCP Gateway tools Inspect

Try in Browser

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A3.8/5.0

Disambiguation5/5

Each tool has a clearly distinct purpose, targeting either UCP profile management or shopping operations (cart, checkout, product). Within the shopping domain, actions are separated by object type (cart vs checkout) and operation (create, get, update, cancel), leaving no ambiguity.

Naming Consistency5/5

All tools follow a consistent snake_case pattern with verb_noun structure (e.g., get_ucp_profile, shopping_cart_create, shopping_product_search). The naming convention is uniform across profile and shopping tool groups.

Tool Count5/5

With 12 tools, the server is well-scoped for its domain. It provides a focused set covering profile registration, cart and checkout lifecycle, and product search without being overwhelming or insufficient.

Completeness4/5

The tool set covers the core shopping flow (cart CRUD, checkout CRUD, product lookup) and profile registration. A minor gap is the absence of profile update or deletion, but registration is idempotent and deletion may be out of scope. Overall, no critical missing operations.

Resources

Need Help?