Itcons.app MCP Server

Model Context Protocol server for connecting AI assistants to Itcons.app.

Itcons.app is a business operations platform for managing work reports, work orders, projects, clients, users, and related operational resources. It is designed to help teams digitize field and office workflows around daily reports, assignments, task tracking, and service execution.

This package can run in two modes:

• Local stdio mode for clients such as Codex, Claude Desktop, and other local MCP hosts.
• Remote HTTP mode for hosted MCP clients such as ChatGPT Apps or other clients that require a public HTTPS MCP endpoint.

With this MCP server, an assistant can query Itcons.app data, search work reports and work orders, list operational catalogs such as statuses, users, resources, projects, and clients, and create supported Itcons.app records when the configured user has permission to do so.

Features

• Authenticate with POST /api/login_check.
• Use Bearer authentication for Itcons.app API calls.
• Resolve the API base URL from ITCONS_DOMAIN.
• List statuses, users, resources, clients, projects, work order types, and work report models.
• Search work reports and work orders.
• Create clients, projects, users, and work orders.

Webhooks are intentionally not included in this MCP server. The remote HTTP mode is for MCP client traffic, not inbound Itcons.app webhook delivery.

Installation

From npm:

npm install -g @itcons-app/mcp

From this repository:

npm install
npm run check

If Node was installed with Homebrew and node/npm are not in your PATH, use:

/opt/homebrew/opt/node/bin/npm install
/opt/homebrew/opt/node/bin/npm run check

Configuration

The local stdio server reads Itcons.app credentials from environment variables.

ITCONS_DOMAIN=demo
ITCONS_USERNAME=user@example.com
ITCONS_PASSWORD=change-me
ITCONS_TIMEZONE=Europe/Madrid

For https://demo.itcons.app, set:

ITCONS_DOMAIN=demo

You may use an existing Bearer token instead of username/password:

ITCONS_DOMAIN=demo
ITCONS_TOKEN=ey...

ITCONS_API_BASE_URL is optional. If omitted, the server uses:

https://ITCONS_DOMAIN.itcons.app/api

MCP Client Example

Example configuration using a globally installed package:

{
  "mcpServers": {
    "itcons-app": {
      "command": "itcons-app-mcp",
      "env": {
        "ITCONS_DOMAIN": "demo",
        "ITCONS_USERNAME": "user@example.com",
        "ITCONS_PASSWORD": "change-me",
        "ITCONS_TIMEZONE": "Europe/Madrid"
      }
    }
  }
}

Remote HTTP Server

Start the remote MCP server:

PORT=3000 \
HOST=127.0.0.1 \
ITCONS_MCP_PUBLIC_URL=https://mcp.example.com \
ITCONS_OAUTH_CLIENT_ID=itcons-app-chatgpt \
ITCONS_OAUTH_CLIENT_SECRET=change-me \
npm run start:http

The remote server exposes:

• MCP Streamable HTTP endpoint: https://mcp.example.com/mcp
• SSE-compatible endpoint: https://mcp.example.com/sse
• OAuth authorize URL: https://mcp.example.com/oauth/authorize
• OAuth token URL: https://mcp.example.com/oauth/token
• OAuth dynamic client registration URL: https://mcp.example.com/oauth/register
• Health check: https://mcp.example.com/health

For ChatGPT's "Create app" screen, use the public MCP URL:

https://mcp.example.com/mcp

If a client specifically asks for an SSE URL, use:

https://mcp.example.com/sse

When the user connects the app, the OAuth login page asks for their Itcons.app email and password. If ITCONS_DOMAIN_LOOKUP_URL is configured, the page tries to detect the Itcons.app domain from the email; otherwise the user can type the domain manually. The server validates those credentials with Itcons.app and stores an in-memory session token for subsequent MCP calls.

Example configuration using a local checkout:

{
  "mcpServers": {
    "itcons-app": {
      "command": "node",
      "args": [
        "/absolu

... [View full README on GitHub](https://github.com/itcons-app/mcp#readme)