# @afferens/mcp-server

MCP server for [Afferens](https://afferens.com) - real-time physical perception for AI agents.

Use it from local MCP clients over stdio or remote/hosted clients over streamable HTTP. It gives any MCP-compatible AI assistant live sensor data: object detections, positions, sounds, environmental readings, chemical traces, and node health.

## Tools

| Tool | Auth | Description |
|------|------|-------------|
| `afferens_demo` | None | Live perception data across all 6 modalities. Free, no key needed. |
| `afferens_perceive` | API key | Query live events by modality with filtering and limits. |
| `afferens_verify` | API key | Fetch the feed twice and return a proof bundle with headers, age, and a freshness verdict. |

**Modalities:** `VISION` / `SPATIAL` / `ACOUSTIC` / `ENVIRONMENTAL` / `MOLECULAR` / `INTEROCEPTION`

## Quick Start

Free tier: 10,000 tokens, no card required. Get your key at [afferens.com](https://afferens.com).

### Local MCP Clients

```bash
claude mcp add afferens -- npx -y @afferens/mcp-server
```

Then set your key:

```bash
claude mcp add afferens -e AFFERENS_API_KEY=YOUR_KEY -- npx -y @afferens/mcp-server
```

This stdio setup works for Claude Code, Claude Desktop, Cursor, and Windsurf.

### Remote MCP Clients

For hosted or browser-based clients, run Afferens in HTTP mode and point the client at the `/mcp` endpoint:

```bash
AFFERENS_TRANSPORT=http AFFERENS_PORT=8790 AFFERENS_API_KEY=YOUR_KEY node dist/index.js
```

Then register the endpoint:

```json
{
  "afferens": {
    "url": "http://127.0.0.1:8790/mcp",
    "bearer_token_env_var": "AFFERENS_API_KEY"
  }
}
```

### Claude Desktop / Cursor / Windsurf

Add to your MCP config file:

```json
{
  "mcpServers": {
    "afferens": {
      "command": "npx",
      "args": ["-y", "@afferens/mcp-server"],
      "env": {
        "AFFERENS_API_KEY": "YOUR_KEY"
      }
    }
  }
}
```

Config file locations:
- Claude Desktop (Mac): `~/Library/Application Support/Claude/claude_desktop_config.json`
- Claude Desktop (Windows): `%APPDATA%\Claude\claude_desktop_config.json`
- Cursor: `.cursor/mcp.json` in your project root
- Windsurf: `~/.codeium/windsurf/mcp_config.json`

### Try it without a key

```json
{
  "mcpServers": {
    "afferens": {
      "command": "npx",
      "args": ["-y", "@afferens/mcp-server"]
    }
  }
}
```

Call `afferens_demo` - no API key needed.

## Usage

Once connected, your AI agent can call:

```text
afferens_perceive({ modality: "VISION", limit: 5 })
```

Returns structured perception events your agent can reason over and act on.

For demo verification:

```text
afferens_verify({ modality: "VISION", limit: 3, wait_ms: 2000 })
```

Returns two raw snapshots plus headers, age, and a hash check so you can show whether the feed is live, stale, or unchanged.

## Links

- [afferens.com](https://afferens.com) - sign up, dashboard, API docs
- [npm](https://www.npmjs.com/package/@afferens/mcp-server)
- [Smithery](https://smithery.ai/servers/afferens/afferens-mcp)

## License

MIT