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
• 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, riskLevel, enabled e capabilityCode.

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_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":{}}'