<span id="工作区mcp工具导入合同"></span>

# Workspace MCP tool import contract

<span id="选择工具"></span>

## 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.

<span id="附加描述符"></span>

## 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.

<span id="预演复用与恢复"></span>

## 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.
