MCP Tools

AgenticCognition exposes 14 MCP tools over JSON-RPC 2.0 stdio transport. Each tool follows the Agentra MCP quality standard: verb-first imperative descriptions, isError: true for execution errors, and JSON-RPC error codes for protocol violations.

cognition_model_create

Create a new living user model.

Returns the model ID and initial lifecycle stage (Birth).

cognition_model_heartbeat

Record an interaction heartbeat to advance the living user model.

The heartbeat advances the model lifecycle, updates activity metrics, and incorporates any observations into the belief graph.

cognition_model_vitals

Retrieve health metrics and activity summary for a living user model.

Returns lifecycle stage, belief count, last heartbeat timestamp, interaction count, and model health score.

cognition_model_portrait

Generate a natural-language portrait of the user based on the living model.

Returns a structured portrait containing identity summary, core values, behavioral patterns, and growth trajectory.

cognition_belief_add

Add a new belief to the living user model.

Returns the belief ID and initial physical properties.

cognition_belief_query

Query beliefs in the model by text, domain, or property.

Returns a list of matching beliefs with their full properties.

cognition_belief_graph

Retrieve the full belief graph showing entanglements and relationships.

Returns nodes (beliefs) and edges (entanglements, tensions, supports) with relationship types and weights.

cognition_soul_reflect

Produce a deep soul reflection across all model dimensions.

Returns a multi-dimensional reflection covering core identity, belief architecture, shadow patterns, growth trajectory, and inner tensions.

cognition_self_topology

Generate the self-concept topology map showing identity landscape.

Returns identity peaks (strongest self-beliefs), valleys (weakest), edges (boundaries), and defended territories (resistant to change).

cognition_pattern_fingerprint

Generate a decision-making fingerprint from behavioral patterns.

Returns the decision fingerprint including dominant patterns, recurring themes, risk profile, and consistency score.

cognition_shadow_map

Generate the shadow map showing unconscious patterns.

Returns shadow beliefs, projections (attributes ascribed to others that belong to self), blindspots (gaps between self-assessment and behavior), defended regions, bias fields, and emotional triggers.

cognition_drift_track

Track longitudinal drift in beliefs, values, and identity.

Returns drift events, value tectonic movements, and growth ring snapshots over the specified time range.

cognition_predict

Predict user preferences, reactions, or choices.

Returns the prediction with confidence, supporting beliefs, and reasoning chain.

cognition_simulate

Simulate a decision scenario with multiple options.

Returns per-option analysis showing alignment with values, predicted satisfaction, risk assessment, and the recommended choice with reasoning.

Error Handling

Tool execution errors return results with isError: true in the MCP content:

{
  "content": [{"type": "text", "text": "Model not found: abc-123"}],
  "isError": true
}

Protocol errors use standard JSON-RPC error codes:

Tool Surface Control

The exposed tool set can be restricted via ACOG_MCP_TOOL_SURFACE or --tool-surface. When set, only listed tools respond; unlisted tools return TOOL_NOT_FOUND.