Import Providers

Endpoint

POST /api/import/providers

Imports provider configurations with their associated tools and parameters. Uses upsert logic to create new providers or update existing ones based on the code field.

Request Body

root

array

required

Array of provider objects to import

Show Provider Object

name

string

required

Human-readable name of the API provider

code

string

required

Unique identifier for the provider. If a provider with this code exists, it will be updated; otherwise, a new provider is created.

baseUrl

string

required

Base URL for all API requests to this provider

authenticationType

enum

required

Authentication method: API_KEY, BEARER_TOKEN, BASIC_AUTH, NONE

apiKeyLocation

enum

Where to send the API key: HEADER, QUERY_PARAM, IN_BODY

apiKeyName

string

Name of the authentication header/parameter (e.g., “Authorization”, “x-api-key”)

apiKeyValue

string

The actual API key value. Values equal to <YOUR_API_KEY> or empty strings are skipped and will not update existing keys.

isDynamicAuth

boolean

default:"false"

Whether this provider uses dynamic authentication (token refresh)

dynamicAuthUrl

string

URL endpoint for obtaining fresh authentication tokens

dynamicAuthMethod

enum

default:"POST"

HTTP method for dynamic auth: GET, POST, PUT, PATCH, DELETE

dynamicAuthPayloadType

enum

default:"JSON"

Format of auth payload: JSON, FORM_DATA, XML

dynamicAuthPayloadLocation

enum

default:"BODY"

Where to send auth payload: BODY, QUERY_PARAMS, HEADERS

dynamicAuthPayload

string

Template for authentication request payload. Use placeholders like {"identifier":"user","password":"pass"}

dynamicAuthTokenExtractionPath

string

JSONPath expression to extract the token from auth response (e.g., “accessJwt”, “data.token”)

dynamicAuthInvalidationKeywords

string

Comma-separated keywords that trigger token refresh

customHeaders

object

Key-value pairs of custom HTTP headers to include in all requests

tools

array

required

Array of tool configurations for this provider

Show Tool Object

name

string

required

Human-readable tool name

code

string

required

Unique identifier for the tool. Used for upsert logic.

description

string

required

Description of what the tool does (shown to AI agents via MCP)

endpointPath

string

required

API endpoint path (appended to provider baseUrl). Supports path parameters like /repos/{owner}/{repo}

httpMethod

enum

required

HTTP method: GET, POST, PUT, PATCH, DELETE

parameters

array

Array of parameter definitions for this tool

Show Parameter Object

name

string

required

Parameter name

type

enum

required

Parameter type: STRING, NUMBER, BOOLEAN, OBJECT, ARRAY

description

string

Human-readable description of the parameter’s purpose

required

boolean

default:"false"

Whether this parameter is mandatory

defaultValue

string

Default value if not provided by the user

Upsert Behavior

The import endpoint uses code-based upsert logic:

Providers

If code matches an existing provider → Update the existing provider
If code does not exist → Create a new provider
If code is missing or blank → Generate a new UUID and create a provider

Tools

Tools follow the same code-based upsert pattern
Existing tool parameters are cleared and replaced with the imported parameters
This ensures clean updates without orphaned parameters

Parameters

Parameters are always recreated with fresh UUIDs to avoid database conflicts
Old parameters are removed when updating a tool

API Key Handling

API key values are processed with special logic for security:

Values equal to <YOUR_API_KEY> → Skipped (preserves existing key)
Empty or blank values → Skipped (preserves existing key)
Valid API key values → Encrypted and stored

This allows you to import exported configurations without exposing or overwriting production API keys.

Response

Returns a success message when the import completes.

message

string

Confirmation message: "Import successful"

Error Handling

The import process validates all data before persisting. Common errors include:

Missing required fields: Provider name, code, baseUrl, authenticationType
Invalid enum values: Unsupported HTTP methods or authentication types
Malformed JSON: Invalid customHeaders structure
Database constraints: Duplicate codes (should not occur with upsert logic)

Cache Refresh

After a successful import, the tool cache is automatically refreshed. This ensures that:

MCP clients immediately see the new/updated tools
No server restart is required
Changes are reflected in the next tools/list call

Example Request

curl -X POST http://localhost:8080/api/import/providers \
  -H "Content-Type: application/json" \
  -d @providers.json

Full Example Payload

[
  {
    "name": "Tavily AI Search",
    "code": "tavily",
    "baseUrl": "https://api.tavily.com",
    "authenticationType": "API_KEY",
    "apiKeyLocation": "IN_BODY",
    "apiKeyName": "api_key",
    "apiKeyValue": "<YOUR_API_KEY>",
    "isDynamicAuth": false,
    "customHeaders": {
      "Content-Type": "application/json"
    },
    "tools": [
      {
        "name": "Búsqueda Tavily",
        "code": "tavily-search",
        "description": "Realiza una búsqueda impulsada por IA optimizada para obtener respuestas y fuentes precisas.",
        "endpointPath": "/search",
        "httpMethod": "POST",
        "parameters": [
          {
            "name": "api_key",
            "type": "STRING",
            "description": "Clave API de Tavily (requerida en el cuerpo de la petición).",
            "required": true,
            "defaultValue": ""
          },
          {
            "name": "query",
            "type": "STRING",
            "description": "La consulta de búsqueda a procesar.",
            "required": true,
            "defaultValue": ""
          },
          {
            "name": "search_depth",
            "type": "STRING",
            "description": "Profundidad de búsqueda ('basic' o 'advanced').",
            "required": false,
            "defaultValue": "basic"
          },
          {
            "name": "include_images",
            "type": "BOOLEAN",
            "description": "Si se deben incluir imágenes en los resultados (true/false).",
            "required": false,
            "defaultValue": ""
          }
        ]
      }
    ]
  },
  {
    "name": "Bluesky API",
    "code": "bluesky",
    "baseUrl": "https://bsky.social/xrpc",
    "authenticationType": "BEARER_TOKEN",
    "apiKeyLocation": "HEADER",
    "apiKeyName": "Authorization",
    "apiKeyValue": "",
    "isDynamicAuth": true,
    "dynamicAuthUrl": "https://bsky.social/xrpc/com.atproto.server.createSession",
    "dynamicAuthMethod": "POST",
    "dynamicAuthPayloadType": "JSON",
    "dynamicAuthPayloadLocation": "BODY",
    "dynamicAuthPayload": "{\"identifier\":\"your_handle.bsky.social\",\"password\":\"your_app_password\"}",
    "dynamicAuthTokenExtractionPath": "accessJwt",
    "dynamicAuthInvalidationKeywords": "ExpiredToken,AuthenticationRequired",
    "customHeaders": {},
    "tools": [
      {
        "name": "Ver Timeline",
        "code": "bluesky-timeline",
        "description": "Obtiene las últimas publicaciones del feed de inicio del usuario autenticado en Bluesky.",
        "endpointPath": "/app.bsky.feed.getTimeline",
        "httpMethod": "GET",
        "parameters": [
          {
            "name": "limit",
            "type": "NUMBER",
            "description": "Cantidad de posts a recuperar (ej. 10)",
            "required": false,
            "defaultValue": "10"
          }
        ]
      }
    ]
  }
]

Example Response

{
  "message": "Import successful"
}

Import from Export

You can directly import the output from the export endpoint:

# Step 1: Export from source instance
curl http://source-server:8080/api/export/providers > export.json

# Step 2: Update API keys in export.json if needed
# Replace <YOUR_API_KEY> placeholders with real values

# Step 3: Import to target instance
curl -X POST http://target-server:8080/api/import/providers \
  -H "Content-Type: application/json" \
  -d @export.json

API Keys Are Not Exported
The export endpoint masks all API keys as <YOUR_API_KEY>. You must manually add real API keys to the JSON before importing, or the import will preserve existing keys (or skip if creating new providers).

Validation Notes

All required fields must be present
Enum values must match exactly (case-sensitive)
customHeaders must be a valid JSON object
isDynamicAuth defaults to false if omitted
dynamicAuthInvalidationKeywords defaults to standard keywords if omitted
Parameter types must be valid: STRING, NUMBER, BOOLEAN, OBJECT, ARRAY

Side Effects

Database Changes: Creates or updates provider, tool, and parameter records
Tool Cache Refresh: All MCP tool caches are invalidated and rebuilt
Timestamps: createdAt set for new records, updatedAt set for all records
Encryption: Valid API keys are encrypted using the configured encryption service
Exportable Flag: All imported providers are marked as exportable = true

MCP Endpoints

Admin API

Task Memory API

Import/Export API

Import Providers

Endpoint

Request Body

Upsert Behavior

Providers

Tools

Parameters

API Key Handling

Response

Error Handling

Cache Refresh

Example Request

Full Example Payload

Example Response

Import from Export

Validation Notes

Side Effects

Build docs developers (and LLMs) love

MCP Endpoints

Admin API

Task Memory API

Import/Export API

​Endpoint

​Request Body

​Upsert Behavior

​Providers

​Tools

​Parameters

​API Key Handling

​Response

​Error Handling

​Cache Refresh

​Example Request

​Full Example Payload

​Example Response

​Import from Export

​Validation Notes

​Side Effects

Build docs developers (and LLMs) love

Endpoint

Request Body

Upsert Behavior

Providers

Tools

Parameters

API Key Handling

Response

Error Handling

Cache Refresh

Example Request

Full Example Payload

Example Response

Import from Export

Validation Notes

Side Effects