Gateway API

The Gateway API lets you register external MCP servers, sync their tools into Nexla's unified catalog, and search across all gateway tools. This enables a single ToolSet to aggregate tools from multiple MCP-compatible providers alongside Nexla-native tools.

External MCP Server Endpoints

Method	Path	Description
POST	`/v1/toolsets/{id}/gateway/mcp-servers`	Register an external MCP server
GET	`/v1/toolsets/{id}/gateway/mcp-servers`	List registered servers
GET	`/v1/toolsets/{id}/gateway/mcp-servers/{server_id}`	Get server details
PUT	`/v1/toolsets/{id}/gateway/mcp-servers/{server_id}`	Update server config
DELETE	`/v1/toolsets/{id}/gateway/mcp-servers/{server_id}`	Remove a server
POST	`/v1/toolsets/{id}/gateway/mcp-servers/{server_id}/sync`	Trigger tool sync
GET	`/v1/toolsets/{id}/gateway/mcp-servers/{server_id}/available-tools`	Preview available tools
PUT	`/v1/toolsets/{id}/gateway/mcp-servers/{server_id}/tool-filter`	Update tool filter

Gateway Tool Endpoints

Method	Path	Description
GET	`/v1/toolsets/{id}/gateway/tools`	List all gateway tools
POST	`/v1/toolsets/{id}/gateway/tools:search`	Semantic search tools
GET	`/v1/toolsets/{id}/gateway/tools/{tool_name}`	Get gateway tool details
GET	`/v1/toolsets/{id}/gateway/sync-logs`	Get sync logs

Register an External MCP Server

POST /v1/toolsets/{id}/gateway/mcp-servers

Registers a new external MCP server under a ToolSet. The server's tools are not imported until you trigger a sync.

Request:

curl -X POST "https://api-genai.nexla.io/v1/toolsets/5/gateway/mcp-servers" \
  -H "Authorization: Bearer $NEXLA_SERVICE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "server_name": "Slack MCP Server",
    "server_description": "Tools for Slack workspace management",
    "server_url": "https://mcp.slack-tools.example.com/mcp",
    "transport_type": "streamable_http",
    "mcp_config": {
      "headers": {
        "Authorization": "Bearer slack-api-key..."
      }
    },
    "tool_filter": {
      "include_patterns": ["channels_*", "messages_*"],
      "exclude_patterns": ["admin_*"]
    }
  }'

Response (201):

{
  "id": 12,
  "server_name": "Slack MCP Server",
  "server_description": "Tools for Slack workspace management",
  "server_url": "https://mcp.slack-tools.example.com/mcp",
  "transport_type": "streamable_http",
  "status": "registered",
  "tool_count": 0,
  "created_at": "2025-06-10T09:15:00Z",
  "updated_at": "2025-06-10T09:15:00Z"
}

note

Credentials in mcp_config are encrypted and stored in a secure vault. They are never returned in API responses.

Trigger Tool Sync

POST /v1/toolsets/{id}/gateway/mcp-servers/{server_id}/sync

Triggers an asynchronous sync that connects to the external MCP server, discovers its tools, and imports them into the ToolSet's gateway catalog. The response returns a sync job ID — query the sync logs endpoint to track progress and results.

Request:

curl -X POST "https://api-genai.nexla.io/v1/toolsets/5/gateway/mcp-servers/12/sync" \
  -H "Authorization: Bearer $NEXLA_SERVICE_KEY"

Response (202):

{
  "sync_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "started",
  "started_at": "2025-06-10T09:20:00Z"
}

Preview Available Tools

GET /v1/toolsets/{id}/gateway/mcp-servers/{server_id}/available-tools

Lists the tools currently exposed by the external MCP server before they are synced into the gateway catalog. Use this to review what will be imported and to fine-tune your tool filter.

Request:

curl -X GET "https://api-genai.nexla.io/v1/toolsets/5/gateway/mcp-servers/12/available-tools" \
  -H "Authorization: Bearer $NEXLA_SERVICE_KEY"

Response (200):

{
  "tools": [
    {
      "name": "channels_list",
      "description": "List all channels in the Slack workspace",
      "input_schema": {
        "type": "object",
        "properties": {
          "include_archived": { "type": "boolean", "default": false }
        }
      }
    },
    {
      "name": "messages_send",
      "description": "Send a message to a Slack channel",
      "input_schema": {
        "type": "object",
        "properties": {
          "channel": { "type": "string" },
          "text": { "type": "string" }
        },
        "required": ["channel", "text"]
      }
    }
  ],
  "total": 2
}

Update Tool Filter

PUT /v1/toolsets/{id}/gateway/mcp-servers/{server_id}/tool-filter

Updates the tool filter for a registered server. The filter controls which tools are imported during the next sync. Changing the filter does not automatically trigger a sync — call the sync endpoint afterward to apply the new filter.

Request:

curl -X PUT "https://api-genai.nexla.io/v1/toolsets/5/gateway/mcp-servers/12/tool-filter" \
  -H "Authorization: Bearer $NEXLA_SERVICE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "include_patterns": ["data_*"],
    "exclude_patterns": ["internal_*", "debug_*"]
  }'

Response (200):

{
  "include_patterns": ["data_*"],
  "exclude_patterns": ["internal_*", "debug_*"]
}

Patterns use glob syntax: * matches any sequence of characters, ? matches a single character. If include_patterns is empty or omitted, all tools are included. exclude_patterns take precedence over include_patterns.

Semantic Search

POST /v1/toolsets/{id}/gateway/tools:search

Performs a semantic search across all gateway tools in the ToolSet. The query is matched against tool names, descriptions, and parameter metadata. Results are ranked by relevance.

Request:

curl -X POST "https://api-genai.nexla.io/v1/toolsets/5/gateway/tools:search" \
  -H "Authorization: Bearer $NEXLA_SERVICE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "tools for reading customer order data",
    "limit": 10
  }'

Response (200):

{
  "results": [
    {
      "tool_name": "read_customer_orders",
      "description": "Read customer orders by date range or order ID",
      "server_name": "Orders MCP Server",
      "similarity_score": 0.94
    },
    {
      "tool_name": "get_order_details",
      "description": "Retrieve full order details including line items",
      "server_name": "Orders MCP Server",
      "similarity_score": 0.87
    }
  ],
  "total": 2
}

Sync Logs

GET /v1/toolsets/{id}/gateway/sync-logs

Returns a history of sync operations for all servers in the ToolSet. Use this to track sync progress, diagnose failures, and audit tool catalog changes.

Request:

curl -X GET "https://api-genai.nexla.io/v1/toolsets/5/gateway/sync-logs?limit=5" \
  -H "Authorization: Bearer $NEXLA_SERVICE_KEY"

Response (200):

{
  "items": [
    {
      "sync_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "server_id": 12,
      "server_name": "Slack MCP Server",
      "sync_type": "manual",
      "status": "completed",
      "tools_discovered": 15,
      "tools_created": 10,
      "tools_updated": 0,
      "tools_removed": 0,
      "tools_unchanged": 5,
      "duration_ms": 2340,
      "error_message": null,
      "started_at": "2025-06-10T09:20:00Z",
      "completed_at": "2025-06-10T09:20:02Z"
    }
  ],
  "total": 1,
  "limit": 5,
  "offset": 0
}

Sync log fields:

Field	Type	Description
`sync_id`	string	Unique identifier for the sync operation
`server_id`	integer	ID of the external MCP server
`server_name`	string	Name of the external MCP server
`sync_type`	string	`manual` (triggered via API) or `scheduled`
`status`	string	`started`, `completed`, `failed`, or `partial`
`tools_discovered`	integer	Total tools found on the remote server
`tools_created`	integer	New tools added to the catalog
`tools_updated`	integer	Existing tools updated with new metadata
`tools_removed`	integer	Tools removed from the catalog
`tools_unchanged`	integer	Tools that matched and required no update
`duration_ms`	integer	Sync duration in milliseconds
`error_message`	string	Error details if status is `failed` or `partial`

External MCP Server Endpoints​

Gateway Tool Endpoints​

Register an External MCP Server​

Trigger Tool Sync​

Preview Available Tools​

Update Tool Filter​

Semantic Search​

Sync Logs​

External MCP Server Endpoints

Gateway Tool Endpoints

Register an External MCP Server

Trigger Tool Sync

Preview Available Tools

Update Tool Filter

Semantic Search

Sync Logs