Workspace MCP tool import contract

Select tools

Candidates merge published enabled API services in the current workspace, request-attached descriptors, and product API descriptors in that order, keeping the first of each name. Published services must be ready, dynamic_service, enabled, uniquely named, and have a published version identifier. The catalog is not the current tool-instance list.

Omitted/null/[] tool_names selects all candidates. A nonempty array selects exact trimmed names, deduplicates candidates, and ignores unknown names. A nonempty array containing only whitespace names may select zero items. Preview first, then explicitly select importable items such as api_service. Importing product_api rejects the entire selection before creation.

Attached descriptors

Field

Type

Description

tools[].name

string

Candidate name; use server preview names for regular tasks.

tools[].description

string

Optional description.

tools[].inputSchema

object

JSON Schema with camelCase keys. Do not put credentials in defaults.

tools[]._meta

object

Optional metadata; client-supplied ui blocks are removed.

tools[]._meta.origin

string

Source identifier. Manually providing a source does not bypass actual execution privileges.

node_id, version, and workflow_id are internal descriptor fields and are not currently decoded from JSON bodies. Client-supplied ui cannot select a page. Valid page URIs come from server-published services. Server discovery remains available without tools. This endpoint does not probe arbitrary external MCP URLs or create them in bulk.

Preview, reuse, and recovery

dry_run=true does not create tools, refresh existing page metadata, or update agent bindings. It still performs discovery, reads existing tools, and checks authorization. Previews may include existing tool IDs; new candidates may lack tool_id. dry_run defaults to false. An empty body or null does not guarantee preview, and unknown body keys are not strictly rejected by contract.

Actual import creates or reuses same-named tools individually. Matching names do not prove identical schemas, sources, or states. When an imported API service identity matches, reimport may refresh or remove publisher-managed mcp_app metadata while retaining other user settings. Unrelated same-named tools are not overwritten merely because of reimport.

API service tools resolve the currently published service by name at call time, without pinning a node ID or version. The tool-level endpoint does not bind agents. The agent-level endpoint appends bindings for nonempty tool_id values after import. The response is not binding details, and binding failures have no common saved_tool_ids receipt. Retain preview selections, then read current tools and target bindings after errors/timeouts to check actual writes before retrying.

Product API rejection occurs before item writes, but this does not imply every failure rolls back everything. Per-tool writes and subsequent bindings have no common outer transaction. Later-item failures, concurrent name collisions, and binding failures all require reading again.

Last updated on