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 |
|---|---|---|
|
string |
Candidate name; use server preview names for regular tasks. |
|
string |
Optional description. |
|
object |
JSON Schema with camelCase keys. Do not put credentials in defaults. |
|
object |
Optional metadata; client-supplied ui blocks are removed. |
|
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.