Connect an AI assistant with MCP

MCP human in the loop: when to pause an agent

Use a human in the loop MCP server when a decision depends on taste or tone: which of two replies is clearer, whether a person would send a delicate message, or which image makes the offer easier to understand. The agent asks for a quote with get_quote, sends a neutral question with ask_question, then calls get_results with the returned cursor. Each wait can last up to 25 seconds. When the pool closes, the owner can read the reasons and verify each live answer’s receipt before deciding what to do.

The sandbox follows the same flow with synthetic test answers and separate sandbox receipts. Keys are issued by invitation. This is useful for testing your code; it is not evidence that a person preferred an option. See the REST human judgement API and the agent accountability rules for the wider workflow.

Which setup do I need?

Endpoint

• URL: https://pennyforyours.com/mcp
• Transport: Streamable HTTP, stateless (no session ID), JSON responses. POST only; GET and DELETE return 405.
• Auth: Authorization: Bearer pfy_test_… on every request. Calls without a key get HTTP 401. OAuth sign-in is not offered yet.
• Mode: sandbox only. Synthetic test members answer within a few minutes, and nothing is charged.
• Protocol: built on the official MCP TypeScript SDK, which speaks protocol revisions up to 2025-11-25. The current specification revision is 2026-07-28, so your client must be able to use 2025-11-25 or an earlier revision.

Keep your key out of repositories: every snippet below reads it from an environment variable or a secure prompt, or has a placeholder for you to replace.

Claude Code

export PFY_API_KEY=pfy_test_...   # your sandbox key
claude mcp add --transport http --scope user pennyforyours https://pennyforyours.com/mcp \
  --header "Authorization: Bearer $PFY_API_KEY"

--scope is local (the default: this project, just you), project (shared through .mcp.json) or user (all your projects). Your shell expands $PFY_API_KEY before Claude Code sees it, so the key is stored in ~/.claude.json. To share the server with a team without committing the key, use the project file, which Claude Code expands from the environment:

{
  "mcpServers": {
    "pennyforyours": {
      "type": "http",
      "url": "https://pennyforyours.com/mcp",
      "headers": {
        "Authorization": "Bearer ${PFY_API_KEY}"
      }
    }
  }
}

Then ask: “Run a five-answer sandbox test: which bakery name sounds friendlier, Brightwell or Corvane?” Claude calls ask_question, then get_results until the synthetic pool closes.

Claude Desktop and claude.ai

Custom connectors work on Free (one custom connector), Pro, Max, Team and Enterprise plans. The connection is made from Anthropic's servers, so it reaches the hosted endpoint, not a server on your own machine.

Free, Pro and Max:

1. Open Customize → Connectors, select + Add, then Add custom connector.
2. Name it “PennyForYours” and enter https://pennyforyours.com/mcp.
3. Choose No sign in.
4. Under Request headers, add Authorization with the value Bearer pfy_test_…. Claude stores it encrypted and sends it with every request.
5. Add the connector, then switch it on in a chat.

Team and Enterprise: an Owner adds it under Organization settings → Connectors → Add → Custom → Web; members then connect from Customize → Connectors.

A local development server: use the mcp-remote bridge (MIT) in claude_desktop_config.json. The header value goes in env because some clients do not escape spaces in args:

{
  "mcpServers": {
    "pennyforyours": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://pennyforyours.com/mcp",
        "--header",
        "Authorization:${PFY_AUTH_HEADER}"
      ],
      "env": {
        "PFY_AUTH_HEADER": "Bearer pfy_test_..."
      }
    }
  }
}

ChatGPT and OpenAI

In the ChatGPT app, through developer mode connectors: not yet. ChatGPT's connector screen supports OAuth, no authentication, or a mix of the two. It can't send a fixed API key, and our MCP server needs one. OAuth is on our list; tell us if it would let you use this connection.

In ChatGPT, through a Custom GPT Action: yes

Use the REST API instead of MCP:

1. In the GPT editor, add an Action and paste in the OpenAPI document from https://pennyforyours.com/v1/openapi.json.
2. Set Authentication to API Key, choose Bearer, and paste your sandbox key.
3. In the GPT's instructions, tell it to call GET /v1/question-types, then POST /v1/questions with an Idempotency-Key, then GET /v1/questions/{id} with the returned cursor until the state is closed.

Actions time out after 45 seconds, so keep wait_seconds at 25 or less. Results can take minutes, so the GPT may need to check back rather than wait in one turn.

OpenAI Responses API

{
  "model": "YOUR_MODEL",
  "input": "Run a five-answer sandbox test: which bakery name sounds friendlier, Brightwell or Corvane?",
  "tools": [
    {
      "type": "mcp",
      "server_label": "pennyforyours",
      "server_url": "https://pennyforyours.com/mcp",
      "headers": {
        "Authorization": "Bearer pfy_test_..."
      },
      "require_approval": "never"
    }
  ]
}

OpenAI Agents SDK (Python)

from agents.mcp import MCPServerStreamableHttp

server = MCPServerStreamableHttp(
    name="pennyforyours",
    params={
        "url": "https://pennyforyours.com/mcp",
        "headers": {"Authorization": f"Bearer {api_key}"},
        "timeout": 30,  # get_results can wait up to 25 seconds in one call
    },
)

OpenAI Codex CLI

# ~/.codex/config.toml
[mcp_servers.pennyforyours]
url = "https://pennyforyours.com/mcp"
bearer_token_env_var = "PFY_API_KEY"

Or run codex mcp add pennyforyours --url https://pennyforyours.com/mcp --bearer-token-env-var PFY_API_KEY.

Cursor

In .cursor/mcp.json (this project) or ~/.cursor/mcp.json (everywhere). Cursor reads environment variables as ${env:NAME}.

{
  "mcpServers": {
    "pennyforyours": {
      "url": "https://pennyforyours.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:PFY_API_KEY}"
      }
    }
  }
}

VS Code (Copilot agent mode)

Run MCP: Add Server. For new servers VS Code recommends its portable destinations: a workspace .mcp.json (the same mcpServers format as Claude Code) or your Copilot settings. The older .vscode/mcp.json is marked deprecated but still works, and it is the format where VS Code can prompt for the key once and store it securely:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "pfy-api-key",
      "description": "PennyForYours sandbox API key",
      "password": true
    }
  ],
  "servers": {
    "pennyforyours": {
      "type": "http",
      "url": "https://pennyforyours.com/mcp",
      "headers": {
        "Authorization": "Bearer ${input:pfy-api-key}"
      }
    }
  }
}

VS Code's documentation does not say the portable .mcp.json supports this key prompt, and servers that use ${input:…} are not passed to its Agent Host.

Other clients

• Gemini CLI: gemini mcp add --transport http --header "Authorization: Bearer $PFY_API_KEY" pennyforyours https://pennyforyours.com/mcp. In settings.json, a Streamable HTTP server goes under httpUrl (url means the older SSE transport).
• Zed: add a remote server under context_servers with url and headers.
• Devin Desktop, legacy Cascade agent: Devin's Cascade guide uses serverUrl plus headers in ~/.config/devin/mcp_config.json (macOS and Linux), with ${env:VAR} for the key. New tabs use Devin Local and its separate MCP setup.
• Anything else: if it can send a header to a remote Streamable HTTP MCP server, it should work.

MCP Inspector and raw HTTP

npx @modelcontextprotocol/inspector --cli https://pennyforyours.com/mcp --transport http \
  --method tools/list --header "Authorization: Bearer $PFY_API_KEY"

Any HTTP client works. Send JSON-RPC with POST and accept both JSON and event streams:

curl https://pennyforyours.com/mcp \
  -H "Authorization: Bearer $PFY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_question_types","arguments":{}}}'

Human in the loop MCP server tools

Each tool mirrors a REST endpoint and needs the same scope. Errors come back as tool results with isError: true and a problem object (type, status, detail), so the model can read them and recover.

Transport details

• Stateless Streamable HTTP built on the official MCP TypeScript SDK. Every request stands alone, so there is no Mcp-Session-Id; GET and DELETE return 405.
• get_results long-polls for up to 25 seconds inside a single call; nothing streams back mid-call.
• Rate limits are per key and shared with REST: a tool call uses the same budget as its endpoint. See sandbox and limits.
• Optional header X-Agent-Name records which agent asked. Members are told when a question came through an AI tool.

PennyForYours lets you ask verified real people quick questions and get structured answers back, each with a signed receipt.

Use it when a human judgement beats a model: first impressions of an image or text, which of 2–3 options people prefer, whether something reads clearly, or a 1–5 rating with a reason.

Typical flow: list_question_types → get_quote (optional) → ask_question → get_results with cursor and wait_seconds until state is "closed" → rate_answers. Use get_receipt and verify_receipt to prove an answer came from a verified person.

Ask neutral questions: do not lead, do not reveal which option you prefer, keep the prompt under 280 characters.

Every call is made under an operator API key whose owner is accountable for it. Members are told when a question came through an AI tool. Rules for agents: https://pennyforyours.com/agents/

Sandbox mode: during early access only pfy_test_ keys are issued. Sandbox questions are answered by synthetic test members within a few minutes, every answer is marked synthetic, and nothing reaches real people.

Priced per answer by answer type. Launch example: a quick take (pick or rate plus one line of why, about 30 seconds) from 30p a person, plus 50p a question for screening and the summary. Free during early access: nothing is charged.

Pools of 5 to 50 people. Text or an image (PNG, JPEG or WebP); links and URL questions are refused.

Not for regulated advice (medical, legal, financial), collecting personal data, or writing reviews.

Sources

Each client's steps were checked against its own documentation on 5 October 2026.