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
• @platform/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

Catalogo tool e capability

platform-mcp-service pubblica il catalogo interno dei tool su /internal/mcp/tools/catalog. Ogni record espone name, title, description, context, riskLevel, enabled e capabilityCode. context contiene key e label per raggruppare i tool nei BFF e nelle UI operative.

La capability canonica per chiamare un tool e:

platform:mcp:tool:<toolName>:call

Il servizio MCP non decide gli ACL utente per singolo tool: valida host, origin e token interno, poi esegue i tool registrati. La disponibilita per utente viene risolta da platform-auth-service e applicata dai BFF o dagli orchestratori che consumano MCP.

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 <ACCESS_TOKEN> quando un orchestratore propaga sessione utente
• 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 /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.

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.	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."
      }
    }
  }'

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
          }
        }
      }
    }
  }'