Core · Service · Active

platform-mcp-service

Core MCP boundary that exposes controlled platform tools for status, auth, AI, datasource diagnostics and scraper operations without moving product business logic into the MCP service.

• TypeScript
• NestJS 11
• @modelcontextprotocol/sdk
• zod
• @platform/contracts-ai
• @codestormlab/cs-contracts-connectors
• @platform/contracts-scraper
• @platform/observability

Spec sheet

Boundary

Core / MCP

Runtime

NestJS 11 HTTP service with Model Context Protocol SDK

Default port

3500

Proxy host

http://mcp.cs.lvh.me:8080/mcp

Security

Host/Origin policy plus x-platform-internal-token or bearer session token

Responsibilities

• Expose read-only and diagnostic MCP tools over a single /mcp endpoint.
• Propagate user bearer context to downstream Core services when present.
• Keep AI generation, auth configuration, connectors and status logic in their owning services.
• Redact sensitive provider details when exposing admin diagnostics to MCP clients.

Interfaces and contract surface

• GET /health
• GET /internal/mcp/tools/catalog
• POST /mcp
• MCP tool platform_status_overview
• MCP tool platform_core_services_health
• MCP tool platform_service_health
• MCP tool platform_auth_providers
• MCP tool platform_auth_provider_detail
• MCP tool platform_ai_providers
• MCP tool platform_ai_provider_detail
• MCP tool platform_ai_generate_text
• MCP tool platform_connectors_sources
• MCP tool platform_connectors_source_status
• MCP tool platform_connectors_source_capabilities
• MCP tool platform_connectors_test_source
• MCP tool platform_connectors_describe_objects
• MCP tool platform_connectors_describe_fields
• MCP tool platform_connectors_query_page
• MCP tool platform_connectors_query_more
• MCP tool platform_connectors_raw_query
• MCP tool platform_connectors_raw_query_page
• MCP tool platform_connectors_raw_query_more
• MCP tool platform_connectors_sosl_search
• MCP tool platform_scraper_health
• MCP tool platform_scraper_create_crawl
• MCP tool platform_scraper_crawl_detail

Consumers

• MCP clients
• platform-agent-service AI execution path
• cs-chat api

Dependencies and external touchpoints

• platform-auth-service
• platform-ai-service
• platform-connectors-service
• platform-scraper-service
• platform-status-service
• @platform/observability

Notes

• Tools are read-only or diagnostic except platform_ai_generate_text, which delegates generation to platform-ai-service.
• Scraper crawl creation is an internal queueing operation and requires both MCP_ENABLE_SCRAPER_CRAWL_CREATION=true and a caller-owned callback URL.
• Mutating tools require an explicit policy decision before they are added.

Source references

• platform-mcp-service/README.md
• platform-mcp-service/src/tools
• platform-mcp-service/package.json

Autenticazione, relay e catalogo

POST /mcp usa Streamable HTTP e supporta chiamanti CORE fidati con x-platform-internal-token e client OAuth con bearer destinato all'audience platform-mcp-service. Il challenge rimanda al Protected Resource Metadata path-aware /.well-known/oauth-protected-resource/mcp; Auth pubblica il metadata server su /.well-known/oauth-authorization-server e implementa Authorization Code con PKCE S256 e Dynamic Client Registration configurabile.

I client OAuth esterni ricevono soltanto le capability provider configurate e coperte dagli scope del token. I tool, resource e prompt statici CORE restano riservati ai chiamanti interni. I cataloghi provider sono risolti tramite il contratto generico @platform/contracts-mcp; MPS non contiene logica di prodotto. Prima di invocare un provider, MPS scambia il token MCP tramite Auth con un token delegato avente l'audience del provider. Il bearer MCP non viene inoltrato.

GET /internal/mcp/tools/catalog espone ai BFF il catalogo combinato, con name, title, description, context, riskLevel, enabled, capabilityCode e, per provider dinamici, operation. I tool statici usano la capability platform:mcp:tool:<toolName>:call; il BFF decide la disponibilità per utente. Gli scope OAuth dei provider sono invece registrati in Auth con kind: mcp_scope e concessi con grant prodotto distinti.

Il provider Task Board cs-portal.task-board espone 4 letture e 12 mutazioni. Le capability OAuth sono cs-portal.task-board.read e cs-portal.task-board.write; Portal applica nuovamente membership e ruolo board. MPS espone i tool solo se lo scope è nel token. Le scritture usano chiave di idempotenza di 24 ore e il token Portal separato. L'operatività e la matrice dei ruoli sono documentate in cs-portal/docs/task-tracking-operations.md.

platform-status-service è stato valutato: il relay non aggiunge un servizio, una health route o uno smoke status distinto, quindi il catalogo e le operazioni Task Board non introducono un target status autonomo.

Smoke test MCP

export MCP_BASE_URL=http://127.0.0.1:3500
export MCP_URL=http://127.0.0.1:3500/mcp
export INTERNAL_TOKEN=platform-local-stack-internal-token

curl -sS "$MCP_URL" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "x-platform-internal-token: $INTERNAL_TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Endpoint reference

Header comuni:

• x-platform-internal-token: $INTERNAL_TOKEN per accesso service-to-service
• Authorization: Bearer <MCP_ACCESS_TOKEN> per client OAuth MCP; i chiamanti interni possono aggiungere un contesto sessione separato
• Accept: application/json, text/event-stream per richieste JSON-RPC MCP

Endpoint	Scopo	Request	Esempio	Risposta rappresentativa	Errori e consumer
GET /health	Verifica liveness MCP e configurazione minima.	Nessun body.	curl -sS "$MCP_BASE_URL/health"	{"status":"ok","service":"platform-mcp-service","mcpPath":"/mcp"}	5xx se policy/config non valida. Consumer: status dashboard.
GET /.well-known/oauth-protected-resource/mcp	Metadata della risorsa protetta MCP e scope provider configurati.	Nessun body.	curl -sS "$MCP_BASE_URL/.well-known/oauth-protected-resource/mcp"	{"resource":"https://mcp.example.com/mcp","authorization_servers":["https://auth.example.com"],"scopes_supported":["cs-portal.task-board.read"]}	503 se un provider configurato non risponde. Consumer: client OAuth MCP.
GET /internal/mcp/tools/catalog	Espone catalogo tool, context, risk level, enablement e capability code.	Header interno.	curl -sS "$MCP_BASE_URL/internal/mcp/tools/catalog" -H "x-platform-internal-token: $INTERNAL_TOKEN"	{"items":[{"name":"platform_status_overview","title":"Platform status overview","context":{"key":"status","label":"Platform status"},"riskLevel":"low","enabled":true,"capabilityCode":"platform:mcp:tool:platform_status_overview:call"}]}	401/403 token. Consumer: BFF/admin UI che devono risolvere capability via auth service.
POST /mcp con initialize	Avvia handshake MCP HTTP.	JSON-RPC MCP.	curl -sS "$MCP_URL" -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" -H "x-platform-internal-token: $INTERNAL_TOKEN" -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"manual","version":"1.0.0"}}}'	{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2024-11-05","serverInfo":{"name":"platform-mcp-service"}}}	400 JSON-RPC non valido, 403 host/origin non ammesso. Consumer: MCP clients.
POST /mcp con tools/list	Elenca tool registrati nello standard MCP.	JSON-RPC MCP.	curl -sS "$MCP_URL" -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" -H "x-platform-internal-token: $INTERNAL_TOKEN" -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'	{"jsonrpc":"2.0","id":2,"result":{"tools":[{"name":"platform_ai_generate_text","description":"Create a text generation using the shared platform AI service.","inputSchema":{"type":"object"}}]}}	Errori JSON-RPC standard. Consumer: agent service e client MCP.
POST /mcp con tools/call	Esegue un tool abilitato.	params.name e params.arguments.	curl -sS "$MCP_URL" -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" -H "x-platform-internal-token: $INTERNAL_TOKEN" -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"platform_status_overview","arguments":{}}}'	{"jsonrpc":"2.0","id":3,"result":{"content":[{"type":"text","text":"{\"status\":\"ok\"}"}]}}	403 policy host/origin/token, errori tool normalizzati nel result MCP. Consumer: agent service, cs-chat API, client MCP.

Per operazioni remote, esporre MCP e Auth su HTTPS e mantenere coerenti resource, issuer e domini ammessi. Codex e Claude Code usano il trasporto HTTP remoto e autenticazione OAuth secondo i rispettivi client. Per i comandi di collegamento e i parametri di stack vedere platform-mcp-service/README.md.

Catalogo tool

Ogni tool espone una capability platform:mcp:tool:<toolName>:call.

Tool	Risk	Scopo	Downstream
platform_status_overview	low	Overview aggregata piattaforma.	platform-status-service
platform_core_services_health	low	Health dei servizi Core.	platform-status-service
platform_service_health	low	Health di un target status specifico.	platform-status-service
platform_auth_providers	medium	Lista provider auth con secret redatti.	platform-auth-service
platform_auth_provider_detail	medium	Dettaglio provider auth redatto.	platform-auth-service
platform_ai_providers	medium	Provider AI disponibili e configurati.	platform-ai-service
platform_ai_provider_detail	medium	Dettaglio provider AI redatto.	platform-ai-service
platform_ai_generate_text	high	Generazione testo via boundary AI, con outputSchema opzionale.	platform-ai-service
platform_connectors_sources	low	Lista sorgenti datasource.	platform-connectors-service
platform_connectors_source_status	low	Stato configurazione sorgente.	platform-connectors-service
platform_connectors_source_capabilities	low	Capability sorgente.	platform-connectors-service
platform_connectors_test_source	medium	Test credenziali sorgente senza persistenza.	platform-connectors-service
platform_connectors_describe_objects	low	Describe oggetti datasource.	platform-connectors-service
platform_connectors_describe_fields	low	Describe campi oggetto.	platform-connectors-service
platform_connectors_query_page	medium	Query strutturata paginata.	platform-connectors-service
platform_connectors_query_more	medium	Pagina successiva query strutturata.	platform-connectors-service
platform_connectors_raw_query	high	Query raw read-only.	platform-connectors-service
platform_connectors_raw_query_page	high	Query raw paginata.	platform-connectors-service
platform_connectors_raw_query_more	high	Pagina successiva query raw.	platform-connectors-service
platform_connectors_sosl_search	high	Ricerca SOSL Salesforce.	platform-connectors-service
platform_scraper_health	low	Health dello scraper.	platform-scraper-service
platform_scraper_create_crawl	high	Accoda crawl interno con callback.	platform-scraper-service
platform_scraper_crawl_detail	medium	Legge dettaglio crawl.	platform-scraper-service

Esempi tool call

Generazione AI via MCP:

curl -sS "$MCP_URL" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "x-platform-internal-token: $INTERNAL_TOKEN" \
  -d '{
    "jsonrpc": "2.0",
    "id": 10,
    "method": "tools/call",
    "params": {
      "name": "platform_ai_generate_text",
      "arguments": {
        "providerKey": "template",
        "input": "Scrivi una risposta breve.",
        "instructions": "Rispondi in italiano.",
        "outputSchema": {
          "type": "object",
          "additionalProperties": false,
          "required": ["message"],
          "properties": {
            "message": { "type": "string" }
          }
        }
      }
    }
  }'

Query datasource read-only via MCP:

curl -sS "$MCP_URL" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "x-platform-internal-token: $INTERNAL_TOKEN" \
  -d '{
    "jsonrpc": "2.0",
    "id": 11,
    "method": "tools/call",
    "params": {
      "name": "platform_connectors_query_page",
      "arguments": {
        "sourceId": "salesforce-default",
        "pageSize": 25,
        "query": {
          "kind": "structured",
          "query": {
            "objectName": "Contact",
            "select": ["Id", "Name", "Email"],
            "limit": 25
          }
        }
      }
    }
  }'