Menso

Menso

AI users run real tasks on your live site and show where they get stuck, with a replay of every step.

This repository holds the public parts of Menso's developer integration:

• the settings for Menso's hosted MCP server, for Claude (as a custom connector), Claude Code (as a plugin), Codex, Cursor, Windsurf and any MCP client that supports Streamable HTTP with OAuth sign-in or a custom Authorization header;
• menso, the command line for terminals and CI (bin/, src/);
• the entry for the official MCP registry (mcp-registry/server.json).

The test runner, the AI users and the scoring run on Menso's servers and are not part of this repository. MCP documentation: menso.io/docs/mcp.

1. Sign in, or create an API key

Clients that support OAuth, such as Claude on claude.ai and the Claude desktop app, connect with your Menso sign-in and need no key: skip to Claude (custom connector) below.

For the others, sign in to Menso, open Settings and choose Create API key. Copy it right away: Menso shows it once. Keep it in an environment variable or a CI secret, never in a repository.

2. Connect your editor (MCP)

The server is hosted at https://api.menso.io/mcp (Streamable HTTP). Nothing to install.

Claude (custom connector)

In Claude, open Settings → Connectors → Add custom connector, name it Menso and paste https://api.menso.io/mcp. Claude finds Menso's sign-in by itself; leave the advanced OAuth fields empty. Choose Connect, sign in to Menso and allow access on the Connect Menso page. The four tools below then appear in Claude. Remove the connector in Claude to disconnect.

Claude Code (plugin)

This repository is a Claude Code plugin. Install it in one step; Claude Code asks for your Menso API key and keeps it in secure storage:

/plugin install menso --marketplace menso-io/menso

From a shell, the same is claude plugin marketplace add menso-io/menso and then claude plugin install menso@menso.

Claude Code (without the plugin)

claude mcp add --transport http menso https://api.menso.io/mcp \  --header "Authorization: Bearer YOUR_MENSO_API_KEY"

To share it with a team, put this in .mcp.json at the project root; each person sets MENSO_API_KEY in their own shell:

{  "mcpServers": {    "menso": {      "type": "http",      "url": "https://api.menso.io/mcp",      "headers": { "Authorization": "Bearer ${MENSO_API_KEY}" }    }  }}

Cursor (~/.cursor/mcp.json or .cursor/mcp.json)

{  "mcpServers": {    "menso": {      "url": "https://api.menso.io/mcp",      "headers": { "Authorization": "Bearer ${env:MENSO_API_KEY}" }    }  }}

Windsurf (~/.codeium/windsurf/mcp_config.json)

{  "mcpServers": {    "menso": {      "serverUrl": "https://api.menso.io/mcp",      "headers": { "Authorization": "Bearer ${env:MENSO_API_KEY}" }    }  }}

Codex (~/.codex/config.toml; Codex reads the key from MENSO_API_KEY in your shell)

[mcp_servers.menso]url = "https://api.menso.io/mcp"bearer_token_env_var = "MENSO_API_KEY"

Cursor plugin

This repository is also a Cursor plugin: .cursor-plugin/plugin.json and mcp.json add the Menso MCP server. After you install it, set MENSO_API_KEY to your Menso API key where Cursor asks for the plugin's configuration (Plugins → Configure).

Then ask for a test in plain words: "Run a Menso signup test on https://staging.example.com and tell me where the AI user got stuck."

Tools

3. Command line

Node.js 20 or newer. The npm package @menso/cli is being published; until then, run it from this repository:

git clone https://github.com/menso-io/menso.git && cd mensoexport MENSO_API_KEY=menso_sk_...
# Start a test and wait for the findingsnode bin/menso.mjs run https://staging.example.com --wait
# Sign-up flow with a dedicated test inbox; the password comes from the environmentMENSO_TEST_PASSWORD='a-test-only-password' \  node bin/menso.mjs run https://staging.example.com --template signup --email [email protected] --wait
# Check a run, read its findingsnode bin/menso.mjs status <test_id>node bin/menso.mjs findings <test_id> --json

Exit codes: 0 ok, 1 error, 2 usage, 3 run failed or scored below --fail-under. In GitHub Actions the findings are also added to the job summary; examples/github-action.yml tests each successful deployment (it uses the npm package, so it works once @menso/cli 1.0 is published).

Tests and security

Runs started through MCP or the command line follow the same rules as runs started on menso.io: the month's tests are checked before a run starts, and a run interrupted by a problem on Menso's side does not count. The key can start tests and read your account's results; error messages may show how many tests are left and your plan. It cannot change your plan or payment details, and it cannot create or revoke keys. Revoke it in Settings if it leaks. Test only sites you own or have permission to test.

Questions: [email protected]

License

MIT