Losant Mcp Server

Losant MCP Server

[](LICENSE) [](https://nodejs.org) [](https://pnpm.io)

Losant MCP Server is a Model Context Protocol (MCP) server that provides AI assistants like Claude with secure access to the Losant IoT Platform. It supports two authentication modes: a simple API token mode for local use and development, and a full OAuth 2.0 flow for multi-user or production deployments.

Features

• 🔐 OAuth 2.0 Authentication - RFC-compliant bearer token auth (RFC 6750, RFC 7235, RFC 8707, RFC 9728)
• 🛠️ Two Powerful MCP Tools:
• losant_query - Query applications, devices, flows, data tables, and more
• losant_write - Create/Update devices, flows, data tables, files and more
• losant_timeseries - Retrieve time-series device data and state
• 📚 Dynamic Documentation - API docs and schemas loaded from losant-rest package
• 🚀 Stateless & Scalable - Per-request MCP server instances for horizontal scaling
• 🐳 Docker Support - Production-ready multi-stage Docker builds
• ✅ Comprehensive Tests - Tests covering unit, integration, and E2E scenarios

---

Table of Contents

• [Quick Start](#quick-start)
• [Installation](#installation)
• [Configuration](#configuration)
• [Usage](#usage)
• [MCP Tools](#mcp-tools)
• [Authentication](#authentication)
• [Deployment](#deployment)
• [Development](#development)
• [Testing](#testing)
• [Documentation](#documentation)
• [Contributing](#contributing)
• [License](#license)

---

Quick Start

Prerequisites

• Node.js >= 24.0.0
• pnpm >= 11.4.0
• Losant Account with an API token or OAuth configured

Install & Run (API Token — Default)

The simplest way to get started. Set LOSANT_API_TOKEN and the server will authenticate all Losant API requests using that token. OAuth is disabled by default.

# Clone repository
git clone https://github.com/Losant/losant-mcp-server.git
cd losant-mcp-server

# Install dependencies
pnpm install

# Configure environment
cp .env.example .env
# Set LOSANT_API_TOKEN in .env (ENABLE_OAUTH must be false or unset)
# You can generate a token in your Losant account, e.g. https://app.losant.com/me/user-tokens
# If you do not have an account sign up for free at https://accounts.losant.com

# Start server
pnpm start

# Server running at http://localhost:3000

Install & Run (OAuth 2.0)

For multi-user or production deployments, enable OAuth so each MCP client authenticates individually against the Losant auth server.

# Configure environment
cp .env.example .env
# Set LOSANT_RESOURCE_URL to the URL where the MCP server is hosted and ENABLE_OAUTH=true in .env

# Start server
pnpm start

Verify Installation

# Health check
wget http://localhost:3000/healthz

# Expected response:
# {"ok":true,"server":"losant-mcp-server"}

---

Installation

From Source

git clone https://github.com/Losant/losant-mcp-server.git
cd losant-mcp-server
pnpm install

Docker

# Pull image
docker losant/losant-mcp-server:latest

# Run container
docker run -d -p 3000:3000 \
  -e LOSANT_API_TOKEN= \
  losant/losant-mcp-server:latest

See [README.Docker.md](README.Docker.md) for detailed Docker instructions.

---

Configuration

Configuration is managed via environment variables. See [.env.example](.env.example) for all options.

API Token Mode (Default — ENABLE_OAUTH=false)

The server authenticates every Losant API call using a single static token. No OAuth setup is required. This is the recommended mode for local development and single-user deployments.

| Variable | Required | Description | Example | |----------|----------|-------------|---------| | LOSANT_API_TOKEN | Yes | Losant API token used for all requests to the Losant API | your-api-token |

ENABLE_OAUTH must be false (the default) when using this mode.

OAuth 2.0 Mode (ENABLE_OAUTH=true)

Each MCP client connection authenticates independently against the Losant OAuth server. The server validates the resulting bearer token on every request and forwards it to the Losant API. This is the recommended mode for multi-user and production deployments.

| Variable | Required | Description | Example | |----------|----------|-------------|---------| | LOSANT_RESOURCE_URL | Yes | MCP server resource URL — must prefix-match the JWT audience claim | https://mcp.your-domain.com | | LOSANT_OAUTH_SCOPES | No | Fallback OAuth scopes requested during authorization | all.Organization.bounded, only.User.read |

Common Variables

| Variable | Default | Description | |----------|---------|-------------| | PORT | 3000 | Server port | | HOST | null | Server host (null = all interfaces) | | NODE_ENV | development | Environment (production recommended) | | LOSANT_API_URL | https://api.losant.com | Losant API endpoint | | MCP_TITLE | "Losant" | Server title shown in MCP clients | | MCP_ICON_URL | "" | Server icon URL (SVG format) | | ROLLBAR_KEY | "" | Rollbar error reporting key | | SHUTDOWN_TIMEOUT | 10000 | Graceful shutdown timeout (milliseconds) | | ENABLE_OAUTH | false | Set to true to enable OAuth endpoints |

Example .env — API Token Mode

# Authentication
LOSANT_API_TOKEN=your-losant-api-token

# Optional
PORT=3000
NODE_ENV=production
MCP_TITLE=Losant MCP Server

Example .env — OAuth Mode

# Authentication
ENABLE_OAUTH=true
LOSANT_RESOURCE_URL=https://mcp.your-domain.com

# Optional
PORT=3000
NODE_ENV=production
MCP_TITLE=Losant MCP Server
ROLLBAR_KEY=your-rollbar-api-key

---

Usage

Claude Desktop Integration

API Token Mode (Default)

When ENABLE_OAUTH=false, the server uses LOSANT_API_TOKEN for all Losant API calls. No bearer token is required from the MCP client — just point Claude Desktop at the server:

{
  "mcpServers": {
    "losant": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

OAuth 2.0 Mode

When ENABLE_OAUTH=true, each client must authenticate against the Losant auth server before making requests. Claude Desktop handles this automatically:

{
  "mcpServers": {
    "losant": {
      "url": "https://mcp.your-domain.com/mcp"
    }
  }
}

On first connection, Claude will:

1. Discover the OAuth server via /.well-known/oauth-protected-resource
2. Redirect you to log in to your Losant account
3. Request the configured scopes
4. Include the resulting bearer token on every subsequent request

Using MCP Tools

Once connected (either mode), you can ask Claude:

• "List my Losant applications"
• "Show devices in application X"
• "Get temperature data for device Y"

HTTP API

The server exposes standard MCP endpoints over HTTP:

POST /mcp

Main MCP endpoint for tool calls and resource queries.

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "losant_query",
    "arguments": {
      "operation": "list",
      "resourceType": "application"
    }
  }
}

Headers:

Authorization: Bearer 
Content-Type: application/json

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{
      "type": "text",
      "text": "{\"count\":5,\"items\":[...]}"
    }]
  }
}

GET /healthz

Health check endpoint.

Response:

{"ok":true,"server":"losant-mcp-server"}

GET /.well-known/oauth-protected-resource

OAuth 2.0 Protected Resource Metadata (RFC 9728).

Response:

{
  "resource": "https://mcp.your-domain.com/mcp",
  "authorization_servers": ["https://accounts.losant.com/oauth"],
  "bearer_methods_supported": ["header"],
  "scopes_supported": [ "all.Application.read", "all.Application.bounded", "only.Organization.read", "only.Organization.bounded", "all.Organization.read", "all.Organization.bounded", "only.User.read" ]
}

---

MCP Tools

1. losant_query

Query Losant resources (applications, devices, flows, data tables, etc.).

Parameters:

• operation - "list" or "get"
• resourceType - Type of resource (application, device, flow, etc.)
• applicationId - Application ID (required for app-scoped resources)
• parentResourceId - Parent resource ID (for nested resources)
• resourceId - Resource ID (required for "get" operation)
• page, perPage - Pagination
• filterField, filter - Filtering
• sortField, sortDirection - Sorting
• query - Advanced MongoDB-style queries

Supported Resource Types:

• Top-level: application
• App-scoped: event, device, applicationKey,deviceRecipe,dataTable,webhook,integration,applicationDashboard,notebook,flow,resourceJob,credential,file,privateFile,experienceDomain,experienceEndpoint,experienceGroup,experienceSlug,experienceUser,experienceVersion,experienceView
• Nested: flowVersion (requires flowId), dataTableRow (requires dataTableId)

Example: List Applications

{
  "name": "losant_query",
  "arguments": {
    "operation": "list",
    "resourceType": "application",
    "perPage": 10
  }
}

Example: Get Device by ID

{
  "name": "losant_query",
  "arguments": {
    "operation": "get",
    "resourceType": "device",
    "applicationId": "507f1f77bcf86cd799439011",
    "resourceId": "507f1f77bcf86cd799439012"
  }
}

Example: List Devices with Filter

{
  "name": "losant_query",
  "arguments": {
    "operation": "list",
    "resourceType": "device",
    "applicationId": "507f1f77bcf86cd799439011",
    "filterField": "name",
    "filter": "Temperature*",
    "perPage": 25
  }
}

2. losant_write

Create or update Losant resources. Read losant://guides/losant-write-tool before calling for operations, schema links, PATCH semantics, and resource-specific notes.

Parameters:

• operation - "createOne" (POST) or "updateOne" (PATCH)
• resourceType - Type of resource to create or update
• applicationId - Application ID (required for all app-scoped resources)
• resourceId - Resource ID (required for updateOne, except application and applicationReadme)
• parentResourceId - Parent resource ID (required for nested resources)
• body - Resource data — check losant://schemas/{resourceType}Post or losant://schemas/{resourceType}Patch for the exact shape

Supported Resource Types:

• device, deviceRecipe, dataTable, dataTableRow, webhook, integration, resourceJob, applicationKey, credential, file, privateFile, notebook
• experienceDomain, experienceEndpoint, experienceGroup, experienceSlug, experienceUser, experienceVersion, experienceView
• application, applicationReadme
• Nested: dataTableRow (requires parentResourceId = dataTableId)

Key behaviors:

• PATCH is partial — send only the fields you want to change; omitted fields are left unchanged
• createOne is not supported for event, application, or applicationReadme
• application and applicationReadme do not require resourceId for updateOne
• applicationKey returns the key and secret on createOne only — surface them to the user immediately
• applicationReadme body shape: { "content": "..." }

Example: Create a Device

{
  "name": "losant_write",
  "arguments": {
    "operation": "createOne",
    "resourceType": "device",
    "applicationId": "507f1f77bcf86cd799439011",
    "body": {
      "name": "My Sensor",
      "deviceClass": "standalone",
      "attributes": [
        { "name": "temperature", "dataType": "number" }
      ]
    }
  }
}

Example: Update a Webhook

{
  "name": "losant_write",
  "arguments": {
    "operation": "updateOne",
    "resourceType": "webhook",
    "applicationId": "507f1f77bcf86cd799439011",
    "resourceId": "507f1f77bcf86cd799439012",
    "body": {
      "name": "Updated Webhook Name"
    }
  }
}

Example: Insert a Data Table Row

{
  "name": "losant_write",
  "arguments": {
    "operation": "createOne",
    "resourceType": "dataTableRow",
    "applicationId": "507f1f77bcf86cd799439011",
    "parentResourceId": "507f1f77bcf86cd799439013",
    "body": {
      "sensorId": "abc123",
      "temperature": 22.5
    }
  }
}

3. losant_timeseries

Query time-series device data and state information.

Parameters:

• operation - Operation type (see below)
• applicationId - Application ID (required)
• deviceId - Device ID (for state/command/logs)
• query - Query object (for timeSeriesQuery/lastValueQuery)
• start, end - Time range
• limit, offset - Pagination

Operations:

• timeSeriesQuery - Query time-series data with aggregation
• lastValueQuery - Get last reported values
• getState - Get device state history
• getCompositeState - Get composite device state
• getCommand - Get device command history
• getLogEntries - Get device log entries

Example: Time-Series Aggregation

{
  "name": "losant_timeseries",
  "arguments": {
    "operation": "timeSeriesQuery",
    "applicationId": "507f1f77bcf86cd799439011",
    "query": {
      "aggregation": {
        "duration": "1h",
        "operation": "mean"
      },
      "devices": [{"id": "507f1f77bcf86cd799439012"}],
      "attributes": ["temperature", "humidity"]
    }
  }
}

Example: Get Last Values

{
  "name": "losant_timeseries",
  "arguments": {
    "operation": "lastValueQuery",
    "applicationId": "507f1f77bcf86cd799439011",
    "query": {
      "deviceIds": ["507f1f77bcf86cd799439012"],
      "attributes": ["temperature"]
    }
  }
}

---

Authentication

The server supports two mutually exclusive authentication modes controlled by ENABLE_OAUTH.

Mode 1: API Token (Default — ENABLE_OAUTH=false)

Set LOSANT_API_TOKEN to a Losant API token. The server uses this token for every call to the Losant API, regardless of which MCP client is connected. No bearer token is required from the client.

This mode is ideal for:

• Local development
• Single-user deployments
• Environments where OAuth is not available

Mode 2: OAuth 2.0 (ENABLE_OAUTH=true)

Each MCP client connection must authenticate with the Losant OAuth server before making requests. The server implements OAuth 2.0 Bearer Token authentication with shallow validation:

1. Client obtains JWT from Losant OAuth server
2. Client includes JWT in Authorization: Bearer header
3. Server validates JWT:

• Audience (aud) prefix-matches LOSANT_RESOURCE_URL
• Expiry (exp) is in the future
• No signature verification (delegated to Losant API)

1. Server creates MCP instance bound to that bearer token
2. Losant API validates signature and scopes

This mode is ideal for:

• Multi-user deployments
• Production environments
• Scenarios requiring per-user access control

Security Model

• ✅ Token validated on every request
• ✅ Audience claim prevents token reuse across services
• ✅ Per-request server instances prevent token leakage
• ✅ Signature verification delegated to Losant API
• ✅ RFC-compliant error responses with WWW-Authenticate headers

Supported RFCs (OAuth Mode)

• RFC 6750 - OAuth 2.0 Bearer Token Usage
• RFC 7235 - HTTP Authentication (WWW-Authenticate)
• RFC 7230 - HTTP Message Syntax (quoted-string)
• RFC 8707 - Resource Indicators (audience arrays)
• RFC 9728 - Protected Resource Metadata

---

Deployment

Production Checklist

Both modes:

• [ ] Set NODE_ENV=production
• [ ] Set up HTTPS reverse proxy (nginx, Cloudflare, etc.)
• [ ] Configure Rollbar for error reporting
• [ ] Enable health checks
• [ ] Set appropriate resource limits (memory, CPU)
• [ ] Configure graceful shutdown timeout
• [ ] Set up monitoring and alerting

API Token mode (ENABLE_OAUTH=false):

• [ ] Set `LOSANTAPITOKE

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Losant
• Source: Losant/losant-mcp-server
• License: MIT
• Homepage: https://www.losant.com

Install and usage instructions live in the source repository linked above.