Context

Served by Nucleo Core (auth.nucleoplatform.com): which companies the person can work in, which modules each company exposes to AI clients and their API hosts, and the active company.

Base URL, authentication and conventions of this API are on the AI Tools API page.

Endpoints

get/api/mcp/contextGet companies, modules and active company
put/api/mcp/companySet the active company

get/api/mcp/context

Get companies, modules and active company

Requires the nucleo.ai_tools scope.

The companies of the signed-in person in canonical order, with the modules each one can reach through AI clients (connector_enabled) and the base URL of each module's API, plus the active company used by the MCP connector.

active_company_source tells how it was chosen: claim (the org_id hint you passed, or else the org_id of the access token, set with org_id on /oauth/authorize), only (the person has one company), preference (saved with PUT /api/mcp/company or the connector tool nucleo_switch_company), default (first company).

A module with connector_enabled: false has been switched off for AI clients by that company (or has no tools API): do not call it. The connector does not offer its tools, and the module itself refuses AI clients' calls to its AI tools in that company with 403 ai_connector_disabled (the same switches are in the userinfo claim ai_connector_disabled).

GET https://auth.nucleoplatform.com/api/mcp/context

Authentication: OAuth 2.0 access token

Query parameters

org_idinteger
Preferred company id; used as active company only if the person belongs to it.

Example: 7

Responses

200Context.application/json
- userobject
  Child attributes
  idinteger
  namestring
  emailstring (email)
  languagestring
  One ofenit
  is_internalboolean
- companiesarray of object
  Attributes of each item
  idinteger
  slugstring
  namestring
  is_internalboolean
  is_demoboolean
  disabled_sectionsarray of string
  modulesarray of object
  Attributes of each item
  slugstring
  One ofbraincatalogcommerceintelligence
  namestring
  rolestring
  api_base_urlstring (uri) | null
  connector_enabledboolean
- active_company_idinteger | null
- active_company_sourcestring | null
  One ofclaimonlypreferencedefaultnull
401Missing, expired or revoked token — or a token that is not from a self-registered client. Body: {"message":"Unauthenticated."}; Intelligence answers with application/problem+json. application/json
- messagestring

Request

curl -X GET 'https://auth.nucleoplatform.com/api/mcp/context?org_id=7' \
  -H "Authorization: Bearer $NUCLEO_ACCESS_TOKEN" \
  -H 'Accept: application/json'

const res = await fetch("https://auth.nucleoplatform.com/api/mcp/context?org_id=7", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.NUCLEO_ACCESS_TOKEN}`,
    Accept: "application/json",
  },
});
const data = await res.json();
console.log(res.status, data);

<?php

require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

$response = $client->request('GET', 'https://auth.nucleoplatform.com/api/mcp/context?org_id=7', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('NUCLEO_ACCESS_TOKEN'),
        'Accept' => 'application/json',
    ],
    'http_errors' => false,
]);

echo $response->getStatusCode(), PHP_EOL;
echo $response->getBody();

Response

{
  "user": {
    "id": 42,
    "name": "Giulia Rossi",
    "email": "giulia.rossi@acme.example",
    "language": "it",
    "is_internal": false
  },
  "companies": [
    {
      "id": 7,
      "slug": "acme",
      "name": "Acme Apparel",
      "is_internal": false,
      "is_demo": false,
      "disabled_sections": [
        "pos"
      ],
      "modules": [
        {
          "slug": "catalog",
          "name": "Catalog",
          "role": "editor",
          "api_base_url": "https://api-catalog.nucleoplatform.com",
          "connector_enabled": true
        },
        {
          "slug": "commerce",
          "name": "Commerce",
          "role": "viewer",
          "api_base_url": "https://api-commerce.nucleoplatform.com",
          "connector_enabled": true
        },
        {
          "slug": "intelligence",
          "name": "Intelligence",
          "role": "viewer",
          "api_base_url": "https://api-intelligence.nucleoplatform.com",
          "connector_enabled": false
        }
      ]
    }
  ],
  "active_company_id": 7,
  "active_company_source": "only"
}

{
  "message": "Unauthenticated."
}

put/api/mcp/company

Set the active company

Requires the nucleo.ai_tools scope.

Saves the active company of the person for AI clients (one value per person, shared by every AI client they connect, including the MCP connector) and returns the updated context.

PUT https://auth.nucleoplatform.com/api/mcp/company

Authentication: OAuth 2.0 access token

Request bodyapplication/json

organization_idintegerrequired
Company id from companies[].id.

Responses

200Updated context (same shape as GET /api/mcp/context).application/json
- userobject
  Child attributes
  idinteger
  namestring
  emailstring (email)
  languagestring
  One ofenit
  is_internalboolean
- companiesarray of object
  Attributes of each item
  idinteger
  slugstring
  namestring
  is_internalboolean
  is_demoboolean
  disabled_sectionsarray of string
  modulesarray of object
  Attributes of each item
  slugstring
  One ofbraincatalogcommerceintelligence
  namestring
  rolestring
  api_base_urlstring (uri) | null
  connector_enabledboolean
- active_company_idinteger | null
- active_company_sourcestring | null
  One ofclaimonlypreferencedefaultnull
401Missing, expired or revoked token — or a token that is not from a self-registered client. Body: {"message":"Unauthenticated."}; Intelligence answers with application/problem+json. application/json
- messagestring
403The person has no access to that company.application/json
- errorstring
  One ofcompany_requiredcompany_forbiddencompany_not_readyai_connector_disabledunsupported_versionunknown_toolpermission_deniedinvalid_arguments
- messagestringrequired
  In the language of X-Nucleo-Language where translated.
- permissionstring
  permission_denied only.
- supportedarray of integer
  unsupported_version only.
- errorsobject
  invalid_arguments on Commerce and Intelligence (standard validation shape).
- detailsarray of object
  invalid_arguments on Brain and Catalog.
  Attributes of each item
  fieldstring
  errorstring
422Validation failed.application/json
- messagestring
- errorsobject

Request

curl -X PUT https://auth.nucleoplatform.com/api/mcp/company \
  -H "Authorization: Bearer $NUCLEO_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "organization_id": 7
}'

const res = await fetch("https://auth.nucleoplatform.com/api/mcp/company", {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${process.env.NUCLEO_ACCESS_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "organization_id": 7
  }),
});
const data = await res.json();
console.log(res.status, data);

<?php

require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

$response = $client->request('PUT', 'https://auth.nucleoplatform.com/api/mcp/company', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('NUCLEO_ACCESS_TOKEN'),
    ],
    'json' => [
        'organization_id' => 7,
    ],
    'http_errors' => false,
]);

echo $response->getStatusCode(), PHP_EOL;
echo $response->getBody();

Response

{
  "user": {
    "id": 1,
    "name": "string",
    "email": "jane@example.com",
    "language": "en",
    "is_internal": true
  },
  "companies": [
    {
      "id": 1,
      "slug": "string",
      "name": "string",
      "is_internal": true,
      "is_demo": true,
      "disabled_sections": [
        "string"
      ],
      "modules": [
        {
          "slug": "brain",
          "name": "string",
          "role": "string",
          "api_base_url": "https://shop.acme.example",
          "connector_enabled": true
        }
      ]
    }
  ],
  "active_company_id": 1,
  "active_company_source": "claim"
}

{
  "message": "Unauthenticated."
}

{
  "error": "company_forbidden",
  "message": "You have no access to this company."
}

{
  "message": "The organization id field is required.",
  "errors": {
    "organization_id": [
      "The organization id field is required."
    ]
  }
}

Was this page helpful?