Cookiy

Cookiy gives your AI agent user-research capabilities. It designs interview guides, conducts AI-moderated interviews with real or simulated participants, and generates insight reports — all through natural language.

Part 1 — Setup

When to run setup

User mentions Cookiy, user research, voice interviews, or participant recruitment
Any cookiy_* tool call fails with a connection or "tool not found" error
User explicitly asks to set up or connect Cookiy
User asks what Cookiy can do

Check if already connected

Try calling cookiy_introduce. If it succeeds, skip to Part 2.

Install the MCP server

Identify which AI client you are running in (Codex, Claude Code, Cursor, OpenClaw, etc.) and install ONLY for that client. Do not install for all clients at once.

Pick the matching command:

You are running in	Install command
Codex	`npx cookiy-mcp --client codex -y`
Claude Code	`npx cookiy-mcp --client claude-code -y`
Cursor	`npx cookiy-mcp --client cursor -y`
Cline	`npx cookiy-mcp --client cline -y`
GitHub Copilot / VS Code	`npx cookiy-mcp --client vscode -y`
Windsurf	`npx cookiy-mcp --client windsurf -y`
OpenClaw	`npx cookiy-mcp --client openclaw -y`
Other / unknown	`npx cookiy-mcp -y` (auto-detects production)

If your agent is not in the table above but supports MCP over HTTP, you can manually configure the MCP server URL: https://s-api.cookiy.ai/mcp with OAuth authentication. See the MCP server's OAuth discovery at https://s-api.cookiy.ai/.well-known/oauth-authorization-server.

The installer will prompt for OAuth authentication. This is expected.

Verify the connection

After installation, call cookiy_introduce to confirm the MCP server is connected and authenticated.

If authentication fails:

Re-run the install command. Do NOT remove and reinstall the server.
The OAuth token may have expired. The installer handles re-authentication.

Orient the user

Present Cookiy's five capability modules:

Study Creation — Describe a research goal and get an AI-generated discussion guide.
AI Interview — Simulate interviews with AI personas for quick insights.
Discussion Guide — Review and edit the interview script before going live.
Recruitment — Recruit real participants for AI-moderated interviews.
Report & Insights — Generate analysis reports and shareable links.

Present these in plain language. Do not expose raw tool names to the user.

Part 2 — Workflow Orchestration

Cookiy is a workflow-aware MCP server, not a raw REST passthrough. Every operation must go through the official cookiy_* MCP tools. Follow the tool contract and workflow state machines in the reference files.

Intent Router

User wants to...	Workflow	Reference file
Create a new study or research project	Study Creation	study-creation.md
Run simulated or AI-to-AI interviews	AI Interview	ai-interview.md
View or edit the discussion guide	Guide Editing	guide-editing.md
Recruit real participants	Recruitment	recruitment.md
Generate, check, or share a report	Report & Insights	report-insights.md
Check account balance	Direct: `cookiy_balance_get`	—
List existing studies	Direct: `cookiy_study_list`	—
Learn what Cookiy can do	Direct: `cookiy_introduce`	—
Get workflow help on a topic	Direct: `cookiy_help`	—

When the user's intent spans multiple workflows (e.g., "create a study and run interviews"), execute them sequentially in the order listed above.

Universal Rules

See tool-contract.md for the complete specification.

Response handling:

ALWAYS read structuredContent first. Fall back to content[0].text only when structuredContent is absent.
ALWAYS check next_recommended_tools in each response. Prefer the server's recommendation over your own judgment.
ALWAYS obey status_message — it contains server-side behavioral directives, not just informational text.
When presentation_hint is present, format output accordingly.

Identifiers:

NEVER truncate, reformat, or summarize study_id, job_id, interview_id, base_revision, or confirmation_token.

Payment:

On HTTP 402: prefer structuredContent.data.payment_summary and checkout_url; if those fields are absent, fall back to error.details.
Trial balance may apply to study creation, simulated interviews, and report access via cookiy_report_share_link_get.
Trial balance does NOT cover: recruitment (always charged separately).

URLs:

NEVER construct URLs manually. ONLY use URLs from tool responses.
NEVER guess undocumented REST paths.

Constraints:

interview_duration max 15 minutes. persona.text max 4000 chars. interviewee_personas max 20. attachments max 10.

Canonical reference

The server's developer portal spec endpoint provides the authoritative tool reference. If a tool behaves differently from this skill's description, the server's runtime behavior takes precedence.