deep-agentic-core-mcp

deep-agentic-core-mcp is the shared MCP server layer for the DeepAgentLabs ecosystem. It is designed to expose a single MCP interface that combines:

• agenticlens style workflow inspection, profiling, and analysis
• agentic-chaos style resilience testing and fault-injection workflows
• agentic-sidecar style supervision-readiness and module-surface discovery
• future agenticops-control-tower style operator-facing control-plane access

It sits above the AI Operations Workflow Specification, exposing a unified MCP-native control surface over the shared operational model used by the reference implementations.

The goal is one MCP server, one package, and one registry identity rather than separate MCP servers for each product surface.

Connect and use

Start with the user and developer guide for hosted signup, MCP client connection, workflow analysis, evaluation reports, and local chaos/ Sidecar capabilities. Run the Python workflow example to send an exported workflow to the hosted service. The guide documents current integration availability and distinguishes implemented tools from future runtime work.

Idea

This project is the control plane between LLM hosts and the existing Python libraries:

• agenticlens remains the core profiling and analysis engine
• agentic-chaos remains the core chaos and resilience engine
• agentic-sidecar remains the core decision-supervision and governance engine
• agenticops-control-tower remains the future operator-facing control plane
• the AI Operations Workflow Specification remains the shared data contract
• deep-agentic-core-mcp becomes the MCP-native interface that hosts can call

That means MCP clients can connect once and access observability, chaos, sidecar discovery, and later Control Tower-aligned operations surfaces through one server.

What This Server Should Eventually Do

Planned capability areas:

• profile an agentic workflow and return structured telemetry summaries
• analyze workflow artifacts and surface optimization recommendations
• run controlled chaos experiments against target workflows
• expose installed Sidecar decision/runtime capabilities and module inventory; package readiness is distinct from a live task connection
• eventually expose Control Tower inventory and operator-facing control surfaces once that sibling package ships them
• compare normal versus chaos runs
• expose shared resources such as workflow schemas, run metadata, and saved reports

Design Principles

• One MCP identity: publish a single server to the MCP Registry
• Python-first: package and publish through PyPI
• Thin orchestration layer: reuse agenticlens, agentic-chaos, and agentic-sidecar instead of re-implementing their logic
• Local-first: work well as a stdio MCP server for developer workflows — this matters because chaos.run_experiment executes real code (see SECURITY.md), so this server is meant for trusted, local/stdio use; authenticated HTTP deployments disable code execution
• Dual transport, one tool surface: the optional Streamable HTTP transport (below) reuses stdio tools/resources/prompts, with remote script execution excluded

Agentic Chaos v0.5 compatibility (MCP 0.3.2)

Install agentic-chaos>=0.5.0 alongside the server to discover streaming, authentication, and context-length faults through chaos.list_faults. The existing local stdio chaos.run_experiment tool runs examples/chaos_stream_target.py with faults=["stream_cut"] and returns the native degraded event. Real sibling integration tests cover the catalog and experiment path. Chaos remains optional; no hard sibling dependency is introduced. Hosted HTTP rejects chaos execution.

The example is a repository file, not a wheel-installed asset. Clone the v0.3.2 source into a mcp-server directory and set DEEP_AGENTIC_CORE_MCP_WORKSPACE_ROOT to its parent directory before starting the server. The user guide provides exact setup commands. CI checks both the pinned Chaos v0.5.0 tag and the latest sibling checkout.

See the user guide and the Chaos v0.5 API guide.

Phase 3 completion (MCP 0.3.3)

• Finding provenance (3a): every lens.analyze_workflow recommendation has a provenance block. It names the artifact (workflow_id, canonical sha256 digest), the workflow step (id, name, type, index), the evidence span IDs and the producer. resolved is true only when all of these exist in the artifact you sent, and provenance_summary counts how many do. Needs agenticlens>=0.6.1 for model-swap and chaos-impact findings.
• Chaos results as AIOS runs (3b): chaos.run_experiment attaches aios_run, an AI Operations v0.4-draft Run built by agentic-chaos>=0.5.1's own exporter and checked by the spec adapter (aios_export.aligned). chaos.export_aios_run converts a saved or session report without running any code.
• Script policy (3b): DEEP_AGENTIC_CORE_MCP_ALLOWED_SCRIPT_GLOBS and DEEP_AGENTIC_CORE_MCP_DENIED_SCRIPT_GLOBS narrow which workspace scripts chaos.run_experiment may run. Deny wins, and .venv, site-packages and .git are always denied.
• Version routing and conformance (3c): spec.validate_artifact validates against the schema set the artifact's spec_version names and rejects markers it has no schema for, citing the applicable v0.5 rule (AIOS-0.5-V01…V06). Its conformance section lists every AIOS-0.4-* rule with a status, separate from server presentation. Needs ai-operations-spec>=0.5.1 for the rule and compatibility catalogs.

Run examples/phase3_walkthrough.py from a workspace checkout to see all four end to end.

Since 0.3.4 the hosted service at https://mcp.deepagentlabs.io/mcp ships the same sibling versions and spec catalogs, so provenance, conformance reports and chaos.export_aios_run behave the same hosted as locally. Only chaos.run_experiment stays local-only.

AgenticLens 0.7.0 diagnosis tools (MCP 0.3.5)

• lens.diagnose_run — send a trace Run (and optional baseline runs) and get AgenticLens's diagnosis report: failure-taxonomy diagnoses with confidence and supporting spans, the faulty step and agent with ranked candidates, the incident timeline, robust anomalies against the baseline, guardrail status (budget caps spans, depth, and time), and an investigation narrative in Markdown (include_narrative, default true).
• lens.score_analysis — send an evaluation report and get deterministic and model-based scores reported separately, judge cost kept apart from agent cost, and the cases where evaluators disagree.

Both need agenticlens>=0.7.0; with an older install they return a clear "unavailable" error and every other Lens tool keeps working. The hosted images pin agenticlens==0.7.0 and agentic-chaos==0.5.3.

MCP Surface (current, 0.3.5)

• core.health — rich diagnostics: adapter availability/version, loaded tool/resource/prompt counts, workspace root, recent successful calls
• core.version — server package version
• core.verify — checks agenticlens/agentic-chaos/agentic-sidecar/ai-operations-spec connectivity and reports readiness
• core.session_state — inspect what the active session has accumulated
• lens.analyze_workflow — run AgenticLens recommendations against a workflow artifact
• lens.report_summary — render a Markdown workflow report
• lens.compare_runs — compare baseline/candidate trace runs for regressions
• lens.slo_summary — apply release-gate style SLO thresholds to an evaluation report
• lens.audit_report — case-by-case evaluation detail, optionally with HTML
• lens.diagnose_run — diagnose a trace run: faulty step and agent, timeline, anomalies, investigation narrative (agenticlens>=0.7.0)
• lens.score_analysis — deterministic vs model-based scores, judge cost, and evaluator disagreement for an evaluation report (agenticlens>=0.7.0)
• chaos.list_faults — list the supported fault types
• chaos.run_experiment — run a workspace-sandboxed, policy-checked target script under selected faults and attach an AIOS run export (executes real code — see SECURITY.md)
• chaos.export_aios_run — convert a chaos report into a validated AI Operations v0.4-draft run artifact (added in 0.3.3; no code execution)
• sidecar.status — report installed Sidecar runtime APIs separately from live task connectivity (added in 0.3.0)
• sidecar.module_inventory — inspect the installed sidecar modules, framework adapters, and integration placeholders (added in 0.3.0)
• spec.validate_artifact — validate a workflow/run artifact against the schema set its spec_version names, with a rule-cited conformance report

Sequential tool calls can share context via an optional session_id argument, backed by an in-memory session store — see ROADMAP.md Phase 2.

See ROADMAP.md for what's shipped per phase and what's still open, and docs/tools.md for full input schemas and per-tool metadata (generated from tools/registry.py, run make docs to refresh it after changing that file).

Local vs. remote install modes

Container definitions are grouped under deploy/docker.

• Local: pip install deep-agentic-core-mcp, then run deep-agentic-core-mcp over stdio. Local session behavior is unchanged.
• Self-hosted multi-user HTTP (0.3.0+): install with pip install 'deep-agentic-core-mcp[http]', then run deep-agentic-core-mcp-http. Provision a unique bearer key per user and a Redis URL before startup. Missing configuration prevents startup.
• Hosted AWS signup: open mcp.deepagentlabs.io to generate a user identity and MCP key; connect your MCP client to https://mcp.deepagentlabs.io/mcp with its bearer key. DynamoDB stores user records and key hashes; keys work immediately and can be replaced or revoked through the page. No password or email verification is used. Save the key: it cannot be recovered. See the AWS guide.

The HTTP service uses stateless MCP transport at /mcp and Redis-backed workflow sessions scoped to the authenticated user. Users can reuse the same session_id without accessing each other's artifacts. HTTP calls cannot run chaos.run_experiment, even if the local remote-chaos override is set.

See the remote hosting guide and render.yaml for Render deployment, configuration, container builds, AWS deployment requirements, client headers, limits, and credential rotation. create_app() also accepts explicit credentials, a session backend, and allowed hosts/origins for integrations and tests. MemorySessionStore is an explicit development option; the CLI requires Redis.

Repository Layout

mcp-server/
├── README.md
├── ROADMAP.md
├── pyproject.toml
├── server.json
├── .gitignore
├── docs/
│   ├── architecture.md
│   └── tools.md          # generated - see scripts/generate_tools_doc.py
├── examples/
│   ├── sample_workflow.json
│   ├── provenance_workflow.json
│   ├── phase3_walkthrough.py
│   └── chaos_target.py
├── scripts/
│   └── generate_tools_doc.py
├── src/
│   └── deep_agentic_core_mcp/
│       ├── __init__.py
│       ├── server.py
│       ├── transport_http.py
│       ├── config.py
│       ├── prompts/
│       │   ├── __init__.py
│       │   └── registry.py
│       ├── resources/
│       │   ├── __init__.py
│       │   └── catalog.py
│       ├── schemas/
│       │   ├── __init__.py
│       │   └── tooling.py
│       ├── services/
│       │   ├── __init__.py
│       │   ├── registry.py
│       │   └── session.py
│       ├── adapters/
│       │   ├── __init__.py
│       │   ├── agentic_chaos.py
│       │   ├── agenticlens.py
│       │   ├── agentic_sidecar.py
│       │   └── ai_operations_spec.py
│       └── tools/
│           ├── __init__.py
│           ├── registry.py
│           ├── chaos.py
│           ├── core.py
│           ├── lens.py
│           ├── sidecar.py
│           └── spec.py
└── tests/
    ├── test_chaos_aios_export.py
    ├── test_chaos_script_policy.py
    ├── test_degraded_boot.py
    ├── test_imports.py
    ├── test_lens_provenance.py
    ├── test_spec_conformance.py
    ├── test_registry.py
    ├── test_server.py
    └── test_session.py

MCP-Oriented Structure

This repository should have all of the standard layers we expect for a useful MCP server:

• tools/ for callable MCP tools and their registration metadata
• resources/ for readable assets such as fault catalogs, templates, and workflow examples
• prompts/ for reusable prompt templates exposed through the server
• schemas/ for typed request and response contracts
• services/ for shared orchestration logic that keeps tool modules thin, including the in-memory session store (services/session.py)
• adapters/ for integration boundaries to agenticlens, agentic-chaos, agentic-sidecar, and ai-operations-spec — each degrades to "available": false rather than crashing server boot if its sibling repo is missing

Packaging and Publishing Model

One repository supports both the local Python package and the hosted HTTP service. The stdio entry point remains available without the optional HTTP dependencies. HTTP transport and signup support are included from 0.3.0; the earlier PyPI 0.2.0 release provides local stdio.

A push to main does not publish to PyPI or deploy AWS. A version-tag release deploys the same tagged source to AWS only after PyPI publication succeeds. Package releases use PyPI Trusted Publishing; AWS deployment uses the dedicated IAM user's GitHub secrets. See CONTRIBUTING.md for releases and the AWS CI guide for deployment setup and limits.

For PyPI-based verification, the mcp-name marker above must match the name field in server.json.

What's Next

Phase 2 (session management, rich diagnostics, tool annotations, prompt registry, core.verify) is complete as of 0.2.0, and Phase 3 (3a AgenticLens, 3b Agentic Chaos, 3c AI Operations Specification, 3d Sidecar discovery) is complete as of 0.3.3. What's still open (see ROADMAP.md for full detail):

• Sidecar runtime controls: richer control surfaces require an authenticated, task-scoped runtime bridge
• Phase 4 (Unified Workflows) — joined observability + chaos workflows, incident/readiness reporting, a higher-level control surface
• Future Control Tower coordination — once agenticops-control-tower ships real control-plane APIs, MCP should expose those operator-facing surfaces without reimplementing them here
• Phase 5/6 — PyPI + MCP Registry publishing, operational intelligence features

Development

A Makefile provides shorthand for common tasks:

make install     # install dev dependencies
make check       # run all quality gates (lint + format + typecheck + test)
make test-cov    # tests with coverage report
make docs        # regenerate docs/tools.md from tools/registry.py
make docs-check  # fail if docs/tools.md is out of date
make help        # list all available targets

Notes

This scaffold assumes the intended GitHub namespace is io.github.deepagentlabs/deep-agentic-core-mcp. If the final publishing account or org changes, update:

• the mcp-name marker in this README
• server.json
• any repository URLs in pyproject.toml

Operational safety roadmap

See planned safety acceptance criteria for responsibilities and dependencies. These additions do not claim implemented end-to-end containment or integrity protection.

Sidecar v0.7 compatibility

With Sidecar installed, sidecar.status detects its public decision, plan, runtime-event, audit and local operator APIs. runtime_ready means the decision API is installed; runtime_connected=false and mcp_runtime_controls=false make clear that these MCP discovery tools do not attach to an active task. sidecar.module_inventory lists adapter files, including placeholders; their presence does not certify framework support. No Sidecar dependency is required for MCP startup. An unavailable package produces an unavailable response.

For live task controls, use Sidecar's authenticated local OperatorServer/CLI interface described in its v0.7.0 live operations guide. Sidecar v0.7.0 is published separately. This patch improves discovery without enabling remote stop/revoke through MCP.