Skip to main content

Deploy an MCP Server from Nexsets

In this tutorial, you'll use the MCP Tools & Servers API to turn your Nexla Nexsets into AI tools, deploy them as an MCP server, and connect an AI agent. With a single API call, Nexla creates tool definitions from your Nexsets, bundles them into a ToolSet, and exposes them through a standards-compliant MCP server that any compatible client can consume.

Tutorial Goal​

By the end of this tutorial, you'll have a working MCP server exposing your Nexla data as tools to Claude Desktop (or any MCP-compatible client). Specifically, you will:

  1. Create AI tools from your Nexsets and deploy them as an MCP server
  2. Verify the generated tool definitions
  3. Connect Claude Desktop to the MCP server
  4. Execute tools through an AI agent
  5. Review the execution audit trail

Prerequisites​

Nexla Service Key​

A Nexla service key is required for API authentication. All API calls in this tutorial use the service key as a Bearer token.

See Service Keys to generate one. Once created, export it as an environment variable for use in the commands below:

export NEXLA_SERVICE_KEY="your-service-key-here"
warning

Keep your service key secure. Do not share it or commit it to version control.

Active Nexsets​

You need at least one active Nexset in your Nexla account. Note down the Nexset IDs you want to expose as tools. You can find Nexset IDs in the Nexla UI or by querying the Nexla API.

MCP Client​

An MCP-compatible client is needed to connect to the deployed server. Supported clients include:

  • Claude Desktop (used in this tutorial)
  • Cursor
  • VS Code with Copilot

Step 1: Create a ToolSet from Nexsets​

The fastest path to a working MCP server is a single API call. The toolsets:from_nexsets endpoint creates tools from your Nexsets, bundles them into a ToolSet, and deploys an MCP server — all in one request.

curl -X POST https://api-genai.nexla.io/v1/toolsets:from_nexsets \
  -H "Authorization: Bearer $NEXLA_SERVICE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Data Tools",
    "nexset_ids": [12345, 67890],
    "create_export": true
  }'

Replace 12345 and 67890 with your actual Nexset IDs. Setting create_export to true tells the API to automatically deploy an MCP server for the ToolSet.

Example response:

{
  "id": 1,
  "name": "My Data Tools",
  "status": "active",
  "mcp_server_key": "my-data-tools-a1b2c3",
  "tools": [
    {"id": 101, "key": "read_customer_data", "kind": "nexset_read", "status": "active"},
    {"id": 102, "key": "read_sales_metrics", "kind": "nexset_read", "status": "active"}
  ],
  "export": {
    "id": 1,
    "export_type": "mcp_server",
    "status": "active",
    "mcp_url": "https://api-genai.nexla.io/mcp/service_key/abc123..."
  }
}

Key fields in the response:

  • id — The unique identifier for the ToolSet. Use this to manage the ToolSet in subsequent API calls.
  • mcp_server_key — A human-readable key for the MCP server, derived from the ToolSet name.
  • tools — The list of tools created from your Nexsets. Each tool has an id, a key (used to invoke it), and a kind indicating the tool type.
  • export.mcp_url — The URL of the deployed MCP server. This is what your MCP client will connect to.
tip

Save the mcp_url from the response — you'll need it to configure your MCP client.

Step 2: Verify Your Tools​

After creating the ToolSet, verify that your tools were created correctly.

Check the ToolSet and its tools:

curl -X GET "https://api-genai.nexla.io/v1/toolsets/1" \
  -H "Authorization: Bearer $NEXLA_SERVICE_KEY"

This returns the full ToolSet object, including all tools and their statuses. Confirm that each tool has "status": "active".

Inspect a specific tool's definition:

curl -X GET "https://api-genai.nexla.io/v1/tools/101/definition" \
  -H "Authorization: Bearer $NEXLA_SERVICE_KEY"

The tool definition describes what the tool does and how to call it. It includes:

  • Input schema — The parameters the tool accepts (e.g., filters, format, limit), defined as a JSON Schema object that MCP clients use to construct valid requests.
  • Output format — The structure of the data returned when the tool is executed, so clients know how to parse and display results.

Review the definition to confirm it accurately reflects the data in your Nexset.

Step 3: Connect Claude Desktop​

With the MCP server deployed, you can now connect it to Claude Desktop.

Retrieve the MCP client configuration:

curl -X GET "https://api-genai.nexla.io/v1/toolsets/1/mcp_config" \
  -H "Authorization: Bearer $NEXLA_SERVICE_KEY"

Alternatively, you can manually create the configuration using the endpoint_url from Step 1:

{
  "mcpServers": {
    "nexla-data-tools": {
      "url": "https://api-genai.nexla.io/mcp/service_key/abc123...",
      "headers": {
        "Authorization": "Bearer YOUR_NEXLA_SERVICE_KEY"
      }
    }
  }
}

Replace abc123... with your actual server_key and YOUR_NEXLA_SERVICE_KEY with your service key.

Add the configuration to Claude Desktop:

  1. Open Claude Desktop.
  2. Navigate to Settings and then MCP Servers.
  3. Add the configuration from above.
  4. Restart Claude Desktop to apply the changes.

After restarting, you should see your Nexla tools listed in the tool picker within the Claude Desktop interface.

Step 4: Use Your Tools via AI​

With the MCP server connected, you can now ask Claude to interact with your Nexla data using natural language. The AI agent automatically discovers available tools, selects the appropriate one based on your prompt, and returns results from your Nexla data.

Try these example prompts:

  • "What customer data is available?" — This triggers the tools/list operation, causing Claude to enumerate the available tools and describe what data each one provides.
  • "Show me the latest customer orders" — This triggers a tools/call operation, where Claude selects the relevant tool, executes it, and returns the data from your Nexset.

The MCP protocol handles all the communication between Claude Desktop and your Nexla MCP server. You simply ask questions in natural language, and the AI agent translates them into tool calls behind the scenes.

Step 5: View the Execution Receipt​

Every tool execution generates a receipt that provides an audit trail. You can query receipts to see what tools were called, by whom, and whether they succeeded.

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

Example response:

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "principal": "user:jane@example.com",
      "tool_id": 101,
      "tool_key": "read_customer_data",
      "result_status": "ok",
      "created_at": "2026-03-22T14:30:00Z"
    }
  ],
  "total": 1,
  "limit": 5,
  "offset": 0
}

Key fields in each receipt:

  • principal — The identity of the caller (user or service) that triggered the execution.
  • tool_id / tool_key — The tool that was executed.
  • result_status — Whether the execution succeeded (ok) or failed (error).
  • created_at — When the execution occurred.

Receipts are useful for monitoring usage, debugging issues, and maintaining compliance with data governance policies.

Step 6 (Optional): Execute a Tool via REST API​

You can also execute tools directly via the REST API, without going through an MCP client. This is useful for scripting, testing, or integrating Nexla tools into custom applications.

curl -X POST "https://api-genai.nexla.io/v1/tools/101:execute" \
  -H "Authorization: Bearer $NEXLA_SERVICE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "version": "1.0.0",
    "args": {
      "format": "dataframe_columns",
      "limit": 10
    }
  }'

Example response:

{
  "receipt_id": "550e8400-e29b-41d4-a716-446655440000",
  "result": {
    "status": "ok",
    "data": {
      "columns": ["customer_id", "name", "email", "order_count"],
      "rows": [
        [1, "Alice Johnson", "alice@example.com", 15],
        [2, "Bob Smith", "bob@example.com", 8],
        [3, "Carol Lee", "carol@example.com", 23]
      ]
    },
    "row_count": 3,
    "truncated": false
  }
}

The args object accepts the parameters defined in the tool's input schema (retrieved in Step 2). The format parameter controls how the data is structured in the response, and limit caps the number of rows returned.

Summary​

In this tutorial, you accomplished the following:

  • Created AI tools from Nexsets using the toolsets:from_nexsets endpoint
  • Deployed an MCP server automatically as part of the ToolSet creation
  • Connected Claude Desktop to the MCP server using the generated configuration
  • Executed tools via an AI agent by asking natural language questions
  • Verified the audit trail by reviewing execution receipts
  • Executed a tool directly via REST API for scripting and integration use cases

Next Steps​