MCP Protocol

Nexla implements the Model Context Protocol (MCP) via Streamable HTTP, providing a standards-based interface for AI clients to discover and invoke tools. Each ToolSet export is served as an MCP-compatible endpoint that any MCP client — such as Claude Desktop, Cursor, or custom agents — can connect to.

MCP Server Endpoints

Path	Auth Method	Description
`POST /mcp/service_key/{server_key}`	Service Key (Bearer)	MCP Streamable HTTP with service key auth
`POST /mcp/oauth/google/{server_key}`	Google OAuth	MCP Streamable HTTP with Google OAuth
`POST /mcp/oauth/azure/{server_key}`	Azure OAuth	MCP Streamable HTTP with Azure OAuth

All three endpoints implement the same MCP Streamable HTTP protocol. The only difference is how the client authenticates.

How MCP Streamable HTTP Works

MCP uses JSON-RPC 2.0 over HTTP. Clients send JSON-RPC requests as POST bodies, and the server responds with JSON-RPC results. The server_key in the URL identifies which ToolSet export to serve, determining which tools are available to the client.

A typical flow looks like this:

The client sends an initialize request to establish a session.
The client sends tools/list to discover available tools.
The client sends tools/call to execute a specific tool.
The server returns results, including a receipt ID for audit purposes.

MCP Operations

The following MCP operations are supported on all server endpoints.

initialize

Session initialization. The client provides its capabilities and protocol version, and the server responds with available tools and its own capabilities.

Initialize: 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": "initialize",
    "params": {
      "protocolVersion": "2025-03-26",
      "capabilities": {},
      "clientInfo": {
        "name": "my-agent",
        "version": "1.0.0"
      }
    }
  }'

Initialize: Response
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-03-26",
    "capabilities": {
      "tools": { "listChanged": true }
    },
    "serverInfo": {
      "name": "nexla-mcp-server",
      "version": "1.0.0"
    }
  }
}

tools/list

Returns all active tools in the ToolSet. The response includes each tool's name, description, and JSON Schema input schema — everything an AI model needs to understand how to call the tool.

List 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": 2,
    "method": "tools/list"
  }'

List Tools: Response
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "tools": [
      {
        "name": "get_customer_profile",
        "description": "Retrieve a customer profile by customer ID",
        "inputSchema": {
          "type": "object",
          "properties": {
            "customer_id": {
              "type": "integer",
              "description": "The unique customer identifier"
            }
          },
          "required": ["customer_id"]
        }
      },
      {
        "name": "search_customers",
        "description": "Search customers by name, email, or account status",
        "inputSchema": {
          "type": "object",
          "properties": {
            "query": {
              "type": "string",
              "description": "Search query string"
            },
            "limit": {
              "type": "integer",
              "description": "Maximum results to return",
              "default": 10
            }
          },
          "required": ["query"]
        }
      }
    ]
  }
}

tools/call

Execute a specific tool. The request includes the tool name and arguments. The response includes the execution result and a receipt_id that can be used to query the execution audit trail via the Receipts API.

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": "get_customer_profile",
      "arguments": {
        "customer_id": 1001
      }
    }
  }'

Call Tool: Response
{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"customer_id\":1001,\"name\":\"Acme Corp\",\"email\":\"contact@acme.com\",\"plan\":\"enterprise\",\"status\":\"active\"}"
      }
    ],
    "receipt_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Gateway Meta-Tools

When the MCP Server is backed by a Gateway-enabled ToolSet, tools/list includes five additional MCP tools — search_tools, describe_tool, call_tool, list_nexla_vendors_with_available_credentials, and create_nexla_credential — that agents use to discover and invoke gateway tools at runtime instead of receiving the full gateway catalog up front. They are called via tools/call like any other MCP tool. See Gateway Meta-Tools for input and output schemas and end-to-end examples.

MCP Configuration Endpoints

These REST endpoints return pre-formatted MCP client configuration, making it easy to connect any MCP-compatible client to a Nexla ToolSet.

Method	Path	Description
GET	`/v1/toolsets/{id}/mcp_config`	Get MCP config by ToolSet ID
GET	`/v1/mcp/{server_key}/config`	Get MCP config by server key
GET	`/v1/toolsets/{id}/exports/{export_id}/mcp_config`	Get MCP config by export ID

Get MCP Config: Request
curl -X GET https://api-genai.nexla.io/v1/toolsets/42/mcp_config \
  -H "Authorization: Bearer $NEXLA_SERVICE_KEY"

Get MCP Config: Response
{
  "mcpServers": {
    "nexla-sales-analytics": {
      "url": "https://api-genai.nexla.io/mcp/service_key/abc123...",
      "headers": {
        "Authorization": "Bearer YOUR_SERVICE_KEY"
      }
    }
  },
  "instructions": "Tools for querying sales analytics data."
}

Copy this JSON directly into your MCP client's configuration file (e.g., claude_desktop_config.json for Claude Desktop) to connect.

Session Management

MCP sessions track the lifecycle of a client connection, including protocol negotiation, tool discovery, and tool execution.

Method	Path	Description
GET	`/v1/sessions`	List MCP sessions
GET	`/v1/sessions/{session_id}`	Get session details
POST	`/v1/sessions/{session_id}:terminate`	Terminate a session
POST	`/v1/sessions:cleanup`	Cleanup stale sessions
GET	`/v1/toolsets/{id}/sessions`	List sessions for a ToolSet

Each session tracks:

MCP session ID — unique identifier assigned during initialization
Protocol version — the MCP protocol version negotiated with the client
Client info — name and version of the connecting client
Initialization status — whether the session completed the initialize handshake
Last activity time — timestamp of the most recent request

Terminate a Session

Terminate Session: Request
curl -X POST https://api-genai.nexla.io/v1/sessions/sess_abc123:terminate \
  -H "Authorization: Bearer $NEXLA_SERVICE_KEY"

Cleanup Stale Sessions

POST /v1/sessions:cleanup accepts a max_idle_seconds parameter to terminate sessions that have been idle beyond the specified threshold.

Cleanup Sessions: Request
curl -X POST https://api-genai.nexla.io/v1/sessions:cleanup \
  -H "Authorization: Bearer $NEXLA_SERVICE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "max_idle_seconds": 3600
  }'

Cleanup Sessions: Response
{
  "terminated_count": 5,
  "remaining_active": 12
}

OAuth Discovery

For OAuth-enabled MCP servers (Google or Azure auth), standard OAuth discovery endpoints are available:

Path	Description
`GET /.well-known/oauth-authorization-server/{path}`	OAuth authorization server metadata
`GET /.well-known/oauth-protected-resource/{path}`	Protected resource metadata

These endpoints follow RFC 8414 and allow MCP clients to automatically discover authorization endpoints, token endpoints, and supported grant types.

Example: Full MCP Interaction

The following example walks through a complete MCP interaction — from session initialization to tool execution to receipt lookup.

Step 1: Initialize the Session

Step 1: Initialize
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": "initialize",
    "params": {
      "protocolVersion": "2025-03-26",
      "capabilities": {},
      "clientInfo": {
        "name": "my-agent",
        "version": "1.0.0"
      }
    }
  }'

The server responds with its capabilities and protocol version, establishing the session.

Step 2: List Available Tools

Step 2: List Tools
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/list"
  }'

The server returns all active tools with their names, descriptions, and input schemas.

Step 3: Call a Tool

Step 3: Call Tool
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": "get_customer_profile",
      "arguments": {
        "customer_id": 1001
      }
    }
  }'

The server executes the tool and returns the result along with a receipt_id.

Step 4: View the Receipt

Use the receipt ID from the tool call response to query the execution audit trail via the Receipts API:

Step 4: View Receipt
curl -X GET https://api-genai.nexla.io/v1/receipts/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer $NEXLA_SERVICE_KEY"

Receipt: Response
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "org_id": 1,
  "principal": "user:jane@example.com",
  "tool_id": 1,
  "tool_key": "get_customer_profile",
  "version": "1.0.0",
  "args_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "result_status": "ok",
  "actor_type": "agent",
  "auth_type": "api_key",
  "policy_decision": "allow",
  "trace_id": "abc-123-def",
  "row_count": 1,
  "truncated": false,
  "created_at": "2025-06-15T14:30:00Z"
}

ToolSets API — Create and manage ToolSets and exports
Tools API — Create and manage individual tools
Receipts API — Query execution audit trail
MCP Tools & Servers User Guide — UI workflows for deploying MCP servers

MCP Server Endpoints​

How MCP Streamable HTTP Works​

MCP Operations​

initialize​

tools/list​

tools/call​

Gateway Meta-Tools​

MCP Configuration Endpoints​

Session Management​

Terminate a Session​

Cleanup Stale Sessions​

OAuth Discovery​

Example: Full MCP Interaction​

Step 1: Initialize the Session​

Step 2: List Available Tools​

Step 3: Call a Tool​

Step 4: View the Receipt​

Related Resources​