@nsp-labs/agnostic-mcp

Official stdio MCP server for local agent development with Agnostic.

The server gives any MCP-compatible coding agent the same role- and environment-filtered project context and confirmation-gated action surface. It never confirms an action, accepts credentials, talks directly to a provider, or creates a second Agnostic token store.

Install

npm install -g @nsp-labs/agnostic-cli @nsp-labs/agnostic-mcp
cd <agnostic-workspace>
agnostic agent setup codex --environment <environment-id>

Use claude or cursor instead of codex for another supported client. Setup performs Local Agent browser authorization, the first context sync, and user-level MCP registration. To inspect without changing anything:

agnostic agent setup codex --environment <environment-id> --dry-run
agnostic agent doctor codex

The process uses stdin/stdout only for MCP JSON-RPC. Diagnostics go to stderr.

Tools

Data reads require a separate grant via agnostic data login --access schema (or records). Introduced in CLI 0.6.0 / MCP 0.2.0, agnostic_data_schema, agnostic_data_records and agnostic_data_aggregate according to that grant. Schema reads return a summary and fingerprint-bound resource link; full resource reads reauthorize and reject stale snapshots. MCP reuses the CLI-owned private Data credential file. These package versions require a separate release.

• agnostic_project_context
• agnostic_available_actions
• agnostic_action_prepare
• agnostic_action_status
• agnostic_action_wait
• agnostic_context_sync
• agnostic_workspace_status
• agnostic_workspace_push
• agnostic_build_status
• agnostic_data_plan
• agnostic_data_plan_status
• agnostic_data_plan_prepare
• agnostic_data_job_status
• agnostic_data_job_wait
• agnostic_data_job_logs
• agnostic_data_job_report
• agnostic_data_import_plan
• agnostic_data_import_plan_status
• agnostic_data_import_plan_prepare
• agnostic_data_import_plan_links
• agnostic_data_import_job_links

agnostic_action_prepare receives its exact input alternatives from the current capability manifest. agnostic_workspace_push reuses the filtered workspace boundary and requires the MCP host to obtain user approval before the write. Its optional build is pinned to the returned commit; agnostic_build_status returns only sanitized status/log data. Deploy is never implicit: the agent prepares app.deploy separately and the user confirms it in Agnostic. The server exposes no confirm, secret, credential, provider, or direct publish tool. After a confirmed action succeeds, agnostic_action_status and agnostic_action_wait refresh .agnostic/agent-context.json together with the Markdown cards in .agnostic/context/**.

CLI 0.7.0 / MCP 0.3.0 add the complete managed schema/import surface. The Data management tools are discovered only for a Local Agent admin/developer capability advertised as managed_workflow. They create an immutable plan, verify its exact hash during prepare, and return the browser confirmation URL. MCP exposes no Data confirmation or cancellation tool. Job status/log pages are cursor-bound and bounded; wait timeout/cancellation detaches the observer without cancelling the durable server job.

Import file bytes never pass through MCP. The CLI first creates and validates a private JSONL.gz artifact; MCP receives only its scoped ID, then can plan, inspect safe link diagnostics and prepare browser confirmation. Record values, source IDs and signed upload URLs are excluded from MCP output.

Prepare also sends the context generation time for payload-free freshness metrics. MCP failures are reported best-effort as an allowlisted mcp_error or redaction_violation code. Telemetry contains no input, output, error message, stack, or matched credential value and never replaces the original MCP result.

The cached project context is also available as the read-only agnostic://project/context resource.

Selection and authentication

Selection follows the existing CLI precedence:

1. MCP call arguments;
2. AGNOSTIC_PROJECT_ID and AGNOSTIC_ENVIRONMENT_ID;
3. the nearest .agnostic/agent-context.json;
4. project id from the nearest .agnostic/workspace.json.

Authentication and API URL reuse @nsp-labs/agnostic-cli configuration, AGNOSTIC_API_TOKEN/AGNOSTIC_TOKEN, and AGNOSTIC_API_BASE_URL. The saved Local Agent credential has priority over the workspace login. The MCP package does not create a token store, and setup never copies a token into Codex, Claude Code, or Cursor configuration.

Safety and compatibility

• action input and reason are rejected when they contain credential-like keys or raw token-shaped values;
• action input is validated against the current server manifest before prepare;
• all success and error payloads are sanitized and versioned;
• non-wait calls have a 30-second server timeout;
• client cancellation aborts the corresponding Agnostic API request;
• capability manifest major version 1 is required;
• the user confirms every prepared mutation in the Agnostic browser UI;
• workspace push requires host-side user approval; build is opt-in, and deploy remains a separate browser-confirmed action for an exact artifact/commit.

Node.js 18.18 or newer is required.