Bulk Import Tools¶
The MCP Gateway provides a bulk import endpoint for efficiently loading multiple tools in a single request, perfect for migrations, environment setup, and team onboarding.
Configuration Options
This feature is controlled by several environment variables:
MCPGATEWAY_BULK_IMPORT_ENABLED=true
- Enable/disable the endpoint (default: true)MCPGATEWAY_BULK_IMPORT_MAX_TOOLS=200
- Maximum tools per batch (default: 200)MCPGATEWAY_BULK_IMPORT_RATE_LIMIT=10
- Requests per minute limit (default: 10)
π Overview¶
The bulk import feature allows you to register multiple tools at once through both the Admin UI and API, providing:
- Per-item validation - One invalid tool won't fail the entire batch
- Detailed reporting - Know exactly which tools succeeded or failed
- Rate limiting - Protected against abuse (10 requests/minute)
- Batch size limits - Maximum 200 tools per request
- Multiple input formats - JSON payload, form data, or file upload
- User-friendly UI - Modal dialog with drag-and-drop file support
π¨ Admin UI Usage¶
Accessing the Bulk Import Modal¶
- Navigate to Admin UI - Open your gateway's admin interface at
http://localhost:4444/admin
- Go to Tools Tab - Click on the "Tools" tab in the main navigation
- Open Bulk Import - Click the "+ Bulk Import Tools" button next to "Add New Tool"
Using the Modal¶
The bulk import modal provides two ways to input tool data:
Option 1: JSON Textarea¶
- Paste JSON directly into the text area
- Validate format - The modal will check JSON syntax before submission
- Click Import Tools to process
Option 2: File Upload¶
- Prepare a JSON file with your tools array
- Click "Choose File" and select your
.json
file - Click Import Tools to process
UI Features¶
- Real-time validation - JSON syntax checking before submission
- Loading indicators - Progress spinner during import
- Detailed results - Success/failure counts with error details
- Auto-refresh - Page reloads automatically after successful import
- Modal controls - Close with button, backdrop click, or ESC key
π‘ API Endpoint¶
Request Methods¶
Method 1: JSON Body¶
Method 2: Form Data (JSON String)¶
POST /admin/tools/import
Authorization: Bearer <jwt_token>
Content-Type: multipart/form-data
Form field: tools_json=<json_string>
Method 3: File Upload¶
POST /admin/tools/import
Authorization: Bearer <jwt_token>
Content-Type: multipart/form-data
Form field: tools_file=<uploaded_json_file>
Payload Structure¶
[
{
"name": "tool_name",
"url": "https://api.example.com/endpoint",
"integration_type": "REST",
"request_type": "GET",
"description": "Optional description",
"headers": {
"X-API-Key": "optional-key"
},
"input_schema": {
"type": "object",
"properties": {
"param": {"type": "string"}
}
}
},
// ... more tools
]
Response¶
{
"success": true,
"created_count": 2,
"failed_count": 1,
"created": [
{"index": 0, "name": "tool1"},
{"index": 1, "name": "tool2"}
],
"errors": [
{
"index": 2,
"name": "tool3",
"error": {
"message": "Validation failed: Invalid request_type",
"details": [...]
}
}
]
}
π οΈ Usage Examples¶
Using cURL¶
# Generate JWT token
TOKEN=$(python3 -m mcpgateway.utils.create_jwt_token \
--username admin --exp 60 --secret $JWT_SECRET_KEY)
# Import tools from file
curl -X POST http://localhost:4444/admin/tools/import \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
--data-binary @tools.json
Using Python¶
import requests
import json
# Your tools data
tools = [
{
"name": "list_users",
"url": "https://api.example.com/users",
"integration_type": "REST",
"request_type": "GET"
},
{
"name": "create_user",
"url": "https://api.example.com/users",
"integration_type": "REST",
"request_type": "POST",
"input_schema": {
"type": "object",
"properties": {
"body": {"type": "object"}
},
"required": ["body"]
}
}
]
# Make the request
response = requests.post(
"http://localhost:4444/admin/tools/import",
headers={
"Authorization": f"Bearer {token}",
"Content-Type": "application/json"
},
json=tools
)
result = response.json()
print(f"Created: {result['created_count']}, Failed: {result['failed_count']}")
π Tool Schema Reference¶
Each tool in the array must follow this schema:
Field | Type | Required | Description |
---|---|---|---|
name | string | β | Unique tool identifier |
url | string | β | Tool endpoint URL |
integration_type | string | β | Must be "REST" or "MCP" |
request_type | string | β | HTTP method: GET, POST, PUT, DELETE, PATCH, SSE, STDIO, STREAMABLEHTTP |
description | string | β | Human-readable description |
headers | object | β | HTTP headers to include |
input_schema | object | β | JSON Schema for input validation |
output_schema | object | β | JSON Schema for output validation |
tags | array | β | List of tags for categorization |
rate_limit | integer | β | Max requests per minute |
timeout | integer | β | Request timeout in seconds |
auth_type | string | β | Authentication type: "basic", "bearer", "api_key" |
auth_value | string | β | Authentication credential |
β οΈ Error Handling¶
The endpoint provides detailed error information for each failed tool:
Validation Errors¶
{
"index": 1,
"name": "invalid_tool",
"error": {
"message": "Validation failed: Invalid request_type",
"details": [
{
"field": "request_type",
"message": "Must be one of: GET, POST, PUT, DELETE, PATCH"
}
]
}
}
Duplicate Tools¶
{
"index": 2,
"name": "existing_tool",
"error": {
"message": "Tool already exists: existing_tool"
}
}
π― Best Practices¶
- Validate locally first - Check your JSON schema before importing
- Use small batches - Start with 10-20 tools to test your format
- Handle partial success - Check both created and errors arrays
- Implement retry logic - For failed items, fix and retry separately
- Monitor rate limits - Stay under 10 requests per minute
π Security Considerations¶
- Authentication required - All requests must include a valid JWT token
- Rate limited - 10 requests per minute per IP address
- Size limited - Maximum 200 tools per request
- Audit logged - All imports are logged with username and timestamp
π¦ Status Codes¶
Code | Meaning |
---|---|
200 | Request processed (check success field for results) |
401 | Authentication required or invalid token |
403 | Feature disabled (MCPGATEWAY_BULK_IMPORT_ENABLED=false) |
413 | Payload too large (>200 tools) |
422 | Invalid request format |
429 | Rate limit exceeded |
500 | Internal server error |
π‘ Tips¶
- Use the bulk import for initial setup and migrations
- Export existing tools first to understand the schema
- Test with a small subset before importing hundreds of tools
- Keep your import files in version control for reproducibility