Itcons.app

io.github.itcons-appPublished by GitHub account itcons-appv0.5.1Updated Oct 25, 2026

Connect AI assistants to Itcons.app work orders, reports, projects, users, and resources.

VerifiedStreamable HTTPWeb executableProductivity & Workflow Business & Commerce

Server details

Identifier: io.github.itcons-app/mcp
Transport: Streamable HTTP
Runtime: Web executable
Trust: Verified
Published: Sep 16, 2026

Security note

MCP servers receive tool arguments from a conversation and may perform external actions. Review what a server can do before you enable it, and give it only the access it needs.

The registry verified the GitHub account itcons-app for this listing. That does not show the account is the product's maker.

SourceWeft's checks cover whether the listing is complete and the endpoint answered; they do not review the server's code or what its tools do.

Add a badge to your README

Show readers this MCP server is listed on SourceWeft. The badge links to this page.

[![Listed on SourceWeft](https://sourceweft.com/badge/mcp/io.github.itcons-app%2Fmcp.svg)](https://sourceweft.com/mcp/io.github.itcons-app%2Fmcp?utm_source=readme&utm_medium=badge)

Overview

AI-generated overview

Connects an AI assistant to Itcons.app work reports, work orders, projects, clients, users and calendars through API v3, read-only or with write access.

What you can do: Check the connection and list or get users, clients, projects, categories, resources, calendars, leave types and statuses
List, get and search work reports, including by date, today's reports and report templates
List and get work order types and work orders
Create and update users, clients, projects, categories, resources, work reports and work orders
Use a reports-only profile with bounded read-only queries and reduced project and work-order fields
When to use it: Useful when an assistant should answer questions about Itcons.app operational data, such as who worked on what, open work orders or project status, or should file work reports and update records without leaving the chat.
Requirements: Runs as a remote HTTPS endpoint with OAuth, or locally via the npm package over stdio. Local mode needs Node.js and the ITCONS_DOMAIN variable plus either ITCONS_USERNAME and ITCONS_PASSWORD or an existing ITCONS_TOKEN; ITCONS_TIMEZONE is optional. Remote hosting needs ITCONS_MCP_PUBLIC_URL and OAuth settings such as ITCONS_OAUTH_CLIENT_SECRET and the state file and secret.

Before you install

Write tools make real changes in Itcons.app, so grant only credentials and installations where the client may modify data. The server handles account credentials (ITCONS_PASSWORD, ITCONS_TOKEN) and OAuth client secrets; keep them out of committed files. Remote deployments should set ITCONS_OAUTH_STATE_FILE and ITCONS_OAUTH_STATE_SECRET, and ITCONS_HTTP_AUTH_DISABLED should only be used for local smoke tests.

Installation

In SourceWeft

Open Itcons.app in the dashboard and add it to a workspace.
Connect the required credentials. They are stored privately and never shown on public pages.
Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Use with an agent

Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.

Read https://sourceweft.com/mcp/io.github.itcons-app%2Fmcp/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.

Read the install guide the agent follows

Other MCP clients

Add this to your client's mcpServers config. The client completes OAuth sign-in on first connect.

{
  "mcpServers": {
    "itcons-app": {
      "type": "http",
      "url": "https://mcp.itcons.app/mcp"
    }
  }
}

README

Itcons.app MCP Server

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

Itcons.app is a business operations platform for managing work reports, work orders, projects, clients, users, calendars, categories, and operational resources.

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 or other clients that require a public HTTPS MCP endpoint.

The MCP uses the existing Itcons.app username/password login flow (POST /api/login_check) and then calls API v3 with Bearer authentication.

Features

Resolve the tenant from ITCONS_DOMAIN.
Call API v3 under https://{ITCONS_DOMAIN}.itcons.app/api/v3.
List and get users, clients, projects, categories, resources, calendars, leave types, work report templates, work reports, work order types, and work orders.
Create and patch API v3 users, clients, projects, categories, resources, work reports, and work orders.
Keep the existing reports-only HTTP profile at /reports-mcp for the current ChatGPT connector.

Webhooks are intentionally not exposed as MCP tools. API v3 documents webhook payloads as outbound deliveries configured inside Itcons.app.

Installation

From npm:

From this repository:

Configuration

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

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

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

ITCONS_API_BASE_URL is optional. If omitted, the server uses:

If ITCONS_API_BASE_URL ends in /api, the server appends /v3 automatically.

MCP Client Example

json

{  "mcpServers": {    "itcons-app": {      "command": "itcons-app-mcp",      "env": {        "ITCONS_DOMAIN": "demo",        "ITCONS_USERNAME": "[email protected]",        "ITCONS_PASSWORD": "change-me",        "ITCONS_TIMEZONE": "Europe/Madrid"      }    }  }}

{  "mcpServers": {    "itcons-app": {      "command": "itcons-app-mcp",      "env": {        "ITCONS_DOMAIN": "demo",        "ITCONS_USERNAME": "[email protected]",        "ITCONS_PASSWORD": "change-me",        "ITCONS_TIMEZONE": "Europe/Madrid"      }    }  }}

Remote HTTP Server

Start the remote MCP server:

bash

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

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
Reports-only MCP endpoint: https://mcp.example.com/reports-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

When a user connects through OAuth, the login page asks for the Itcons.app email/password and domain. If ITCONS_DOMAIN_LOOKUP_URL is configured, the page can detect the domain from the email.

Tools

Read-only tools:

itcons_check_connection
itcons_list_users
itcons_get_user
itcons_list_clients
itcons_get_client
itcons_list_projects
itcons_get_project
itcons_list_categories
itcons_get_category
itcons_list_resources
itcons_get_resource
itcons_list_calendars
itcons_get_calendar
itcons_list_leave_types
itcons_list_work_report_templates
itcons_get_work_report_template
itcons_list_work_reports
itcons_get_work_report
itcons_get_work_report_as_post_payload
itcons_list_work_reports_by_date
itcons_list_today_work_reports
itcons_list_work_order_types
itcons_get_work_order_type
itcons_list_work_orders
itcons_get_work_order
itcons_list_statuses

Write tools:

itcons_create_user
itcons_update_user
itcons_create_client
itcons_update_client
itcons_create_project
itcons_update_project
itcons_create_category
itcons_update_category
itcons_create_resource
itcons_update_resource
itcons_create_work_report
itcons_update_work_report_metadata
itcons_replace_work_report_content
itcons_create_work_order
itcons_update_work_order

Reports-only profile tools exposed by /reports-mcp:

itcons_check_connection
itcons_list_calendars
itcons_list_holidays
itcons_get_working_days
itcons_list_leave_types
itcons_list_projects
itcons_list_work_orders
itcons_list_work_report_models
itcons_search_work_reports
itcons_list_work_reports_by_date
itcons_list_today_work_reports

The reports-only profile keeps its previous work-report tool names for compatibility and adds bounded read-only operational queries. Project and work-order results are reduced to operational fields and exclude notes, user identities, locations, attachments, client details and other unnecessary private data. Public-profile list calls are capped at 50 items, and calendar calculations accept at most 366 inclusive days.

Patch tools accept a payload object with the exact API v3 fields documented by the Postman collection. This keeps the MCP aligned with the API without hiding partial update features such as add and remove operations.

Environment Variables

Variable	Required	Description
`ITCONS_DOMAIN`	Yes	Installation subdomain. For `https://demo.itcons.app`, use `demo`.
`ITCONS_USERNAME`	Yes, unless `ITCONS_TOKEN` is set	Itcons.app username or email.
`ITCONS_PASSWORD`	Yes, unless `ITCONS_TOKEN` is set	Itcons.app password.
`ITCONS_TOKEN`	No	Existing Bearer token. If set, login is skipped.
`ITCONS_API_BASE_URL`	No	Alternative API v3 base URL.
`ITCONS_TIMEZONE`	No	Time zone used by `itcons_list_today_work_reports`. Defaults to `Europe/Madrid`.
`PORT`	No	HTTP server port. Defaults to `3000`.
`HOST`	No	HTTP server bind host. Defaults to `127.0.0.1`.
`ITCONS_MCP_PUBLIC_URL`	Yes for remote mode	Public HTTPS origin, for example `https://mcp.example.com`.
`ITCONS_MCP_PATH`	No	Remote MCP endpoint path. Defaults to `/mcp`.
`ITCONS_REPORTS_MCP_PATH`	No	Reports-only MCP endpoint path. Defaults to `/reports-mcp`.
`ITCONS_MCP_SSE_PATH`	No	SSE-compatible endpoint path. Defaults to `/sse`.
`ITCONS_MCP_ALLOWED_HOSTS`	Recommended for remote mode	Comma-separated allowed Host headers, for example `mcp.example.com`.
`ITCONS_OAUTH_CLIENT_ID`	No	OAuth client ID expected by the remote server. Defaults to `itcons-app-chatgpt`.
`ITCONS_OAUTH_CLIENT_SECRET`	Recommended for remote mode	OAuth client secret expected by the remote server.
`ITCONS_OAUTH_CLIENTS_FILE`	Recommended for public apps	JSON file used to persist dynamically registered OAuth clients.
`ITCONS_OAUTH_STATE_FILE`	Required for restart-safe OAuth	Encrypted state file for access and refresh token sessions.
`ITCONS_OAUTH_STATE_SECRET`	Required with the state file	Long random secret used to encrypt OAuth state at rest.
`ITCONS_DOMAIN_LOOKUP_URL`	No	Endpoint used to detect the Itcons.app domain from an email. Defaults to `https://autov2.itcons.app/webhook/my-domain`.
`ITCONS_HTTP_AUTH_DISABLED`	No	Set to `1` only for local HTTP smoke tests. Disables remote MCP bearer auth.

Development

Run syntax checks:

Run a local MCP discovery smoke test:

Run a local HTTP MCP smoke test:

Run a live read-only smoke test against Itcons.app:

Run a live read-only HTTP smoke test against Itcons.app:

Run a live OAuth smoke test that simulates a hosted-client connection:

Security

Do not commit .env files or real credentials. The package excludes .env, node_modules, and debug logs from npm publication.

Write tools perform real changes in Itcons.app. Use them only with credentials and installations where the MCP client is allowed to make changes.

For remote deployments, configure ITCONS_OAUTH_STATE_FILE and ITCONS_OAUTH_STATE_SECRET. Access and refresh token state is then encrypted at rest and survives process restarts. Authorization codes remain short-lived and in memory.

The file-backed OAuth state is designed for a single Node.js process. Use a shared transactional store before running multiple replicas.

Source: README.md at commit fdbe14d

Tools

This server asks you to sign in, so SourceWeft could not read its tools without an account and has not indexed them. What a connected account sees can depend on that account and its permissions.

Version history

v0.5.1LatestSep 16, 2026

Score

85% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

Reached in the last 30 daysRequired25 pts
Auth declaredRequired10 pts
Tools listed15 pts
Answer tools/list without a credential, or ship a package that starts in a sandbox without one.
DescriptionRequired15 pts
Logo10 pts
Documentation15 pts
License10 pts