@aimodes/mcp-server

Standalone AI Modes MCP server — score AI conversations against the eight-mode engagement typology from any MCP host: Claude Desktop, Gemini CLI, VSCode (Copilot agent mode), Cursor, and ChatGPT connectors.

AI Modes scores conversations 0–100 against a research-backed engagement framework developed at BYU and returns a per-mode breakdown. This server exposes that scoring pipeline as MCP tools, authenticated with the same device token the AI Modes Chrome extension uses.

Quick start

1. Mint a device token at https://aimodes.ai/apps/ai-engagement/extension/auth
2. Run the server:

AIMODES_DEVICE_TOKEN=<token> npx -y @aimodes/mcp-server

By default the server speaks stdio (what desktop apps and IDEs expect). Pass --http for a stateless streamable-HTTP server instead:

AIMODES_DEVICE_TOKEN=<token> npx -y @aimodes/mcp-server --http --port 8787

MCP host configuration

Typical mcp.json / MCP server entry:

{
  "mcpServers": {
    "aimodes": {
      "command": "npx",
      "args": ["-y", "@aimodes/mcp-server"],
      "env": { "AIMODES_DEVICE_TOKEN": "<token>" }
    }
  }
}

Tools

| Tool | What it does | |---|---| | submit_conversation | Submit role-tagged turns for scoring on aimodes.ai | | score_transcript | Score a loose pasted transcript (parsed into turns first) | | get_status | Check auth/device-token status | | get_results | Fetch the score breakdown for a prior submission | | list_modes | List the eight engagement modes | | explain_mode | Explain one mode in depth |

Configuration

| Setting | How | Default | |---|---|---| | Device token | AIMODES_DEVICE_TOKEN env var | required for scoring | | API base URL | AIMODES_API_URL env var or --api-url | https://aimodes.ai | | Transport | --http flag | stdio | | HTTP port | --port | 8787 |

Built on @aimodes/connector-core and the official MCP SDK.

License

MIT © AI Modes