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.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedJun 9, 2026

addedOutput schema / properties / gateway_mcp_url

Added value: +{
+  "description": "Canonical UCP Gateway MCP endpoint URL to save in ./.ucpgateway/agent.json.",
+  "type": "string"
+}

Changed10 schema fields changedJun 7, 2026

changedInput schema / description

Previous value: -"Arguments for registering a hosted UCP profile."New value: +"Arguments for registering a hosted UCP profile. Provide public_key_jwk for default registration, or profile_json for advanced legacy registration, but not both."

addedInput schema / oneOf

Added value: +[
+  {
+    "description": "Default registration: agent_name + public_key_jwk; the gateway builds the canonical UCP profile and default Shopping capabilities.",
+    "required": [
+      "public_key_jwk"
+    ]
+  },
+  {
+    "description": "Advanced/legacy registration: agent_name + a full public UCP profile_json with exact supported capability keys.",
+    "required": [
+      "profile_json"
+    ]
+  }
+]

addedInput schema / properties / metadata

Added value: +{
+  "additionalProperties": true,
+  "description": "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.",
+  "properties": {},
+  "required": [],
+  "type": "object"
+}

changedInput schema / properties / profile_json / description

Previous value: -"Public UCP profile JSON. Must contain ucp.version, supported ucp.capabilities, and only public signing_keys; never include private JWK fields."New value: +"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."

addedInput schema / properties / public_key_jwk

Added value: +{
+  "additionalProperties": true,
+  "description": "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.",
+  "properties": {},
+  "required": [],
+  "type": "object"
+}

changedInput schema / properties / skill_version / description

Previous value: -"Optional public skill/package version, e.g. '0.1.0'."New value: +"Optional public skill/package version, e.g. '0.2.0'."

changedInput schema / required

Previous value: -[
-  "agent_name",
-  "profile_json"
-]New value: +[
+  "agent_name"
+]

changedOutput schema / properties / agent_id / description

Previous value: -"Registered UCP Gateway UUID. Save it and include it in every Shopping tool call."New value: +"Registered UCP Gateway UUID. Save it to ./.ucpgateway/agent.json and include it in every Shopping tool call."

addedOutput schema / properties / created

Added value: +{
+  "description": "True when a new profile row was created; false when an existing active profile was reused for this namespace and public key fingerprint.",
+  "type": "boolean"
+}

addedOutput schema / properties / existing_profile

Added value: +{
+  "description": "True when registration was idempotent and returned an existing active profile without creating a new row.",
+  "type": "boolean"
+}

First observedJun 5, 2026

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

Context Every Agent Can ShareAgents share what they learn, hand off work, and keep it when you switch models. Start with 5 GB free.fulcradynamics.comAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?