Nefesh — Real-Time Human State Awareness for AI

nefesh-ai/nefesh-mcp-server

Exposes six MCP tools for reading and tracking human physiological state in real time. Send biometric data (heart rate, HRV, voice tone, facial expression, sentiment) via `ingest` and get back a 0-100 stress score plus a `suggested_action` like "de-escalate" or "simplify". The standout feature is `adaptation_effectiveness`, which tells your agent whether its previous response actually lowered stress, creating a closed-loop feedback system. Also available as an A2A agent at `https://mcp.nefesh.ai/a2a` for agent-to-agent collaboration. Free tier includes 1,000 calls per month with no credit card. Reach for this when you want your AI to adjust tone, pacing, or complexity based on measurable human state instead of guessing from chat history.

tools: 7
auth: Secret needed
transport: HTTP
last updated: Apr 3, 2026

View on GitHub

Install

From registry metadata

$ npx add-mcp https://mcp.nefesh.ai/mcp --name human-state --header 'X-Nefesh-Key: ${X_NEFESH_KEY}'

Run in your terminal. add-mcp asks which agents to add it to, then asks for each value it needs. Add -g to install it for every project.

Review the command, arguments and environment values before installing. MCP servers run with your local permissions.

Other ways

Claude Code

$ claude mcp add --transport http human-state https://mcp.nefesh.ai/mcp --header 'X-Nefesh-Key: YOUR_X_NEFESH_KEY'

Run in your terminal. Add --scope user to make it available in every project.

Tools

Verified live · 7 tools

Verified live against the running server on Nov 6, 2026.

get_human_stateGet current unified human state for a session. Call this before generating important responses. Returns: - state: calm | relaxed | focused | stressed | acute_stress - stress_score: 0-100 (lower = calmer) - confidence: 0.0-1.0 (based on signal quality and device type) - suggest...1 params

Get current unified human state for a session. Call this before generating important responses. Returns: - state: calm | relaxed | focused | stressed | acute_stress - stress_score: 0-100 (lower = calmer) - confidence: 0.0-1.0 (based on signal quality and device type) - suggest...

Parameters* required

session_id*string

ingestSend biometric signals from any sensor, get unified state back. Required: session_id + timestamp (ISO 8601) + at least one signal. Send whatever you have — the API fuses all signals into one state. Common signals (highest impact): - heart_rate (bpm, 30-220) + rmssd (ms) — card...37 params

Send biometric signals from any sensor, get unified state back. Required: session_id + timestamp (ISO 8601) + at least one signal. Send whatever you have — the API fuses all signals into one state. Common signals (highest impact): - heart_rate (bpm, 30-220) + rmssd (ms) — card...

Parameters* required

activity_levelvalue

ai_responsevalue

cognitive_loadvalue

confidencevalue

edavalue

eeg_alpha_powervalue

eeg_beta_powervalue

eeg_theta_powervalue

engagementvalue

expressionvalue

gazevalue

glucose_mg_dlvalue

glucose_mmol_lvalue

glucose_trendvalue

heart_ratevalue

ibi_countvalue

mean_ibivalue

pitch_variabilityvalue

pnn50value

posturevalue

+17 more parameters. See the server's own documentation for the full schema.

get_trigger_memoryRetrieve psychological trigger profile for a subject. Returns which conversation topics consistently cause stress (active triggers) and which have been resolved over time. - active triggers: topics where stress was elevated across multiple sessions. Tread carefully. - resolved...1 params

Retrieve psychological trigger profile for a subject. Returns which conversation topics consistently cause stress (active triggers) and which have been resolved over time. - active triggers: topics where stress was elevated across multiple sessions. Tread carefully. - resolved...

Parameters* required

subject_id*string

get_session_historyGet state history for a session over time. Returns timestamped datapoints with stress_score, state, and heart_rate for each observation. Includes an overall trend: rising | falling | stable. Use minutes parameter to control the lookback window (default: 5, max: 60). Useful for...2 params

Get state history for a session over time. Returns timestamped datapoints with stress_score, state, and heart_rate for each observation. Includes an overall trend: rising | falling | stable. Use minutes parameter to control the lookback window (default: 5, max: 60). Useful for...

Parameters* required

minutesinteger

default: 5

session_id*string

delete_subjectPermanently delete all sessions and trigger memory for a subject. Irreversible. Only call when the user explicitly requests this deletion.1 params

Permanently delete all sessions and trigger memory for a subject. Irreversible. Only call when the user explicitly requests this deletion.

Parameters* required

subject_id*string

request_api_keyStart free API key authorization; no existing API key needed. Returns a verification_url. Ask the user to open that URL in their browser, enter their own email, then open the verification email and confirm access for their agent. This tool does not accept email addresses and d...

Start free API key authorization; no existing API key needed. Returns a verification_url. Ask the user to open that URL in their browser, enter their own email, then open the verification email and confirm access for their agent. This tool does not accept email addresses and d...

No parameters. Call it with no arguments.

check_api_key_statusCheck a pending API key authorization using its request_id. Use request_id exactly as returned by request_api_key, never an email. Poll every 10 seconds. awaiting_user means the user must open the URL; pending means email verification is still required. ready returns the API k...1 params

Check a pending API key authorization using its request_id. Use request_id exactly as returned by request_api_key, never an email. Poll every 10 seconds. awaiting_user means the user must open the URL; pending means email verification is still required. ready returns the API k...

Parameters* required

request_id*string

Readme

Nefesh MCP + A2A Server

A Model Context Protocol and Agent-to-Agent (A2A) server that gives AI agents real-time awareness of human physiological state.

What it does

Send sensor data (heart rate, voice, facial expression, text sentiment), get back a unified state with a machine-readable action your agent can follow directly. Zero prompt engineering required.

On the 2nd+ call, the response includes adaptation_effectiveness — telling your agent whether its previous approach actually worked. A closed-loop feedback system for self-improving agents.

Adaptation Effectiveness (Closed-Loop)

Most APIs give you a state. Nefesh tells you whether your reaction to that state actually worked.

On the 2nd+ call within a session, every response includes:

{
  "state": "focused",
  "stress_score": 45,
  "suggested_action": "simplify_and_focus",
  "adaptation_effectiveness": {
    "previous_action": "de-escalate_and_shorten",
    "previous_score": 68,
    "current_score": 45,
    "stress_delta": -23,
    "effective": true
  }
}

View the full README on GitHub

Details

Repository: github.com/nefesh-ai/nefesh-mcp-server
Transport: HTTP
Auth: Required
Registry: MCP registry, active
Tools verified: Nov 6, 2026