Sentia MCP

This package is Sentia's MCP server. It uses the official @modelcontextprotocol/sdk for both stdio and Streamable HTTP transports. Sentia business logic stays behind the command-layer REST API; MCP tools are thin, typed adapters over those commands.

The previous legacy design tools and setup docs were intentionally removed. Keep transport, OAuth, audit, and dispatch primitives aligned with the public command-layer contracts in @sentia-labs/contracts.

Tool input schemas are generated at runtime from the same Zod contracts used for validation through @asteasolutions/zod-to-openapi; do not hand-write parallel JSON schemas for agent-native tools.

Transports:

• sentia-mcp --mode=stdio: local coding-agent install for Claude Code, Cursor, Codex-style terminals, and other MCP-aware clients.
• sentia-mcp --mode=http: hosted Streamable HTTP MCP endpoint at /mcp. This is the enterprise remote transport; the previous bespoke /mcp/v1/tools/list and /mcp/v1/tools/call protocol has been removed.

Current command-layer tools (kept in sync with src/tools/index.ts's TOOL_INDEX — the dispatcher's scopes_supported metadata is derived from this same registry, so this table and the server's advertised OAuth scopes can never drift):

• sentia_source_connect
• sentia_source_status
• sentia_research_artifact_status
• sentia_population_create
• sentia_population_status
• sentia_population_list
• sentia_research_run
• sentia_run_status
• sentia_research_run_list
• sentia_evidence_query
• sentia_world_model_coverage
• sentia_world_model_edges
• sentia_world_model_segments
• sentia_world_model_model_card
• sentia_world_model_graph
• sentia_agent_decision_create
• sentia_agent_decision_get
• sentia_agent_decision_list
• sentia_agent_decision_bind
• sentia_simulation_create
• sentia_simulation_status
• sentia_simulation_watch
• sentia_simulation_results
• sentia_simulation_list
• sentia_browser_auth_list
• sentia_browser_auth_get

Authenticated browser walks pass browserAuthArtifactId from sentia_browser_auth_list (approved capture flow). Raw cookies / storageState are rejected. Interactive login capture remains CLI sentia auth capture — MCP lists/binds artifacts only. Website / browser walkthrough agent counts default to 8 and hard-max at 10 (BROWSER_AGENT_CAP); browser credit multiplier is 4× vs text. Prefer sentia_simulation_watch (MCP notifications/progress when the client sends progressToken); otherwise poll sentia_simulation_status every 2-5s (same SimulationDto as CLI), then open resultsUrl for live/replay.

The public MCP surface must stay spec-compliant, typed, permission-scoped, observable, and aligned with docs/strategy/ai-native-platform-plan.md.

Customer-facing install and API reference:

• docs/agent-native-mcp-api.md

Scope map:

• sentia_source_connect: sources:write
• sentia_source_status: sources:read
• sentia_research_artifact_status: populations:read
• sentia_population_create: populations:write
• sentia_population_status: populations:read
• sentia_population_list: populations:read
• sentia_research_run: research:write
• sentia_run_status: research:read
• sentia_research_run_list: research:read
• sentia_evidence_query: evidence:read
• sentia_world_model_*: evidence:read (read tools)
• sentia_agent_decision_create: agent_decisions:write
• sentia_agent_decision_get: agent_decisions:read
• sentia_agent_decision_list: agent_decisions:read
• sentia_agent_decision_bind: agent_decisions:write
• sentia_simulation_create: simulations:write
• sentia_simulation_status / _watch / _results / _list: simulations:read
• sentia_browser_auth_list / _get: browser_auth:read