# Guizzo for agents

Guizzo is a remote MCP server that connects agents with people. Your agent asks a person a question or for an approval, the person answers by email and a web page or from their own AI client, and the answer comes back to the agent. Facts and decisions the team saves are there for every agent of the team to find again.

The Guizzo beta is free. Sign up at https://app.guizzo.ai; new workspaces open a few at a time, with a queue when every place is taken.

## Connect

Add Guizzo to your AI client as a remote MCP server (in chat apps such as Claude and ChatGPT, a custom connector) with this address, then sign in with your Guizzo account when the client asks:

    https://mcp.guizzo.ai/mcp

## Sign-in

- AI clients sign in with OAuth 2.1, as described by the MCP authorization spec. Guizzo accepts Client ID Metadata Documents and Dynamic Client Registration. The client acts as the person who signed in, in one workspace, and the person can disconnect it from the dashboard.
- Agents that run on their own (scripts, background agents, n8n, Zapier) use an API key, created in the dashboard under Access and sent as `Authorization: Bearer gz_...`. A key acts as the person who created it and can have a spending cap.

Discovery: `https://mcp.guizzo.ai/.well-known/oauth-protected-resource/mcp` names the authorization server, `https://app.guizzo.ai`. The OAuth scope is `mcp`.

## Protocol

Streamable HTTP, stateless, with plain JSON responses. Guizzo speaks MCP 2026-07-28 and 2025-11-25. It offers no GET stream: there are no sessions to keep open. Everything Guizzo does is a tool; it uses no prompts or resources apart from the answer form shown to clients that display MCP Apps.

## Tools

| Tool | What it does | Credits |
| --- | --- | --- |
| `ask_person` | Sends a question to up to 20 people by email, with an optional form (text, yes/no, number, date, choice). Returns a `request_id` at once; the answers arrive later. Waits for the first answer, all of them, or a quorum. | 1 |
| `request_approval` | Asks up to 10 approvers for an explicit yes or no before an action. Each approver decides on a web page and confirms with a code or a passkey. Can save the outcome as a decision. | 1 |
| `ask_user` | Asks the user of this session structured questions, shown as a form where the client supports it. Nothing is stored. | 0 |
| `inbox` | Your recent requests with their status and answers, and the requests waiting for your answer. | 0 |
| `respond` | Answers a request someone sent you, by `request_id`, from any workspace. | 0 |
| `people` | Lists the workspace members and the address book, to name recipients by name. | 0 |
| `add_contact` | Adds people outside the workspace to the address book, personal or shared. | 0 |
| `remember` | Saves a fact, such as a preference, a constraint or a current state. | 0 |
| `log_decision` | Saves a decision with its reasoning, the alternatives and who decided. | 0 |
| `recall` | Searches the saved facts and decisions by words, kind, project and date, with whether each one is still valid. | 0 |

Every tool returns structured content, described by its output schema, and the same result as readable text.

## Limits

- Questions and approvals use credits from the workspace's monthly allowance, shared by the team and its agents; the results of `ask_person` and `request_approval` include `credits_remaining`. Unused credits do not roll over. The other tools use none. A request whose emails reach nobody (the address does not exist, or no longer receives our email), sent to people without a Guizzo account (who would still see it there), and with no answer is refunded; `inbox` shows each recipient's delivery.
- A question stays open 7 days unless you set `expires_in_hours` (1 hour to 30 days); an approval 24 hours.
- The plan sets how many members and contacts a workspace can have, whether agents can write to any email address or only to members and contacts, how long closed questions are kept, and how many facts and decisions can be saved and shared.
- People who answer never pay and need no account.

## Rules for messages to people

Questions and approvals go to real people, so the terms of use (https://guizzo.ai/terms) set what agents may send. In short: write only to people who would expect to hear from you, never to lists, scraped or guessed addresses, and never advertising or bulk messages; respect blocks and daily limits instead of working around them; do not ask for passwords, codes, payment card details or sensitive data people have not agreed to share; do not pretend a message comes from someone else; do not use Guizzo where a late or wrong answer could put someone's life, health or safety at risk; and do not use an answer as the only basis for a decision with legal or similarly significant effects on the person who gave it. Recipients can stop requests with one click and report abuse to abuse@guizzo.ai. The skill below spells these rules out for agents.

## How answers come back

AI clients support different parts of MCP, so Guizzo uses what each client declares and always has a way that works:

| If the client supports | Guizzo |
| --- | --- |
| MCP Apps | `ask_user` shows the answer form in the chat. |
| Elicitation (form), on MCP 2026-07-28 | `ask_user` asks with the client's own form. |
| The Tasks extension | `ask_person` and `request_approval` return a task that completes when the answer or the decision arrives. |
| None of these | The tools return text with the questions, and answers are read with `inbox`. Recipients always have the email and the web page. |

We are testing each client during the closed beta and will publish the results here.

## Calling without an MCP client

Any program that can send an HTTP request can call a tool with an API key, as JSON-RPC over MCP 2026-07-28:

```sh
curl https://mcp.guizzo.ai/mcp \
  -H "Authorization: Bearer $GUIZZO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2026-07-28" \
  -H "Mcp-Method: tools/call" \
  -H "Mcp-Name: ask_person" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{
    "name":"ask_person",
    "arguments":{"to":["giulia@example.com"],"title":"Can we ship on Friday?",
      "fields":[{"type":"boolean","name":"ship","label":"Ship on Friday"}]},
    "_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28",
      "io.modelcontextprotocol/clientCapabilities":{},
      "io.modelcontextprotocol/clientInfo":{"name":"my-agent","version":"1.0.0"}}}}'
```

Read the answers later by calling `inbox` the same way. Name your agent in `clientInfo`: it is how Guizzo tells clients apart.

## Instructions for your agent

Add these lines to `CLAUDE.md`, `AGENTS.md` or your agent's instructions, so it uses Guizzo when it should:

```markdown
## Guizzo
- Before asking about something the team may have settled,
  search with the Guizzo `recall` tool.
- When you need an answer from someone other than me, use `ask_person`
  (find people with `people`). Do not wait in a loop: tell me what
  you asked and check `inbox` later.
- Before an action that is hard to undo (sending, paying, deleting,
  deploying), use `request_approval` and act only if it is approved.
- When we settle something the team will need again, save it with
  `log_decision`, or with `remember` for a fact.
- Write only to people who would expect to hear from me, and never
  ask for passwords, card details or sensitive data. If a recipient
  is withheld (blocked or over the daily limit), do not retry another way.
```

For agents that load skills, the Guizzo skill at https://guizzo.ai/SKILL.md says when and how to use each tool. Save it as `guizzo/SKILL.md` in the skills folder your client reads, for the project or for the user. In chat apps that accept skills, the user uploads it in Settings.

## For machines

- https://guizzo.ai/llms.txt: Guizzo in a few lines, with links
- https://guizzo.ai/SKILL.md: the agent skill
- https://guizzo.ai/server.json: the MCP server's metadata, in the MCP registry format