MCP Connector API

curl -X GET https://mcp.nucleoplatform.com/.well-known/oauth-protected-resource \
  -H 'Accept: application/json'

const res = await fetch("https://mcp.nucleoplatform.com/.well-known/oauth-protected-resource", {
  method: "GET",
  headers: {
    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://mcp.nucleoplatform.com/.well-known/oauth-protected-resource', [
    'headers' => [
        'Accept' => 'application/json',
    ],
    'http_errors' => false,
]);

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

{
  "resource": "https://mcp.nucleoplatform.com",
  "authorization_servers": [
    "https://auth.nucleoplatform.com"
  ],
  "bearer_methods_supported": [
    "header"
  ],
  "scopes_supported": [
    "openid",
    "profile",
    "email"
  ],
  "resource_name": "Nucleo"
}

curl -X GET https://mcp.nucleoplatform.com/.well-known/oauth-protected-resource/mcp \
  -H 'Accept: application/json'

const res = await fetch("https://mcp.nucleoplatform.com/.well-known/oauth-protected-resource/mcp", {
  method: "GET",
  headers: {
    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://mcp.nucleoplatform.com/.well-known/oauth-protected-resource/mcp', [
    'headers' => [
        'Accept' => 'application/json',
    ],
    'http_errors' => false,
]);

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

{
  "resource": "https://shop.acme.example",
  "authorization_servers": [
    "https://shop.acme.example"
  ],
  "bearer_methods_supported": [
    "header"
  ],
  "scopes_supported": [
    "string"
  ],
  "resource_name": "string"
}

curl -X GET https://mcp.nucleoplatform.com/

const res = await fetch("https://mcp.nucleoplatform.com/", {
  method: "GET",
});
const data = await res.json();
console.log(res.status, data);

<?php

require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

$response = $client->request('GET', 'https://mcp.nucleoplatform.com/', [
    'http_errors' => false,
]);

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

{
  "error": "method_not_allowed",
  "message": "Use POST with a JSON-RPC 2.0 body."
}

curl -X POST https://mcp.nucleoplatform.com/ \
  -H "Authorization: Bearer $NUCLEO_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-06-18",
    "capabilities": {},
    "clientInfo": {
      "name": "acme-agent",
      "version": "1.4.0"
    }
  }
}'

const res = await fetch("https://mcp.nucleoplatform.com/", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.NUCLEO_ACCESS_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-06-18",
      "capabilities": {},
      "clientInfo": {
        "name": "acme-agent",
        "version": "1.4.0"
      }
    }
  }),
});
const data = await res.json();
console.log(res.status, data);

<?php

require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

$response = $client->request('POST', 'https://mcp.nucleoplatform.com/', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('NUCLEO_ACCESS_TOKEN'),
    ],
    'json' => [
        'jsonrpc' => '2.0',
        'id' => 1,
        'method' => 'initialize',
        'params' => [
            'protocolVersion' => '2025-06-18',
            'capabilities' => (object) [],
            'clientInfo' => [
                'name' => 'acme-agent',
                'version' => '1.4.0',
            ],
        ],
    ],
    'http_errors' => false,
]);

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

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-06-18",
    "capabilities": {
      "tools": {
        "listChanged": false
      }
    },
    "serverInfo": {
      "name": "nucleo",
      "title": "Nucleo",
      "version": "2.0.0"
    },
    "instructions": "ACTIVE COMPANY: \"Acme Apparel\" (the only company of the user). Modules available here: catalog, commerce. Nucleo is the platform of the signed-in person: tools are grouped by module through their prefix (brain_ = CRM, inbox, knowledge, documents, playbooks; catalog_ = products and assets; commerce_ = tickets, stores, orders; intelligence_ = KPIs and reports). Every tool runs inside the active company with the person's own permissions. Before any write tool, summarise what will change and ask for confirmation; tools marked destructive (destructiveHint) cannot be undone, so say so explicitly. Answer in the user's language (English)."
  }
}

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "tools": [
      {
        "name": "nucleo_list_companies",
        "title": "List my companies",
        "description": "List the companies the signed-in person can work in through Nucleo, with the modules available in each and which one is currently active. Call it when the user mentions a company that does not match the active one, or asks what they have access to.",
        "inputSchema": {
          "type": "object",
          "properties": {}
        },
        "annotations": {
          "readOnlyHint": true,
          "destructiveHint": false,
          "idempotentHint": true,
          "openWorldHint": false
        }
      },
      {
        "name": "commerce_get_order",
        "title": "Get order",
        "description": "[Commerce] Orders (Nucleo OMS). One order in full: customer, address, items, ship-from location, holds, shipments with tracking, returns and anomalies.",
        "inputSchema": {
          "type": "object",
          "properties": {
            "order": {
              "type": "string",
              "maxLength": 120,
              "description": "Order number (e.g. #1042) or id."
            }
          },
          "required": [
            "order"
          ]
        },
        "annotations": {
          "readOnlyHint": true,
          "destructiveHint": false,
          "idempotentHint": true,
          "openWorldHint": false
        }
      },
      {
        "name": "brain_merge_contacts",
        "title": "Merge contacts",
        "description": "[Brain] Unisce due contatti doppi: primary_contact_id resta, secondary_contact_id confluisce nel principale e finisce nel cestino. … Chiedi conferma; poi chiama con confirmed_by_user=true. …",
        "inputSchema": {
          "type": "object",
          "properties": {
            "primary_contact_id": {
              "type": "integer",
              "description": "Contatto che resta."
            },
            "secondary_contact_id": {
              "type": "integer",
              "description": "Contatto doppione da unire nel principale."
            },
            "confirmed_by_user": {
              "type": "boolean",
              "description": "true solo dopo il si' esplicito della persona."
            }
          },
          "required": [
            "primary_contact_id",
            "secondary_contact_id",
            "confirmed_by_user"
          ]
        },
        "annotations": {
          "readOnlyHint": false,
          "destructiveHint": true,
          "idempotentHint": false,
          "openWorldHint": false
        }
      }
    ]
  }
}

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Companies (● = active):\n● Acme Apparel (id 7) — modules: catalog, commerce\n○ Acme Outlet (id 9) — modules: catalog"
      }
    ],
    "structuredContent": {
      "companies": [
        {
          "id": 7,
          "slug": "acme",
          "name": "Acme Apparel",
          "modules": [
            "catalog",
            "commerce"
          ],
          "active": true
        },
        {
          "id": 9,
          "slug": "acme-outlet",
          "name": "Acme Outlet",
          "modules": [
            "catalog"
          ],
          "active": false
        }
      ],
      "active_company_id": 7
    },
    "isError": false
  }
}

{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Active company is now \"Acme Outlet\" (id 9). Module tools now work inside it."
      }
    ],
    "structuredContent": {
      "active_company_id": 9
    },
    "isError": false
  }
}

{
  "jsonrpc": "2.0",
  "id": 5,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "You do not have permission `oms.read` for this action."
      }
    ],
    "isError": true
  }
}

{
  "jsonrpc": "2.0",
  "id": 5,
  "error": {
    "code": -32602,
    "message": "Unknown tool: commerce_search_invoices"
  }
}

{
  "jsonrpc": "2.0",
  "id": 8,
  "error": {
    "code": -32601,
    "message": "Method not found: resources/list"
  }
}

{
  "jsonrpc": "2.0",
  "id": 5,
  "error": {
    "code": -32000,
    "message": "Nucleo Commerce is busy, retry in 30 seconds."
  }
}

HTTP 202 — Notification accepted (no body).

{
  "jsonrpc": "2.0",
  "id": null,
  "error": {
    "code": -32700,
    "message": "Parse error: expected a JSON-RPC 2.0 request."
  }
}

{
  "error": "unauthorized",
  "message": "Sign in with Nucleo to use this connector."
}

curl -X GET https://mcp.nucleoplatform.com/mcp

const res = await fetch("https://mcp.nucleoplatform.com/mcp", {
  method: "GET",
});
const data = await res.json();
console.log(res.status, data);

<?php

require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

$response = $client->request('GET', 'https://mcp.nucleoplatform.com/mcp', [
    'http_errors' => false,
]);

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

{
  "error": "method_not_allowed",
  "message": "Use POST with a JSON-RPC 2.0 body."
}

curl -X POST https://mcp.nucleoplatform.com/mcp \
  -H "Authorization: Bearer $NUCLEO_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "jsonrpc": "2.0",
  "id": "string",
  "method": "initialize",
  "params": {}
}'

const res = await fetch("https://mcp.nucleoplatform.com/mcp", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.NUCLEO_ACCESS_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "jsonrpc": "2.0",
    "id": "string",
    "method": "initialize",
    "params": {}
  }),
});
const data = await res.json();
console.log(res.status, data);

<?php

require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

$response = $client->request('POST', 'https://mcp.nucleoplatform.com/mcp', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('NUCLEO_ACCESS_TOKEN'),
    ],
    'json' => [
        'jsonrpc' => '2.0',
        'id' => 'string',
        'method' => 'initialize',
        'params' => (object) [],
    ],
    'http_errors' => false,
]);

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

{
  "jsonrpc": "2.0",
  "id": "string",
  "result": {},
  "error": {
    "code": -32700,
    "message": "string"
  }
}

HTTP 202 — Notification accepted.

{
  "error": "unauthorized",
  "message": "Sign in with Nucleo to use this connector."
}