Skip to main content

Gateway Meta-Tools

When a ToolSet has the MCP Gateway enabled, its MCP Server exposes five additional tools — called Gateway Meta-Tools — alongside the ToolSet's catalog tools. Agents use these meta-tools to discover and invoke gateway tools at runtime, instead of receiving the full gateway catalog in every tools/list response. This keeps the listed tool surface small enough to fit in an agent's context window even when the underlying catalog contains hundreds of tools.

The meta-tools are MCP-protocol tools: they appear in tools/list and are invoked via tools/call on the same endpoint that serves the ToolSet. They are not REST endpoints — the equivalent REST operations are documented in the Gateway API.

When the Meta-Tools Appear​

The meta-tools are appended to tools/list automatically when the ToolSet has Gateway enabled. No additional configuration is required on the MCP client side — an agent that calls tools/list will see them as ordinary MCP tools.

If a catalog tool already uses one of the meta-tool names, that meta-tool is omitted from tools/list for that ToolSet so the catalog tool takes precedence.

The Five Meta-Tools​

Tool NamePurpose
search_toolsDiscover gateway tools by keyword or natural-language description
describe_toolInspect a specific tool's input schema and usage hints
call_toolExecute a gateway tool with the supplied parameters
list_nexla_vendors_with_available_credentialsList the Nexla vendor credentials the caller can use
create_nexla_credentialReturn a secure link to create a new Nexla vendor credential

All meta-tools return their payload as a JSON-encoded string in result.content[0].text, following standard MCP tools/call semantics. The same payload is also available as a structured object in result.structuredContent.result.

search_tools​

Search the ToolSet's gateway catalog by keyword or natural-language description. When semantic search is available, results are ranked by embedding similarity; otherwise, the call falls back to lexical matching across tool names and descriptions.

Input schema:

FieldTypeRequiredDescription
search_termstringYesQuery text (1–2048 characters). Plain keywords or natural-language descriptions both work.
limitintegerNoMaximum number of results to return. Range: 1–50. Default: 10.

Request:

Search Tools: Request
curl -X POST https://api-genai.nexla.io/mcp/service_key/sk_ts42_a1b2c3d4e5f6 \
  -H "Authorization: Bearer $NEXLA_SERVICE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "search_tools",
      "arguments": {
        "search_term": "shopify customers",
        "limit": 5
      }
    }
  }'

Response (the result field's stringified JSON, formatted for clarity):

Search Tools: Response Payload
{
  "results": [
    {
      "tool_name": "shopify_customers_list",
      "display_name": "List Shopify Customers",
      "description": "List customers from a connected Shopify store",
      "source_type": "nexla_vendor",
      "category": "customers",
      "endpoint_type": "list",
      "similarity": 0.91
    }
  ],
  "total_matches": 1,
  "hint": "Use describe_tool(tool_name) for schema details, then call_tool(tool_name, tool_params) to execute."
}

The similarity field is between 0.0 and 1.0 when semantic search is used and 0.0 for lexical fallback matches. source_type is one of nexla_vendor (a tool backed by a Nexla connector) or external_mcp (a tool synced from a registered external MCP server).

describe_tool​

Return the full definition for a gateway tool, including its input schema and credential or server context. Agents should call describe_tool before call_tool to ensure they provide arguments that match the tool's expected shape.

Input schema:

FieldTypeRequiredDescription
tool_namestringYesExact tool name returned by search_tools (1–512 characters).

Request:

Describe Tool: Request
curl -X POST https://api-genai.nexla.io/mcp/service_key/sk_ts42_a1b2c3d4e5f6 \
  -H "Authorization: Bearer $NEXLA_SERVICE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "describe_tool",
      "arguments": {
        "tool_name": "shopify_customers_list"
      }
    }
  }'

Response payload:

Describe Tool: Response Payload
{
  "tool_name": "shopify_customers_list",
  "display_name": "List Shopify Customers",
  "description": "List customers from a connected Shopify store",
  "source_type": "nexla_vendor",
  "category": "customers",
  "endpoint_type": "list",
  "parameters": {
    "type": "object",
    "properties": {
      "limit": { "type": "integer", "default": 50 },
      "since_id": { "type": "string" }
    }
  },
  "usage_hint": "call_tool('shopify_customers_list', {...})",
  "credential_info": {
    "vendor_name": "shopify_api",
    "vendor_display_name": "Shopify",
    "message": "Requires a credential for vendor 'shopify_api'. The gateway resolves this automatically at runtime."
  }
}

The response includes one of the following extra blocks depending on the tool's source:

  • credential_info — present when source_type is nexla_vendor. Names the vendor whose credential the Gateway will resolve when the tool is invoked.
  • server_info — present when source_type is external_mcp. Identifies the external MCP server the tool was synced from.

call_tool​

Execute a gateway tool with the supplied parameters. The Gateway resolves the appropriate credential (for Nexla vendor tools) or opens a session to the registered external MCP server (for synced tools), then returns a normalized result.

Input schema:

FieldTypeRequiredDescription
tool_namestringYesExact tool name to execute (1–512 characters).
tool_paramsobjectNoArguments to pass to the underlying tool. Must conform to the input schema returned by describe_tool. Defaults to {}. A stringified JSON object is also accepted for compatibility with agent runtimes that flatten arguments to strings.

Request:

Call Tool: Request
curl -X POST https://api-genai.nexla.io/mcp/service_key/sk_ts42_a1b2c3d4e5f6 \
  -H "Authorization: Bearer $NEXLA_SERVICE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "call_tool",
      "arguments": {
        "tool_name": "shopify_customers_list",
        "tool_params": { "limit": 10 }
      }
    }
  }'

Response payload — Nexla vendor tool:

Call Tool: Vendor Tool Response
{
  "status": "ok",
  "tool_name": "shopify_customers_list",
  "data": {
    "customers": [
      { "id": 1001, "email": "ada@example.com" },
      { "id": 1002, "email": "grace@example.com" }
    ]
  }
}

Response payload — external MCP tool:

Call Tool: External MCP Tool Response
{
  "status": "ok",
  "tool_name": "slack_messages_send",
  "content": [
    { "type": "text", "text": "Message sent to #general" }
  ],
  "is_error": false
}

Response payload — missing credential:

If the tool requires a Nexla vendor credential and the caller does not have one, call_tool returns a credential_required status with a secure link to create one. The agent can then call create_nexla_credential or follow the link directly.

Call Tool: Credential Required Response
{
  "status": "credential_required",
  "message": "No credential found for vendor 'shopify_api' (Shopify). Please create one at the URL below, then retry this tool call.",
  "vendor_name": "shopify_api",
  "vendor_display_name": "Shopify",
  "create_credential_url": "https://app.nexla.io/connectors?..."
}

list_nexla_vendors_with_available_credentials​

List the Nexla vendor credentials the caller can use. This lets an agent scope subsequent search_tools queries to vendors it can already authenticate against, avoiding credential_required responses on call_tool.

Input schema: none. Pass an empty arguments object.

Request:

List Available Credentials: Request
curl -X POST https://api-genai.nexla.io/mcp/service_key/sk_ts42_a1b2c3d4e5f6 \
  -H "Authorization: Bearer $NEXLA_SERVICE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "tools/call",
    "params": {
      "name": "list_nexla_vendors_with_available_credentials",
      "arguments": {}
    }
  }'

Response payload:

List Available Credentials: Response
{
  "credentials": [
    {
      "credential_id": 42,
      "name": "Production Shopify",
      "nexla_vendor_name": "shopify_api",
      "vendor_display_name": "Shopify",
      "verified_status": "verified",
      "verified_at": "2025-09-01T12:00:00Z"
    }
  ],
  "total": 1,
  "hint": "Use search_tools to find tools for a specific vendor, then describe_tool and call_tool to execute them."
}

Use the nexla_vendor_name value (e.g. shopify_api, not the display name Shopify) when passing a vendor to create_nexla_credential.

create_nexla_credential​

Return existing credentials for a Nexla vendor along with an auto-generated link that lets the user securely create and save a new credential on Nexla. The link routes the user to the Nexla credential-creation flow for the specified vendor. The meta-tool itself does not create the credential — credentials are always created through the secure flow on Nexla so that secrets never pass through agent or MCP responses.

Input schema:

FieldTypeRequiredDescription
nexla_vendor_namestringYesThe internal Nexla vendor name (for example shopify_api, not the display name Shopify). Use values returned by list_nexla_vendors_with_available_credentials or surfaced in credential_info.vendor_name from describe_tool.

Request:

Create Credential: Request
curl -X POST https://api-genai.nexla.io/mcp/service_key/sk_ts42_a1b2c3d4e5f6 \
  -H "Authorization: Bearer $NEXLA_SERVICE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 5,
    "method": "tools/call",
    "params": {
      "name": "create_nexla_credential",
      "arguments": {
        "nexla_vendor_name": "shopify_api"
      }
    }
  }'

Response payload:

Create Credential: Response
{
  "existing_credentials": [],
  "total": 0,
  "nexla_vendor_name": "shopify_api",
  "create_credential_url": "https://app.nexla.io/connectors?...",
  "message": "Found 0 existing credential(s) for 'shopify_api'. To create a new credential, visit: https://app.nexla.io/connectors?..."
}

After the user creates a credential at the returned URL, the Gateway picks it up on the next call_tool invocation; the agent does not need to refresh any session state.

Errors​

Meta-tool failures are returned as MCP tools/call errors. The error message includes a brief reason and, for input validation errors, the offending field. The most common cases:

ConditionReason
search_term, tool_name, or nexla_vendor_name is empty or exceeds the allowed lengthInput validation failure on the meta-tool's arguments.
tool_name does not match any gateway tool in the ToolSetThe tool was not found, or it is not active in this ToolSet.
Nexla session token is missing, invalid, or expiredThe caller is not authenticated (only applies to list_nexla_vendors_with_available_credentials and create_nexla_credential, which depend on the user's session).
Upstream service unavailableThe Nexla API or an external MCP server failed to respond.
Gateway not enabledThe ToolSet does not have the Gateway enabled, so meta-tools are not exposed.

For Nexla-vendor call_tool invocations where no usable credential is available, the call returns a credential_required payload instead of an error — see the call_tool response shapes.