Nefesh — Real-Time Human State Awareness for AI

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
  }
}

Your agent can read effective: true and know its previous de-escalation worked. If effective: false, the agent adjusts its strategy. No other human-state system provides this feedback loop.

Setup

Option A: Connect first, get a key through your agent (fastest)

Add the config without an API key — your agent will get one automatically.

{
  "mcpServers": {
    "nefesh": {
      "url": "https://mcp.nefesh.ai/mcp"
    }
  }
}

Then ask your agent:

"Get me a free Nefesh API key using my email address"

The agent calls request_api_key → you click one email link → the agent picks up the key. No signup form, no manual copy-paste. After that, add the key to your config for future sessions:

{
  "mcpServers": {
    "nefesh": {
      "url": "https://mcp.nefesh.ai/mcp",
      "headers": {
        "X-Nefesh-Key": "nfsh_free_..."
      }
    }
  }
}

Option B: Get a key first, then connect

Sign up at nefesh.ai/signup (1,000 calls/month, no credit card), then add the config with your key:

{
  "mcpServers": {
    "nefesh": {
      "url": "https://mcp.nefesh.ai/mcp",
      "headers": {
        "X-Nefesh-Key": "YOUR_API_KEY"
      }
    }
  }
}

Agent-specific config files

{
  "servers": {
    "nefesh": {
      "type": "http",
      "url": "https://mcp.nefesh.ai/mcp",
      "headers": {
        "X-Nefesh-Key": "<YOUR_API_KEY>"
      }
    }
  }
}

{
  "context_servers": {
    "nefesh": {
      "settings": {
        "url": "https://mcp.nefesh.ai/mcp",
        "headers": {
          "X-Nefesh-Key": "<YOUR_API_KEY>"
        }
      }
    }
  }
}

[mcp_servers.nefesh]
url = "https://mcp.nefesh.ai/mcp"

mcpServers:
  - name: nefesh
    type: streamable-http
    url: https://mcp.nefesh.ai/mcp

All agents connect via Streamable HTTP — no local installation required.

A2A Integration (Agent-to-Agent Protocol v1.0)

Nefesh is also available as an A2A-compatible agent. While MCP handles tool-calling (your agent calls Nefesh), A2A enables agent-collaboration — other AI agents can communicate with Nefesh as a peer.

Agent Card: /.well-known/agent-card.json

A2A Endpoint: POST https://mcp.nefesh.ai/a2a (JSON-RPC 2.0)

Same authentication as MCP — X-Nefesh-Key header or Authorization: Bearer token. Free tier works on both protocols.

Source: nefesh-ai/nefesh-a2a · Docs: nefesh.ai/docs/a2a

MCP Tools

How self-provisioning works

Your AI agent can get a free API key autonomously. You only click one email link.

1. Agent asks you: "What is your email address?"
2. Agent calls request_api_key(your_real_email). No API key needed for this call.
3. You receive a verification email and click the link
4. Agent polls check_api_key_status(your_real_email) every 10 seconds
5. Once verified, the agent receives the API key and can use all other tools

Important: The agent must use your real, accessible email address. Disposable emails are blocked. The verification link must be clicked by you to activate the key.

Free tier: 1,000 calls/month, all signal types, 10 req/min. No credit card.

Quick test

After adding the config, ask your AI agent:

"What tools do you have from Nefesh?"

It should list the 6 tools above.

Pricing

CLI Alternative

Prefer the terminal over MCP? Use the Nefesh CLI (10-32x lower token cost than MCP for AI agents):

npm install -g @nefesh/cli
nefesh ingest --session test --heart-rate 72 --tone calm
nefesh state test --json

GitHub: nefesh-ai/nefesh-cli

Gateway Alternative

Want the AI to adapt automatically? Use the Nefesh Cognitive Compute Router. Change your LLM base URL to gateway.nefesh.ai and the gateway adjusts system prompt and temperature based on biometric state. Three modes: OpenAI-compatible (/v1/chat/completions), Anthropic passthrough (/v1/messages), and Unified Anthropic for any backend. Zero code changes.

GitHub: nefesh-ai/nefesh-gateway

Human State Protocol (HSP)

Nefesh implements and maintains the Human State Protocol, an open specification for exchanging human physiological state between AI systems. HSP defines a standard JSON format for stress scores, behavioral recommendations, and adaptation feedback so any agent can produce or consume human state data interoperably. Apache 2.0.

GitHub: nefesh-ai/human-state-protocol · Docs: nefesh.ai/docs/hsp

Documentation

• Full API Reference
• Quick Start
• State Mapping
• MCP Server · Source
• A2A Server · Source
• Cognitive Compute Router (Gateway) · Source
• CLI · Source
• Human State Protocol (HSP) · Source
• A2A Agent Card
• A2A Protocol Spec

Privacy

• No video or audio uploads — edge processing runs client-side
• No PII stored
• GDPR/BIPA compliant — cascading deletion via delete_subject
• Not a medical device — for contextual AI adaptation only

License

MIT — see LICENSE.