APapicurio
Artifacts
AI

Import tools from an MCP server

Changed on

Experimental. Connects to a live MCP server over the Streamable HTTP transport, lists its tools with tools/list, and publishes each tool as an MCP_TOOL artifact. The artifact named in the path must be an MCP_SERVER; a new version of it references every imported tool whose definition is stored.

Each tool is published like any other version: configured rules, such as COMPATIBILITY, apply, and a tool rejected by a rule is reported as REJECTED with the violations, without changing what is stored. A tool whose definition is unchanged is reported as UNCHANGED. A tool referenced by the previous MCP_SERVER version but no longer listed by the server is reported as REMOVED; its artifact is left as it is. With dryRun, nothing is written and the same report is returned.

The registry connects only to hosts in apicurio.mcp-import.allowed-hosts, never to loopback, link-local or cloud metadata addresses, and does not follow redirects. Headers in the request are sent to the MCP server only; they are not stored, returned or logged.

This operation can fail for the following reasons:

  • The import feature is disabled, or the storage is read-only (HTTP error 409)
  • No artifact with this artifactId exists (HTTP error 404)
  • The artifact is not an MCP_SERVER, or the URL or its host is not allowed (HTTP error 400)
  • The MCP server could not be reached, timed out, sent a response that is too large or invalid, or listed too many tools (HTTP error 502)
  • A server error occurred (HTTP error 500)
post/groups/{groupId}/artifacts/{artifactId}/mcp-import

Request

  • The document declares no server URL.
  • Auth
    none declared

Request body

urlstring required

The MCP server endpoint, for the Streamable HTTP transport. Its host must be allowed by apicurio.mcp-import.allowed-hosts.

headersobject

HTTP headers to send to the MCP server, for example Authorization. Sent to the MCP server only: never stored, returned or logged.

toolGroupIdstring

The group to publish the MCP_TOOL artifacts in. Defaults to the group of the MCP_SERVER artifact.

dryRunboolean

When true, the server is contacted and the report is returned, but nothing is written.

Example request

{
  "url": "https://weather.apps.example.com/mcp",
  "toolGroupId": "mcp-tools",
  "dryRun": false
}

Response

The result of the import, for the server and for each tool.

groupIdstring

An ID of a single artifact group.

artifactIdstring

The ID of a single artifact.

versionstring

The MCP_SERVER version that references the imported tools. Absent when nothing was written.

status'CREATED' | 'NEW_VERSION' | 'UNCHANGED' | 'REJECTED' | 'REMOVED'

The outcome of an MCP import for one artifact.

  • CREATED - a new artifact was created
  • NEW_VERSION - a new version was added to an existing artifact
  • UNCHANGED - the stored version already matches
  • REJECTED - a rule rejected the new definition; nothing was stored
  • REMOVED - the tool was referenced by the previous server version but is no longer listed; its artifact is left as it is

Example response

{
  "groupId": "\"my-group\"",
  "artifactId": "\"example-artifact\"",
  "tools": [
    {
      "groupId": "\"my-group\"",
      "artifactId": "\"example-artifact\"",
      "causes": [
        {
          "description": "External documentation URL is not valid (it must be formatted as a URL).",
          "context": "/info/externalDocs[url]"
        }
      ]
    }
  ]
}

Changes