Human Guides / MCP Setup

🔌 MCP Setup

Model Context Protocol servers give agents eyes and hands beyond file editing. Install these once — every agent in every project on this machine gets them automatically.

~15 min total setup Install once, use everywhere Unlocks: autonomous testing
What MCPs do
Without MCPs vs With MCPs
❌ Without MCPs
Agent builds login form → says "done" → you open the browser to test → you find a bug → you tell the agent → it fixes → you test again → repeat.
✓ With MCPs
Agent builds login form → opens browser via Playwright → fills credentials → submits → sees redirect succeeded → queries Supabase to confirm session stored → marks done with evidence.
MCP 1 of 4 — Most important
Playwright MCP — UI testing & browser control
🎭
Playwright MCP
@playwright/mcp
Gives agents a real browser. Navigate URLs, click buttons, fill forms, take screenshots, read page content — all while your app runs locally.
UI Testing
Setup — 3 steps
1

Install Playwright browsers (one time)

$ npx playwright install chromium
2

Add to ~/.claude.json

// ~/.claude.json { "mcpServers": { "playwright": { "command": "npx", "args": ["-y", "@playwright/mcp@latest"] } } }
3

Restart Claude Code — type /mcp to verify

You should see "playwright" listed as connected.

What agents can now do automatically
✅
Test login flows — navigate to /login, fill credentials, confirm redirect
✅
Test signup — fill form, submit, confirm success page, verify email sent
✅
Check UI states — loading spinners, error messages, empty states, disabled buttons
✅
Take screenshots — attach visual evidence to test reports in .ay/tracking/
✅
Test navigation — all routes load, 404 pages work, redirects correct
MCP 2 of 4
HTTP Testing — API verification via Bash
🌐
HTTP / curl (built-in via Bash)
No install needed — agents use Bash + curl
Agents already have Bash. They use curl to call your API endpoints and verify responses, status codes, and schemas.
API Testing
No setup — this is how agents use it
1

Agents test API endpoints automatically

Inside a Bash tool call
# Test POST /api/users
RESPONSE=$(curl -s -w "\n%{http_code}" -X POST http://localhost:3000/api/users \
-H "Content-Type: application/json" \
-d '{"email":"test@example.com","name":"Test User"}')

CODE=$(echo "$RESPONSE" | tail -1)
[[ "$CODE" == "201" ]] && echo "PASS: 201 Created" || echo "FAIL: got $CODE"
What agents verify automatically
✅
Status codes — 200, 201, 400, 401, 404, 409, 500 — verified not assumed
✅
Response schema — required fields present, correct types, no unexpected nulls
✅
Auth headers — endpoints return 401 without token, 200 with valid token
MCP 3 of 4
Supabase MCP — direct database access
🗄️
Supabase MCP
@supabase/mcp-server-supabase
Agents can query your Supabase DB directly to verify writes, check RLS policies, run migrations, and confirm user data.
Database
Setup — 2 steps
1

Get your Supabase Personal Access Token

Go to app.supabase.com → Account → Access Tokens → New Token. Name it "ay-framework MCP". Copy the token.

2

Add to ~/.claude.json inside mcpServers

"supabase": { "command": "npx", "args": [ "-y", "@supabase/mcp-server-supabase@latest", "--access-token", "YOUR_PERSONAL_ACCESS_TOKEN_HERE" ] }
What agents verify automatically
✅
Data writes — after inserting, query DB to confirm row exists with correct values
✅
RLS policies — verify user can only see their own rows, not others'
✅
Auth state — after signup, confirm user in auth.users with correct metadata
MCP 4 of 4
Email Testing — Mailpit (local SMTP)
📧
Mailpit — local email testing
docker pull axllent/mailpit
Local SMTP server with an API. Agents send emails through it during development, then call the API to confirm arrival, read body, extract links.
Email Testing
Setup — 3 steps
1

Run Mailpit

$ docker run -d -p 1025:1025 -p 8025:8025 axllent/mailpit
# SMTP on :1025, web UI on http://localhost:8025
2

Point your app at Mailpit in .env.local

SMTP_HOST=localhost
SMTP_PORT=1025
3

Agents verify email via Mailpit API

# Check for email after triggering password reset
EMAILS=$(curl -s http://localhost:8025/api/v1/messages)
echo $EMAILS | jq '.[0].Subject' | grep -q "Reset" \
&& echo "PASS: email received" || echo "FAIL"
What agents verify automatically
✅
Email delivery — confirm arrival after triggering action
✅
Subject + body — no placeholder text, links are real
✅
Reset links — extract, follow, verify page loads
Complete config
Full ~/.claude.json with all MCPs
{ "mcpServers": { "playwright": { "command": "npx", "args": ["-y", "@playwright/mcp@latest"] }, "supabase": { "command": "npx", "args": [ "-y", "@supabase/mcp-server-supabase@latest", "--access-token", "YOUR_SUPABASE_PAT_HERE" ] } }, "permissions": { "allow": ["mcp__playwright__*", "mcp__supabase__*"] } }
After restart: Type /mcp in Claude Code to see connected servers. Every agent in every project now has these tools.
Security: Playwright can control any browser on your machine. Supabase PAT gives read/write to your projects — use a dedicated token, not your main account password.