Nexla MCP Gateway

The Nexla MCP Gateway is the layer on top of Nexla's pre-built MCP servers. It gives your AI client one endpoint, https://mcp.nexla.com, for the pre-built MCP servers available to you, each with its own scoped tools. Your agent finds the tool it needs inside those servers, checks how to call it, and runs it -- without you connecting each server separately. The gateway is the endpoint behind Nexla's cloud marketplace and AI client directory listings.

How It Fits Together

Layer	What it is
Nexla MCP Gateway	One endpoint, `https://mcp.nexla.com`. You connect and sign in once.
Pre-built MCP servers	The task-specific servers you access through the gateway, such as Renewal Call Prep.
Tools	Each pre-built server contains the scoped tools for its use case. The gateway's own tools, described below, are how your agent finds and runs them.

What You Can Reach

The tools of the pre-built MCP servers available to you, and other public tools that Nexla organizations publish.
The active tools in your Nexla organization. A private tool is visible only to its owner.

The gateway doesn't expose raw connector operations or tools imported from external MCP servers. The gateway checks that you can see a tool each time you describe or run it, so a search result alone never grants access.

Your client always sees the same five gateway tools, however many Nexla tools you can access. The agent searches for the tool it needs instead of loading every tool definition on every turn.

Gateway Tools

Your client sees these five gateway tools. The agent uses them to reach the tools inside the pre-built servers.

Tool	What it does	Inputs
`search_tool`	Finds the Nexla tools you can use, ranked for your request. Each result has a `tool_id`, a name, a short description, whether the tool reads or writes, `call_with` (the call tool to use) and a confidence. When the match is not certain, several candidates come back.	`query`; `limit` (default 5, maximum 20)
`describe_tool`	Returns a tool's full input schema, whether it reads or writes, which call tool to use, the result modes a read supports, and whether you must connect a credential first.	`tool_id`
`call_tool_read`	Runs a read tool.	`tool_id`, `arguments`, `result_mode`
`call_tool_write`	Runs a write tool. A write changes data in an external system and may not be reversible.	`tool_id`, `arguments`
`analyze_data`	Answers an analytical question -- distinct counts, grouping, totals, rankings, deduplication or joins -- over complete datasets captured with `call_tool_read`. An AI agent writes and runs read-only SQL. The result rows come from the SQL it runs, and any notes it adds are labelled as AI-written.	`intent`, `inputs` (up to 8 datasets, each a `data_ref` with a unique `alias`)

How an Agent Uses the Gateway

Call search_tool with what you want to do -- for example, hubspot contacts.
Call describe_tool with the chosen tool_id to get its input schema and the call tool to use.
Call call_tool_read or call_tool_write, as call_with says, with the tool_id and the tool's arguments.
To compute over complete inputs, call call_tool_read with result_mode set to dataset, then pass the returned data_ref to analyze_data.

call_tool_read rejects write tools, and call_tool_write rejects read tools.

Read Result Modes

`result_mode`	Returns	Use it for
`rows` (default)	Records, within an output size budget	Lookups, lists and answers the source already computes
`count`	The number of matching rows, without returning them	An exact count of matching rows
`dataset`	A `data_ref` that points to the complete captured dataset	Input to `analyze_data`, for grouping, joins and other computation

rows can return only part of the matching records. For an exact count, use count. For totals or grouping over every record, use dataset with analyze_data.

Not every read tool supports count and dataset -- check the result modes in describe_tool. Both modes read the source in full, and if the source can't be read completely they fail instead of returning a partial result. A data_ref lasts up to 30 minutes after capture, and running an analysis doesn't extend it. It may become unavailable earlier.

Write Tools

call_tool_write is marked as destructive, so clients that honor tool annotations may ask you to confirm before a write runs. The gateway itself doesn't ask for confirmation. If a write fails after it reached the external system, don't retry it automatically -- check the external system first.

Credentials and Access

Every call runs on your behalf. Which credential it uses depends on the tool:

If you own a tool, it runs with your own credential.
Otherwise, it runs with the credential mapped to you for that tool.
If there is no credential for you, the call returns AUTH_REQUIRED with a setup URL. describe_tool warns you ahead of time and includes the setup_url. Connect the credential in Nexla, then retry.

Credentials stay in Nexla, and the agent never sees them. Every run of a Nexla tool through the gateway is recorded in an audit receipt. See Audit & Receipts.

Connect Your Client

If you added Nexla from a cloud marketplace or your AI client's connector directory, the listing sets up the connection for you -- sign in when your client asks. To add the gateway yourself, use the site root as the server URL:

https://mcp.nexla.com

The same endpoint also answers at https://mcp.nexla.com/mcp, for clients already configured with that path.

Method	How it works
OAuth	Add the URL with no header. Your client opens the Nexla sign-in page, where you sign in with Google, a Microsoft work or school account, or your Nexla email and password.
Service key	Send your Nexla service key in the `Authorization` header: `Authorization: Bearer YOUR_NEXLA_SERVICE_KEY`. See Service Keys.

Email and password works only if your organization doesn't use single sign-on, and only if the password has no colon (:). Otherwise, sign in with Google or Microsoft. If your organization's single sign-on uses another identity provider, connect with a service key instead.

With OAuth, your client discovers the sign-in flow on its own. Its first request gets a 401 that points it to the server's protected-resource metadata. The client then reads the authorization-server metadata, registers itself, and completes an authorization-code flow with PKCE (S256). Your access token expires with your Nexla session. Clients that support refresh tokens renew it automatically; others ask you to sign in again.

Claude (Custom Connector)

In Claude, open Settings > Connectors and add a custom connector.
Enter https://mcp.nexla.com as the URL.
Connect and sign in.

ChatGPT

In ChatGPT, go to Settings > Apps & Connectors > Advanced settings and turn on Developer mode.
In Apps, click Create app.
In Server URL, enter https://mcp.nexla.com, set Authentication to OAuth, and continue.
Sign in, then confirm the app shows as Connected.

For screenshots of these ChatGPT screens, see Integrate with ChatGPT. Enter https://mcp.nexla.com, not the Server URL shown in that guide.

Claude Code

With OAuth, add the server, then run /mcp in Claude Code and sign in:

claude mcp add --transport http nexla https://mcp.nexla.com

With a service key:

claude mcp add --transport http nexla https://mcp.nexla.com --header "Authorization: Bearer $NEXLA_SERVICE_KEY"

Cursor and VS Code

In Cursor, edit ~/.cursor/mcp.json:

{
  "mcpServers": {
    "nexla": {
      "url": "https://mcp.nexla.com"
    }
  }
}

In VS Code, edit .vscode/mcp.json:

{
  "servers": {
    "nexla": {
      "type": "http",
      "url": "https://mcp.nexla.com"
    }
  }
}

To use a service key instead of OAuth, add an Authorization header to the entry. In Cursor:

{
  "mcpServers": {
    "nexla": {
      "url": "https://mcp.nexla.com",
      "headers": {
        "Authorization": "Bearer YOUR_NEXLA_SERVICE_KEY"
      }
    }
  }
}

In VS Code, which prompts for the key instead of storing it in the file:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "nexla-key",
      "description": "Nexla service key",
      "password": true
    }
  ],
  "servers": {
    "nexla": {
      "type": "http",
      "url": "https://mcp.nexla.com",
      "headers": {
        "Authorization": "Bearer ${input:nexla-key}"
      }
    }
  }
}

Other Clients

Microsoft Copilot and other clients that support remote MCP servers with OAuth: add https://mcp.nexla.com as a custom connector and sign in. If a browser-based client's connection is refused with a 403, contact Nexla support.
Clients that only run local servers, such as Claude Desktop when configured through claude_desktop_config.json, need Node.js. Run the gateway through mcp-remote, which opens a browser window for you to sign in:
```
{
  "mcpServers": {
    "nexla": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.nexla.com"]
    }
  }
}
```
Clients that can't register themselves, such as Gemini Enterprise, need a client ID and secret from Nexla, and sign in with Google or Microsoft only. Nexla support gives you the client ID, the client secret and any extra authorization parameter the client's form needs.

Verify the Connection

List the gateway's tools with a service key:

curl -s https://mcp.nexla.com \
  -H "Authorization: Bearer $NEXLA_SERVICE_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

A working key returns the five gateway tools. The response can arrive as an SSE data: line; the JSON after data: is the result. To try a search:

curl -s https://mcp.nexla.com \
  -H "Authorization: Bearer $NEXLA_SERVICE_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"search_tool","arguments":{"query":"hubspot contacts"}}}'

Troubleshooting

401 After Signing In

Your access token expired with your Nexla session. Clients that support refresh tokens renew it automatically. Otherwise, remove the connector and sign in again.

A Tool Doesn't Appear in Search

search_tool returns only the active tools you can access: the tools of pre-built servers and other public tools, and your organization's tools. A private tool is visible only to its owner. It also returns at most limit results (5 by default), so try a more specific query or raise limit (up to 20).

Error Codes

Tool errors carry a code that tells you what to do next:

Code	Meaning	What to do
`AUTH_REQUIRED`	You have no credential for the tool.	Open the setup URL from the response, connect the credential in Nexla, then retry.
`UNAUTHORIZED`	Your Nexla session ended.	Sign in again.
`NOT_FOUND`, `FORBIDDEN`	The tool doesn't exist or isn't visible to you.	Search again for a tool you can access.
`TOOL_NOT_ACTIVE`	The tool is turned off.	For a tool in a pre-built server, contact Nexla support. For your organization's own tool, ask its owner to activate it.
`OPERATION_MISMATCH`	The tool was run with the wrong call tool.	Use the call tool named in `call_with`: `call_tool_read` for reads, `call_tool_write` for writes.
`UNSUPPORTED_SOURCE`	The read doesn't support the requested `result_mode`.	Use `rows`, or check the supported modes in `describe_tool`.
`INCOMPLETE_COUNT`, `INCOMPLETE_DATASET`	The source couldn't be read completely, so no partial answer was returned.	Narrow the filters and try again.
`CAPTURE_QUOTA`	You have too many captured datasets at once.	Wait for earlier captures to expire, or capture fewer sources.
`REFERENCE_UNAVAILABLE`	The `data_ref` passed to `analyze_data` expired or is no longer available.	Capture the data again with `result_mode` set to `dataset`, then rerun the analysis.
`OUTPUT_TOO_LARGE`	The result exceeds the output budget.	Narrow the request, or use `count` or `dataset`.
`INTERNAL`	The tool failed unexpectedly.	Contact Nexla support and include the `trace_id` from the error details.

Next Steps

Pre-built MCP Servers -- The task-specific servers you access through the gateway, and the tools they contain.
On-Behalf-Of Access -- How every tool call runs with the caller's own credentials.
Audit & Receipts -- Look up the receipt for any tool call.

How It Fits Together​

What You Can Reach​

Gateway Tools​

How an Agent Uses the Gateway​

Read Result Modes​

Write Tools​

Credentials and Access​

Connect Your Client​

Sign-In Options​

Claude (Custom Connector)​

ChatGPT​

Claude Code​

Cursor and VS Code​

Other Clients​

Verify the Connection​

Troubleshooting​

401 After Signing In​

A Tool Doesn't Appear in Search​

Error Codes​

Next Steps​