mia-platform · ThisIsDemetrio · Oct 3, 2025 · Sep 1, 2025 · Sep 1, 2025 · Sep 1, 2025
diff --git a/README.md b/README.md
@@ -5,35 +5,23 @@
 
 ## Introduction
 
-The Mia-Platform Console MCP Server is a [Model Context Protocol (MCP)] server that provides seamless integration
+The Mia-Platform Console MCP Server is a [Model Context Protocol (MCP)](mcp-intro) server that provides seamless integration
 with Mia-Platform Console APIs, enabling advanced automation and interaction capabilities for developers and tools.
 
 ## Prerequisites
 
-1. To run the server in a container, you will need to have [Docker] installed.
-1. Once Docker is installed, you will also need to ensure Docker is running.
-1. Lastly you will need to a way ot authenticate to your Mia-Platform Console installation, you either have to:
-    - [Create a Mia-Platform Service Account] with `Client Secret Basic`
-    authorization mode (the only one supported at this time)
-  the `Client Secret Basic` one.
-    - Use miactl authentication: if you have [`miactl`][miactl] installed you can run any command to login,
-     the same session will then be used by the mcp server to authenticate.
-
-> [!WARNING]
-> When using miactl session, auto-refresh by the MCP Server is not currently supported,
-> once the session created with miactl expires you have to refresh it with miactl again.
----
-> [!IMPORTANT]
-> When using miactl session, the host you provide to the MCP Server **MUST** be the exact same as the one
-> you have logged in with miactl, including scheme and any possible trailing slash.
+To use the Mia-Platform Console MCP Server in your client (such as Visual Studio Code, Claude Desktop, Cursor, Gemini CLI or others), you first need to have a valid account on the Mia-Platform Console instance you want to communicate with. You will be required also to include the instance host address you in the environment variable named `CONSOLE_HOST`.
 
-### How to Run
+You may decide to access via:
+
+- Service Account to perform machine-2-machine authentication and have full access to the MCP capabilities to perform operations on the Company where the S.A. has been created (for more information, visit [our official documentation on how to create a Mia-Platform Service Account](docs-create-service-account)). If you do so, you need to include the environment variables `MIA_PLATFORM_CLIENT_ID` and `MIA_PLATFORM_CLIENT_SECRET`.
+- Using your own credentials: Mia-Platform Console MCP Server follows the [Model Context Protocol specifications on authentication](mcp-specs-auth) using OAuth2.1 and Dynamic Client Registration: clients that follow that specifications will be able to discover the authentication endpoints of the selected Mia-Platform instance you want to access to and guide you to perform the log in.
 
-To run the MCP server on your machine you can follow the instructions in the [Setup Documentation]
+### How to Run
 
-### Run from sources
+You can run stable versions of the Mia-Platform Console MCP Server using [Docker](Docker). You can get detailed guide using the [following guide](20-setup).
 
-If you don't have Docker installed, you can use NPM and Node.js for running it locally. Once you have cloned the
+If you don't have Docker installed, or you simply wish to run it locally, you can use NPM and Node.js. Once you have cloned the
 project you can run the commands:
 
 ```sh
@@ -60,19 +48,53 @@ Once these steps are completed you can setup the MCP server using the `node` com
           "start",
           "--stdio",
           "--host=https://console.cloud.mia-platform.eu"
-        ],
-        "env": {
-          "MIA_PLATFORM_CLIENT_ID": "<YOUR_CLIENT_ID>",
-          "MIA_PLATFORM_CLIENT_SECRET": "<YOUR_CLIEND_SECRET>"
-        }
+        ]
       }
     }
   }
 }
 ```
 
-> [!TIP]
-> If you have a `.env` file configured with your credentials, you can omit the `env` section from the configuration above as the server will automatically load the environment variables.
+:::tip
+
+Alternatively, you start the service after the build with the following command:
+
+```sh
+node mcp-server start
+```
+
+Then add the mcp server to your client simply including the url. As example for VS Code:
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "mia-platform-console": {
+        "type": "http",
+        "url": "http://localhost:3000/console-mcp-server/mcp"
+      }
+    }
+  }
+}
+```
+
+Instead of `3000`, please include the port defined in the environment variable `PORT`. More detail in the [Environment Variables](#environment-variables) section.
+
+:::
+
+### Environment Variables
+
+Environment variables located inside a file named `.env` are automatically included at service startup.
+
+| Variable Name | Description | Required | Default Value |
+|---------------|-------------|----------|---------------|
+| `LOG_LEVEL` | Log level of the application | No | `info` |
+| `PORT` | Port number for the HTTP server | No | `3000` |
+| `CONSOLE_HOST` | The host address of the Mia-Platform Console instance | Yes | - |
+| `MIA_PLATFORM_CLIENT_ID` | Client ID for Service Account authentication | No | - |
+| `MIA_PLATFORM_CLIENT_SECRET` | Client secret for Service Account authentication | No | - |
+| `CLIENT_EXPIRY_DURATION` | Duration in seconds of clients generated with the DCR authentication flow. After this time, the client will be expired and cannot be used anylonger. | No | `300` |
+
 
 ## Local Development
 
@@ -123,10 +145,10 @@ node --test --import tsx <FILE_PATH>
 [pipeline-link]: https://github.com/mia-platform/console-mcp-server/actions
 [build-svg]: https://img.shields.io/github/actions/workflow/status/mia-platform/console-mcp-server/build-and-test.yaml
 [license-svg]: https://img.shields.io/github/license/mia-platform/console-mcp-server
-[Model Context Protocol (MCP)]: https://modelcontextprotocol.io/introduction
+[mcp-intro]: https://modelcontextprotocol.io/introduction
+[mcp-specs-auth]: https://modelcontextprotocol.io/specification/2025-06-18
 [Docker]: https://www.docker.com/
-[Setup Documentation]: /docs/20_setup.md
-[Create a Mia-Platform Service Account]: https://docs.mia-platform.eu/docs/development_suite/identity-and-access-management/manage-service-accounts
+[20-setup]: /docs/20_setup.md
+[docs-create-service-account]: https://docs.mia-platform.eu/docs/development_suite/identity-and-access-management/manage-service-accounts
 [nvm]: https://github.com/nvm-sh/nvm
 [mise]: https://mise.jdx.dev
-[miactl]: https://github.com/mia-platform/miactl
diff --git a/default.env b/default.env
@@ -1,2 +1,17 @@
+# Application port
+PORT=3000
+# Fastify log level
+LOG_LEVEL=info
+
+# Mia-Platform Console instance to communicate with (required)
+CONSOLE_HOST=<CONSOLE_URL>
+
+# If you have a Mia-Platform Service Account on your company, please include
+# the clientId and clientSecret here to perform M2M authentication.
+# If these values are absent, OAuth2 authentication flow will be performed.
 MIA_PLATFORM_CLIENT_ID=<SERVICE_ACCOUNT_CLIENT_ID>
 MIA_PLATFORM_CLIENT_SECRET=<SERVICE_ACCOUNT_CLIENT_SECRET>
+
+# In case OAuth2 authentication, you can set the time in seconds in which the client credentials
+# generated will expire (optional; default: 300)
+CLIENT_EXPIRY_DURATION=300
diff --git a/docs/20_setup.md b/docs/20_setup.md
@@ -5,39 +5,26 @@
 ### Prerequisites
 
 1. To run the server in a container, you will need to have [Docker] installed.
-1. Once Docker is installed, you will also need to ensure Docker is running.
-1. Pull the docker image `docker pull ghcr.io/mia-platform/console-mcp-server`
-1. Login to Mia-Platform. You have two options:
-    - (a) *User Authentication* - Use miactl authentication: if you have [`miactl`][miactl] installed you can login and
-      the same session will then be used by the mcp server to authenticate. To login just type `miactl company list`,
-      or any other miactl command, the browser will be opened and you can use your credentials to login. You will be
-      able to access to all companies and projects that have been granted to your user.
-    - (b) *Service Account* - [Create a Mia-Platform Service Account] with `Client Secret Basic` authorization mode
-      (the only one supported at this time) the `Client Secret Basic` one. In that case you can access to just one
-      company at a time.
-
-> [!WARNING]
-> When using miactl session, auto-refresh by the MCP Server is not currently supported,
-> once the session created with miactl expires you have to refresh it with miactl again.
----
-> [!IMPORTANT]
-> When using miactl session, the host you provide to the MCP Server **MUST** be the exact same as the one
-> you have logged in with miactl, including scheme and any possible trailing slash.
+2. Once Docker is installed, you will also need to ensure Docker is running.
+3. Pull the docker image `docker pull ghcr.io/mia-platform/console-mcp-server` at your own preferred version (or `latest` if you want to try the nightly build)
+4. Login to Mia-Platform. You have two options:
+  - (a) *Service Account* - [Create a Mia-Platform Service Account] with `Client Secret Basic` authorization mode (the only one supported at this time) the `Client Secret Basic` one. In that case you can access to just one company at a time.
+  - (b) *User Authentication* - Assuming you have a valid Mia Platform account, you can simply omit the information about the service account and - at the MCP startup - your client will ask you to open for you a webpage where you can execute the login.
+
 
 ### VS Code
 
-For manual installation, add the following JSON block to your User Settings (JSON) file in VS Code. You can do this by
-pressing `Ctrl + Shift + P` and typing `Preferences: Open User Settings (JSON)`. Optionally, you can add it to a file
-called `.vscode/mcp.json` in your workspace.
+For manual installation, add the following JSON block to your MCP Server list file in VS Code.
+You can do this by pressing `Ctrl + Shift + P` and typing `MCP: List Servers`, or you can create a `.vscode/mcp.json` file inside your repository.
 
 Once you have done it, toggle Agent mode (located by the Copilot Chat text input) and the server will start.
 
 :::note
-The `mcp` key is not needed in the `.vscode/mcp.json` file.  
-Also note that you can change the host of the Console instance to your custom installation
+The `mcp` key is not needed in the `.vscode/mcp.json` file.
+Also note that you can change the host of the Console instance to your custom installation.
 :::
 
-This is the configuration if you are using miactl (a)
+This is the configuration if you are using User Authentication with OAuth2 and Dynamic Client Registration.
 
 ```json
 {
@@ -63,7 +50,7 @@ This is the configuration if you are using miactl (a)
 }
 ```
 
-This is the configuration if you are using Service Account (b)
+This is the configuration if you are using a predefined Service Account.
 
 ```json
 {
@@ -110,11 +97,9 @@ This is the configuration if you are using Service Account (b)
 ```
 
 :::tip
-If you want to use User-based authentication with [`miactl`][miactl] you have to omit from the env object:
-
-- `MIA_PLATFORM_CLIENT_ID`
-- `MIA_PLATFORM_CLIENT_SECRET`
+If both the environment variables `MIA_PLATFORM_CLIENT_ID` and `MIA_PLATFORM_CLIENT_SECRET` are included, you will be asked to authenticate with your credentials. In this case, make sure you open the web page that Visual Studio Code will prompt you to open.
 
+If you have issues to authenticate because of an `invalid_client` error, please try to remove the DCR clients registrated using the `Authentication: Remove Dynamic Authentication Providers` option from the application menu.
 :::
 
 More about using MCP server tools in [VS Code's agent mode documentation].

diff --git a/eslint.config.mjs b/eslint.config.mjs
@@ -43,7 +43,7 @@ export default tseslint.config(
           ignoreCase: true,
           ignoreDeclarationSort: false,
           ignoreMemberSort: false,
-          memberSyntaxSortOrder: [ 'none', 'all', 'single', 'multiple' ],
+          memberSyntaxSortOrder: ['none', 'all', 'single', 'multiple'],
           allowSeparatedGroups: true,
         },
       ],

diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -31,6 +31,7 @@
   },
   "homepage": "https://github.com/mia-platform/console-mcp-server#readme",
   "dependencies": {
+    "@fastify/formbody": "^8.0.2",
     "@mia-platform/console-types": "^0.39.4",
     "@modelcontextprotocol/sdk": "^1.19.1",
     "commander": "^14.0.1",
@@ -52,4 +53,4 @@
     "typescript": "^5.9.3",
     "typescript-eslint": "^8.45.0"
   }
-}
+}
diff --git a/src/apis/http-client/index.test.ts b/src/apis/http-client/index.test.ts
@@ -165,7 +165,6 @@ suite('http client test suite without authentication', () => {
     t.assert.deepEqual(result, { message: 'test' })
   })
 
-
   test('set custom headers, custom accept', async (t) => {
     const customHeadersClient = new HTTPClient(mockedEndpoint, '', '', {
       'custom-header': 'customValue',
@@ -199,6 +198,7 @@ suite('http client test suite with authentication', () => {
   let agent: MockAgent
   beforeEach(() => {
     agent = new MockAgent()
+    agent.disableNetConnect()
     setGlobalDispatcher(agent)
     agent.get(mockedEndpoint).intercept({
       path: '/api/m2m/oauth/token',
@@ -333,7 +333,7 @@ suite('http client test suite with authentication', () => {
   test('set custom headers, don\'t override fixed ones', async (t) => {
     const client = new HTTPClient(mockedEndpoint, clientID, clientSecret, {
       'custom-header': 'customValue',
-      Authorization: 'custom authorization',
+      Authorization: 'Bearer token-coming-from-original-request',
       Accept: 'custom accept value',
       'User-Agent': 'custom user agent',
     })
@@ -342,7 +342,7 @@ suite('http client test suite with authentication', () => {
       path: testPath,
       headers: {
         'custom-header': 'customValue',
-        Authorization: `Bearer ${accessToken}`,
+        Authorization: 'Bearer token-coming-from-original-request',
         Accept: 'custom accept value',
         'User-Agent': `${name}/${version}`,
       },