Skip to main content

Register External MCP Servers

This guide walks you through registering an external MCP server with the Nexla MCP Gateway, syncing its tools into your ToolSet, and managing the server connection over time.

Prerequisites​

Before you begin, make sure you have the following:

  • An active ToolSet with MCP Gateway enabled. See Create & Manage ToolSets for instructions on setting up a ToolSet.
  • The external MCP server's URL (the endpoint Nexla will connect to for tool discovery and invocation).
  • Any required authentication credentials for the external server (API key, OAuth token, etc.).
  • The external server must support the Streamable HTTP transport type.

Registering a Server​

To register an external MCP server with the Gateway:

  1. Open the ToolSet detail page for the ToolSet you want to add external tools to.
  2. Navigate to the Gateway section.
  3. Click Add External MCP Server.
  4. Enter the following details:
    • Server name -- A descriptive name to identify this server in the Gateway (e.g., "Slack Tools" or "Internal Analytics API").
    • Description (optional) -- A brief description of what this server provides.
    • Server URL -- The full URL of the external MCP server endpoint.
    • Transport type -- Select Streamable HTTP.
  5. Configure authentication if the external server requires it. Enter the credentials (API key, token, or other secrets) as prompted.
  6. Click Save. The server is registered with a status of Active.
note

Credentials for external MCP servers are stored securely in an encrypted vault. They are never exposed in the UI or API responses.

Tool Discovery and Sync​

After registering an external server, trigger a sync to discover and import its tools into your ToolSet.

  1. Locate the registered server in the Gateway section of your ToolSet.
  2. Click Sync on the server entry.
  3. Nexla connects to the external server, lists all available tools, and imports them as gateway tools.
  4. When the sync completes, the sync log displays a summary:
    • Tools discovered -- Total number of tools found on the external server.
    • Created -- New tools added to your ToolSet.
    • Updated -- Existing tools whose definitions changed since the last sync.
    • Removed -- Tools that no longer exist on the external server and were removed from your ToolSet.
    • Unchanged -- Tools that have not changed since the last sync.
  5. The sync status transitions from started to completed (or failed if an error occurred).
tip

You can preview available tools before syncing by clicking "View Available Tools" on the registered server. This lets you see what will be imported without making any changes to your ToolSet.

Tool Filtering​

Tool filtering lets you control exactly which tools are imported from an external server. This is useful when an external server exposes many tools but you only need a subset.

Include Patterns​

Include patterns restrict the import to only tools whose names match the specified patterns. When include patterns are set, any tool that does not match is excluded.

Example: sales_* imports only tools whose names start with "sales_", such as sales_lookup, sales_report, and sales_forecast.

Exclude Patterns​

Exclude patterns prevent matching tools from being imported. All other tools are included.

Example: internal_* excludes tools like internal_debug and internal_admin, while importing everything else.

Patterns use glob syntax:

  • * matches any sequence of characters (e.g., data_* matches data_export, data_import, data_transform).
  • ? matches a single character (e.g., report_? matches report_a and report_b but not report_ab).

You can preview filtered results before applying changes. If you clear all filters, the next sync imports all tools from the server.

Managing Registered Servers​

Server Status​

Each registered server has a status indicating its current state:

  • Active -- The server is connected and available for syncing. Tools are being imported normally.
  • Inactive -- The server connection is paused. No syncs occur, but the server configuration and previously synced tools are retained.
  • Error -- The last connection attempt failed. This typically indicates the external server is unreachable or returned an unexpected response. Check the server URL and ensure the external server is running.
  • Auth Error -- Authentication failed. The stored credentials may be expired, revoked, or incorrect. Re-enter valid credentials to resolve the issue.

Updating Server Configuration​

You can update a registered server's configuration at any time:

  1. Open the Gateway section in your ToolSet.
  2. Click on the server you want to update.
  3. Modify the server URL, description, or credentials as needed.
  4. Click Save to apply changes.

After updating credentials or the server URL, trigger a new sync to verify the connection and refresh the tool catalog.

Removing a Server​

To remove a registered external server:

  1. Open the Gateway section in your ToolSet.
  2. Click on the server you want to remove.
  3. Click Remove Server and confirm the action.
warning

Removing an external MCP server deletes all its synced tools from the ToolSet. AI agents will immediately lose access to those tools. This action cannot be undone.

The Gateway generates AI-powered embeddings for every synced tool, enabling semantic search across your entire tool catalog. Instead of searching by exact tool name, you can describe what you need in natural language -- for example, "find tools that send Slack messages" or "tools for querying sales data."

Semantic search is especially useful when working with large catalogs where you may not know the exact tool names. The search ranks results by relevance, surfacing the tools that best match your description.

Sync Logs​

Every sync operation is recorded in the sync logs. Use sync logs to monitor the health of your external server connections and troubleshoot issues.

Each log entry includes:

  • Timestamp -- When the sync started and completed.
  • Tools discovered -- How many tools were found on the external server.
  • Created / Updated / Removed / Unchanged -- A breakdown of what changed in your ToolSet.
  • Duration -- How long the sync took.
  • Status -- Whether the sync completed successfully or failed.
  • Error details -- If the sync failed, the error message describing what went wrong.

Troubleshooting​

Sync Failed​

If a sync fails, check the following:

  • The external server is running and accepting connections.
  • The server URL is correct and reachable from the Nexla Platform.
  • Credentials are valid and have not expired.
  • Your network configuration allows outbound connections to the external server's host and port.

Review the sync log's error details for specific information about what went wrong.

Auth Error​

An auth error means Nexla could not authenticate with the external server:

  • Re-enter credentials by editing the server configuration in the Gateway.
  • Verify that the external server's authentication requirements have not changed (e.g., a switch from API key to OAuth).
  • Check whether the API key or token has been rotated or revoked on the external server's side.

Tools Missing After Sync​

If expected tools are not appearing after a sync:

  • Check your tool filters. Include/exclude patterns may be filtering out the tools you expect to see.
  • Verify that the tools are active on the external server. Inactive or disabled tools may not be listed during discovery.
  • Try a manual re-sync to refresh the tool catalog.
  • Review the sync log to confirm the sync completed successfully and check the tool count.