Desco MCP

Disclaimer: This is an unofficial, community-built DESCO API provided for educational and research purposes. It is not affiliated with or endorsed by DESCO and may change, become unavailable, or return inaccurate information. The API is based on publicly available open-source resources, and the author assumes no responsibility for any loss or damage resulting from its use.

Desco MCP is a Node.js and TypeScript Model Context Protocol (MCP) server for DESCO customer data. It exposes DESCO account lookups and billing/usage data as MCP tools and exposes them over a Streamable HTTP endpoint. The server binds a validated API key to a specific accountNo and meterNo, so callers do not need to pass those identifiers on each tool call when using the HTTP flow.

Features

• Streamable HTTP MCP server with a protected /:apiKey/mcp endpoint

• API-key-based authentication using AES-256-GCM encryption

• DESCO customer lookup tools

• customer location lookup

• daily and monthly consumption queries

• balance lookup

• recharge history lookup

• recent event lookup

• local development tunnel support via ngrok and Docker Compose

• generated API key command for account-specific access

Related MCP server: Cemig: Obter Instalações

Tech Stack

• Node.js

• TypeScript

• Hono

• @hono/node-server

• @modelcontextprotocol/sdk

• Zod

• esbuild

• tsx

• Docker Compose (for the ngrok development tunnel)

This project does not use a database. It calls the DESCO backend over HTTP using a configured base URL.

Project Structure

desco-mcp/
├── .env.example
├── .gitignore
├── docker-compose.dev.yml
├── package.json
├── pnpm-workspace.yaml
├── tsconfig.json
├── scripts/
│   └── generate-api-key.js
├── src/
│   ├── index.ts
│   ├── main.ts
│   ├── server.ts
│   ├── lib/
│   │   └── api-client.lib.ts
│   ├── mcp/
│   │   └── desco.tools.ts
│   ├── schema/
│   │   ├── desco.schema.ts
│   │   └── mcp-tool.schema.ts
│   ├── services/
│   │   └── desco.service.ts
│   ├── types/
│   │   └── desco.type.ts
│   └── utils/
│       ├── api-key.utils.ts
│       ├── desco.utils.ts
│       ├── mcp.utils.ts
│       └── masking.ts
├── README.md
└── node_modules/

Key implementation areas:

• src/index.ts: boots the server and chooses between stdio or Streamable HTTP mode

• src/main.ts: starts the HTTP server and validates API keys per request

• src/server.ts: creates an MCP server and registers DESCO tools

• src/mcp/desco.tools.ts: defines and registers the available MCP tools

• src/services/desco.service.ts: makes HTTP requests to the DESCO backend

• src/utils/api-key.utils.ts: generates and validates opaque API keys

• scripts/generate-api-key.js: CLI helper for creating an API key from an account number and meter number

Prerequisites

Before running the project, make sure you have:

• Node.js and npm installed

• A valid DESCO base URL in the environment configuration

• An API_KEY_SECRET value for key generation and validation

• Access to a DESCO account number and meter number for generating API keys

• Docker Compose installed only if you want to run the ngrok tunnel in docker-compose.dev.yml

Node.js >=24 is required, pinned via the engines field in package.json.

Installation

git clone <repository-url>
cd desco-mcp
cp .env.example .env
npm install

Then fill in the required values in .env before starting the server.

Environment Variables

The project reads environment variables via --env-file=.env in the scripts. The template is defined in .env.example.

API_KEY_SECRET=
PORT=3000
DESCO_BASE_URL=
NGROK_AUTHTOKEN=

Running the Project

Start the app in development mode

npm run dev

This starts the server using the .env file and watches for source changes.

Build the app

npm run build

This runs TypeScript validation with tsc --noEmit and bundles the project into dist/index.js using esbuild.

Start the built app

npm start

This launches the compiled server from dist/index.js using the .env file.

Inspect the MCP server

npm run mcp:inspector

This runs the official MCP inspector for debugging and testing the server.

Generate an API key

npm run generate-api-key -- <accountNo> <meterNo>

Example:

npm run generate-api-key -- 123456789 987654321

This prints a generated opaque API key that can be used in the /:apiKey/mcp route.

Available Scripts

API Documentation

This project does not expose a traditional REST API in the same way as a normal web service. Instead, it exposes an MCP server over a Streamable HTTP endpoint and registers DESCO tools with the Model Context Protocol.

Base URL

When running locally:

http://localhost:3000

Endpoint

GET /
POST /:apiKey/mcp
GET /:apiKey/mcp
DELETE /:apiKey/mcp
OPTIONS /:apiKey/mcp

The project registers a CORS configuration and accepts MCP requests on /:apiKey/mcp.

Authentication

The route uses a path-segment API key:

http://localhost:3000/<API_KEY>/mcp

The key is validated with validateApiKey(). If the key is malformed, expired, tampered with, or generated using a different API_KEY_SECRET, the server returns a JSON-RPC error with HTTP status 401.

MCP Tools

The server registers the following tools:

Example tool call pattern

The exact request format is the MCP protocol request payload sent to the HTTP endpoint, not a custom JSON REST body defined in this repository.

POST /<API_KEY>/mcp HTTP/1.1
Content-Type: application/json

The server then responds with standard MCP JSON-RPC-style content.

Database

No database is configured or used by this project.

The application instead queries a remote DESCO API endpoint using a configured DESCO_BASE_URL. All customer data is retrieved through those HTTP requests; it is not stored locally.

Authentication & Authorization

Authentication is implemented through a generated opaque API key rather than a session system or bearer token flow.

Flow:

1. API_KEY_SECRET is used to derive a SHA-256 key.

2. generateApiKey(accountNo, meterNo) encrypts { accountNo, meterNo } with AES-256-GCM.

3. The resulting base64url string is passed as the route segment in /:apiKey/mcp.

4. validateApiKey(apiKey) decrypts and validates the payload.

5. The resolved accountNo and meterNo are bound to the request before tool execution.

If the secret changes, all previously generated keys become invalid.

Configuration

Important configuration files:

• .env: runtime secrets and app settings loaded during local execution

• .env.example: template for required variables

• docker-compose.dev.yml: ngrok tunnel for exposing the local HTTP server to the internet during development

• tsconfig.json: TypeScript compiler configuration

• package.json: scripts and dependency configuration

Testing

This repository currently does not include a dedicated test framework, test script, or test directory.

The only project verification command present is:

npm run build

This validates TypeScript and ensures the project bundles correctly.

Code Quality

The project performs TypeScript checking as part of the build:

npm run build

There are no separate lint, formatting, or pre-commit configuration files in the repository at the moment.

Deployment

The application is designed to run as a Node.js service.

Local deployment

npm install
npm run build
npm start

Public development exposure

A Docker Compose file is included for exposing the local app via ngrok:

docker compose -f docker-compose.dev.yml up -d

This uses NGROK_AUTHTOKEN from .env and forwards traffic to host.docker.internal:3000.

Docker

The repository contains docker-compose.dev.yml but no Dockerfile for the application itself.

Requirements

• Docker Engine

• Docker Compose

• A valid NGROK_AUTHTOKEN in .env

Start the tunnel

docker compose -f docker-compose.dev.yml up -d

Stop the tunnel

docker compose -f docker-compose.dev.yml down

Troubleshooting

API_KEY_SECRET environment variable is not set

Add a value to API_KEY_SECRET in .env before starting the server.

DESCO_BASE_URL environment variable is not set

Set DESCO_BASE_URL to the correct DESCO backend base URL.

Invalid or expired API key

This usually means:

• the key was generated with a different API_KEY_SECRET

• the key payload is malformed

• the key has been altered

Generate a new key with:

npm run generate-api-key -- <accountNo> <meterNo>

Ngrok tunnel is not working

Verify that:

• NGROK_AUTHTOKEN is set in .env

• Docker Compose is running correctly

• the app is listening locally on port 3000

Server not reachable on the expected route

The server is started on:

http://localhost:3000/{YOUR_API_KEY}/mcp

The root route / only returns a welcome message and version metadata.

Security

• Keep .env files out of version control.

• Treat API_KEY_SECRET as a private secret; rotating it invalidates all prior API keys.

• The app validates API keys before processing requests.

• CORS is enabled with origin: "*", which is permissive and should be reviewed before production use.

• The code validates DESCO API payloads with Zod schemas before returning values to callers.

5. Keep route and schema updates consistent with the actual DESCO API contract and the implementation under src/.

License

This project is licensed under the MIT License.